Add APLOGNO() macro for unique tags for every log message.

x-local-distclean:

	@rm -rf autom4te.cache

update-log-tags update-log-msg-tags:

	find server modules os -name \*.c|xargs perl \

		docs/log-message-tags/update-log-msg-tags

# XXX: This looks awfully platform-specific [read: bad form and style]

include $(top_srcdir)/os/os2/core.mk

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 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 <file1> ...

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.

@r@

expression rv, s;

constant char [] format;

identifier level ~= "^APLOG_\(EMERG\|ALERT\|CRIT\|ERR\|WARNING\|NOTICE\|INFO\|STARTUP\|DEBUG\)$";

identifier fn ~= "^ap_log_\(\|r\|c\|p\)error$";

@@

        fn( APLOG_MARK ,

(

        level

|

        level|APLOG_NOERROR

|

        level|APLOG_STARTUP

)

        ,rv, s

+       , APLOGNO()

        ,format, ...)

#define AP_DECLARE(x)             x

#define AP_DECLARE_NONSTD(x)      x

#define AP_CORE_DECLARE(x)        x

#define AP_CORE_DECLARE_NONSTD(x) x

#define AP_LUA_DECLARE(x)         x

#define APR_DECLARE(x)            x

#define APR_DECLARE_NONSTD(x)     x

#define APU_DECLARE(x)            x

#define APU_DECLARE_NONSTD(x)     x

#define PROXY_DECLARE(x)          x

#define DAV_DECLARE(x)            x

#define APREQ_DECLARE(x)          x

#define APREQ_DECLARE_PARSER(x)   x

#define AP_DECLARE_DATA

#define AP_MODULE_DECLARE_DATA

#define APR_DECLARE_DATA

#define APR_MODULE_DECLARE_DATA

#define APU_DECLARE_DATA

#define DAV_DECLARE_DATA

#define PROXY_DECLARE_DATA

#define AP_DECLARE_MODULE(foo)  module foo##_module

1