Mailing List Archive: Apache: Docs

Error codes

Index | Next | Previous | View Threaded

rbowen at rcbowen

Nov 28, 2011, 6:29 AM

Post #1 of 8 (229 views)
Permalink

Error codes

For those of you who don't follow dev@ closely, please take a look at http://markmail.org/message/tltkphtp327kep6i

Summary: I'd like to put error codes, of the form AH1234 (AH = Apache httpd and 1234 is an arbitrary number) into the calls to *_log_?error so that we can have per-error detailed documentation that is easily Google-able.

This is a multi-step process that looks like this:

1) Create file in svn that lists sequential error codes so that we know what the next number is. The file should list error code and the file in which it is used. Should probably also list line number, although that changes over time, so it's approximate.
2) Find all calls to *_log_?error (Stefan says there's 2700+ such calls!) and add the next error code to the beginning of the message. In parens, perhaps?. Update the file in #1.
3) Add a description of the error condition, and if known, the remediation, to the Wiki. Update the file in #1 with the URL of that document. We probably want one URL per error code. We're counting on the error code being unique-enough to be google-able, so the actual URL doesn't matter a lot at this point.
4) Eventually, when we have a good body of these error documents, we should figure out where they fit in the official documentation, and move them there, complete with a style sheet and standard page elements. (Module, error_level, message, meaning, remediation, etc.)

Presumably we would do this initially in trunk, and based on how well the effort goes, we can propose patches for 2.4 and 2.2.

Comments?

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache

i.galic at brainsware

Nov 28, 2011, 6:39 AM

Post #2 of 8 (216 views)
Permalink

Re: Error codes [In reply to]

----- Original Message -----
> For those of you who don't follow dev@ closely, please take a look at
> http://markmail.org/message/tltkphtp327kep6i
>
>
> Summary: I'd like to put error codes, of the form AH1234 (AH = Apache
> httpd and 1234 is an arbitrary number) into the calls to
> *_log_?error so that we can have per-error detailed documentation
> that is easily Google-able.
>
>
> This is a multi-step process that looks like this:
>
>
> 1) Create file in svn that lists sequential error codes so that we
> know what the next number is. The file should list error code and
> the file in which it is used. Should probably also list line number,
> although that changes over time, so it's approximate.
> 2) Find all calls to *_log_?error (Stefan says there's 2700+ such
> calls!) and add the next error code to the beginning of the message.
> In parens, perhaps?. Update the file in #1.
> 3) Add a description of the error condition, and if known, the
> remediation, to the Wiki. Update the file in #1 with the URL of that
> document. We probably want one URL per error code. We're counting on
> the error code being unique-enough to be google-able, so the actual
> URL doesn't matter a lot at this point.

http://s.apache.org/AH1234

The only question would be, what to point that to :)

> 4) Eventually, when we have a good body of these error documents, we
> should figure out where they fit in the official documentation, and
> move them there, complete with a style sheet and standard page
> elements. (Module, error_level, message, meaning, remediation, etc.)
>
>
> Presumably we would do this initially in trunk, and based on how well
> the effort goes, we can propose patches for 2.4 and 2.2.
>
>
> Comments?
>
>
>
>
>
>
>
> --
> Rich Bowen
> rbowen [at] rcbowen :: @rbowen
> rbowen [at] apache

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

rbowen at rcbowen

Nov 28, 2011, 6:46 AM

Post #3 of 8 (217 views)
Permalink

Re: Error codes [In reply to]

On Nov 28, 2011, at 9:39 AM, Igor Galić wrote:

>
> http://s.apache.org/AH1234
>
> The only question would be, what to point that to :)

That would be awesome if 1) that URL is available, 2) whoever manages s.apache.org doesn't mind our doing this (I presume not, but I don't actually know what the longevity of those links is) and 3) we can update those URLs later when the doc moves to the official docs. I don't actually know anything about s.apache.org. I'll attempt to educate myself.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache

i.galic at brainsware

Nov 28, 2011, 6:50 AM

Post #4 of 8 (219 views)
Permalink

Re: Error codes [In reply to]

----- Original Message -----
>
>
>
> On Nov 28, 2011, at 9:39 AM, Igor Galić wrote:
>
>
>
> http://s.apache.org/AH1234
>
> The only question would be, what to point that to :)
>
>
>
> That would be awesome if 1) that URL is available, 2) whoever manages
> s.apache.org doesn't mind our doing this (I presume not, but I don't
> actually know what the longevity of those links is) and 3) we can
> update those URLs later when the doc moves to the official docs. I
> don't actually know anything about s.apache.org . I'll attempt to
> educate myself.

infrastructure-private@ or infrastructure-dev@ should know the answer
to that.

> --
> Rich Bowen
> rbowen [at] rcbowen :: @rbowen
> rbowen [at] apache

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

sf at sfritsch

Nov 28, 2011, 8:21 AM

Post #5 of 8 (210 views)
Permalink

Re: Error codes [In reply to]

On Monday 28 November 2011, Rich Bowen wrote:
> 1) Create file in svn that lists sequential error codes so that we
> know what the next number is. The file should list error code and
> the file in which it is used. Should probably also list line
> number, although that changes over time, so it's approximate.

