docs/log-message-tags/README

This directory contains the infrastructure to create unique tags for error log
messages. In the source, the tags use the APLOGNO(02182) macro where the argument
is a 5 digit decimal number. The macro expands to "AH02182: ".

The idea is that these tags help users finding useful information with search
engines. The use of the macro is intended to prevent search engine hits at
svn.apache.org or the svn commit mailing list.

Basic rules:

- Only messages of level debug and higher should get tags.
- If the same message is logged at two different places in httpd, assign two
  different tags.
- If the context changes, where a message is generated, assign a new tag.
- If only the text of the message changes (e.g. making it more verbose), keep
  the tag.
- Never reuse tags that have been removed, numbers are cheap.
- Use the same tags in different branches.
- The tag AH02182 is reserved for examples.
- Currently only modules included in the httpd distribution should do this.

TODO: Define what third-party modules should do.

How to add a few new tags:
==========================

When adding new error messages, it is easiest to just add empty APLOGNO() tags
and then run the update-log-msg-tags perl script on the source file. This will
look into docs/log-message-tags/next-number to determine the next tag to be
used, fill in all empty APLOGNO() tags, and update
docs/log-message-tags/next-number accordingly.

The toplevel Makefile has a target update-log-msg-tags to run the script
over all *.c files in the source tree.

The script also puts a list of all messages in docs/log-message-tags/list.
This list should not be committed to svn.


How to add lots of new tags:
============================

In order to find candidate calls to ap_log_*error, coccinelle's spatch command
can be used.  It will add empty APLOGNO() tags where the loglevel is a
constant and is of level debug or above. Then, update-log-msg-tags can be used
to add numbers to the APLOGNO() tags. The invocation for spatch is:

  % DIR=docs/log-message-tags
  % spatch --sp_file $DIR/find-messages.cocci --in_place --macro_file $DIR/macros.h FILESTOCHECK

where FILESTOCHECK is the list of C files you want spatch to work on.

After the initial addition of tags, calling spatch on the same file again may
be a bad idea. But it may still be useful when adding larger pieces of code to
httpd.

Depending on the build details of coccinelle, the regular expressions in the
spatch files can either be in normal PCRE form, or in OCAML Str regexp form.
If your build only supports the latter, you will have to put a backslash in
front of every '(', ')' and '|' that is part of a regexp in the cocci file.

Example:
- original lines
identifier level =~ "^APLOG_(EMERG|ALERT|CRIT|ERR|WARNING|NOTICE|INFO|STARTUP|DEBUG)$";
identifier fn =~ "^ap_log_(|r|c|p)error$";
- new lines
identifier level =~ "^APLOG_\(EMERG\|ALERT\|CRIT\|ERR\|WARNING\|NOTICE\|INFO\|STARTUP\|DEBUG\)$";
identifier fn =~ "^ap_log_\(\|r\|c\|p\)error$";

To finally replace the empty "APLOGNO()," with a real number, run:

  % perl docs/log-message-tags/update-log-msg-tags FILESTOFIX