The file names and line numbers can easily be extracted by a script (I
am volunteering to write it), no need to track these manually.

> 2) Find all calls to *_log_?error (Stefan says there's 2700+ such
> calls!) and add the next error code to the beginning of the
> message. In parens, perhaps?. Update the file in #1.

I would prefer "AH1234: Don't panic". It's one character shorter than
"(AH1234) Don't panic" and horizontal screen space is always short
when viewing the error log.

A question on procedure: Do you want to add all error codes at once
and then fill in the descriptions or add the error codes as the
documentation evolves? If the former, some scripting would probably
save a lot of work, too.

I am not sure that every debug message needs a code, maybe one could
at first only tag those of level info or higher? Or maybe even
warning?

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

rbowen at rcbowen

Nov 28, 2011, 8:29 AM

Post #6 of 8 (212 views)
Permalink

Re: Error codes [In reply to]

On Nov 28, 2011, at 11:21 AM, Stefan Fritsch wrote:

> On Monday 28 November 2011, Rich Bowen wrote:
>> 1) Create file in svn that lists sequential error codes so that we
>> know what the next number is. The file should list error code and
>> the file in which it is used. Should probably also list line
>> number, although that changes over time, so it's approximate.
>
> The file names and line numbers can easily be extracted by a script (I
> am volunteering to write it), no need to track these manually.

Excellent. Time saving is always a good thing. :)

>
>> 2) Find all calls to *_log_?error (Stefan says there's 2700+ such
>> calls!) and add the next error code to the beginning of the
>> message. In parens, perhaps?. Update the file in #1.
>
> I would prefer "AH1234: Don't panic". It's one character shorter than
> "(AH1234) Don't panic" and horizontal screen space is always short
> when viewing the error log.

Sounds good to me.

>
> A question on procedure: Do you want to add all error codes at once
> and then fill in the descriptions or add the error codes as the
> documentation evolves? If the former, some scripting would probably
> save a lot of work, too.

If it can be done all at once with a script, that would be great. The only concern from there would be the ease of applying that change to earlier versions. Presumably the trunk -> 2.4 patch would work pretty well, but -> 2.2 would take a lot of work. Not sure that it would be worth it, though. I'm in favor of making this a 2.4-only effort.

>
> I am not sure that every debug message needs a code, maybe one could
> at first only tag those of level info or higher? Or maybe even
> warning?

Ah. Good point. Yes, we should probably skip stuff in Debug, unless it makes sense to add them on a case-by-case basis later on. (Not sure what would justify that, but perhaps some messages are more common than others? More important? More � something.) I would say warn and higher, but perhaps it merits further discussion. Adding them to info now might save hassle later on if we wanted to further document those, and costs us nothing now, except for 6 characters in the log message. What do folks think?

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache

sf at sfritsch

Nov 29, 2011, 3:30 PM

Post #7 of 8 (207 views)
Permalink

Re: Error codes [In reply to]

On Monday 28 November 2011, Rich Bowen wrote:
> On Nov 28, 2011, at 11:21 AM, Stefan Fritsch wrote:
> > A question on procedure: Do you want to add all error codes at
> > once and then fill in the descriptions or add the error codes as
> > the documentation evolves? If the former, some scripting would
> > probably save a lot of work, too.
>
> If it can be done all at once with a script, that would be great.
> The only concern from there would be the ease of applying that
> change to earlier versions. Presumably the trunk -> 2.4 patch
> would work pretty well, but -> 2.2 would take a lot of work. Not
> sure that it would be worth it, though. I'm in favor of making
> this a 2.4-only effort.
>
> > I am not sure that every debug message needs a code, maybe one
> > could at first only tag those of level info or higher? Or maybe
> > even warning?
>
> Ah. Good point. Yes, we should probably skip stuff in Debug, unless
> it makes sense to add them on a case-by-case basis later on. (Not
> sure what would justify that, but perhaps some messages are more
> common than others? More important? More … something.) I would say
> warn and higher, but perhaps it merits further discussion. Adding
> them to info now might save hassle later on if we wanted to
> further document those, and costs us nothing now, except for 6
> characters in the log message. What do folks think?

Currently my scripts produces:

http://people.apache.org/~sf/error-msg-numbers.diff
http://people.apache.org/~sf/error-msg-numbers.list

This is level info and up, but that is easily changed.

The script still misses all occurences where the format string is
split into several parts (e.g. over several lines), where the loglevel
is not constant but a variable, and possibly some others.

Are other folks comfortable with going this way? Add it to 2.4?

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

rbowen at rcbowen

Nov 29, 2011, 4:04 PM

Post #8 of 8 (209 views)
Permalink

Re: Error codes [In reply to]

On Nov 29, 2011, at 6:30 PM, Stefan Fritsch wrote:

> Currently my scripts produces:
>
> http://people.apache.org/~sf/error-msg-numbers.diff
> http://people.apache.org/~sf/error-msg-numbers.list
>
> This is level info and up, but that is easily changed.
>
> The script still misses all occurences where the format string is
> split into several parts (e.g. over several lines), where the loglevel
> is not constant but a variable, and possibly some others.
>
> Are other folks comfortable with going this way? Add it to 2.4?

+1

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads