>XINS: Splitting out Logdoc?

>Talking to Anthony Goubard yesterday (of JLearnIt and AntCommander fame), I realized that adding features like SMTP– and SMS-support to a Web Services framework like XINS can hardly be considered good separation of concerns. So I definitely need to revise my XINS 3.0 wishlist.

Instead, it may be a much better idea to make XINS focus more on the Web Services functionality and split some technologies out. The main candidates seem to be Logdoc and the ServiceCaller framework:
In the picture the arrows indicate dependencies. So XINS would depend on Logdoc and the ServiceCaller framework and the latter would also depend on Logdoc.

Logdoc: What is it?
In this post I will focus on Logdoc.

So what is Logdoc and why would we want to separate that out from XINS? Is it useful for other projects as well?

IMHO the answer is “yes”. Logdoc is a logging system based on the infamous Apache Log4J library that offers some features over Log4J:

• registered logging categories: there is an explicit list of all logging categories, with documentation;
• unique log messages: each log message is in a specific category and gets a specific number; this allows system administrators to enable or disable individual messages;
• multi-locale: it is straight-forward to add a new language for log messages;
• separation of concerns: the code does not bother with log levels, translations and categories, instead it just deals with a single log message (identified by ID) and it’s parameters.

Logdoc code example
Here is an example of a piece of Java code that uses Logdoc, from the HTTPServiceCaller class (javadoc/source):

// Unknown host
if (exception instanceof UnknownHostException) {
 Log.log_1102(url, params, duration);

Notice that there is no category, no creation of objects and no language-specific stuff.

Logdoc definitions
The key to the Logdoc system is the definition of categories and entries in XML. Every entry is within a single category. Translations can be specified in separate files, one per language/locale. So for example, for the XINS/Java Server Framework, the following files define all logdoc entries and their translations:

• src/logdoc/server/log.xml – defines all categories and contained entries; each entry has a unique number, it specified a log level and optionally some parameters;
• src/logdoc/server/translation-bundle-en_US.xml – defines all U.S. English translations for the log messages defined in the log.xml file;
• src/logdoc/server/translation-bundle-fr_FR.xml – defines all French (France) translations;

Adding a new set of translations is as easy as adding one line to the log.xml and one translation-bundle-xx_XX.xml file, where xx is the ISO language code and XX is the ISO country code.

Now from these specifications, both code and documentation is automatically generated, XINS-style. Here is an example of generated Logdoc documentation:

• Logdoc documentation for the XINS/Java Server Framework

Notice that there are 2 ways to find log entries: by category and by ID (see the Logdoc entry list link at the top).

More information
For more information on Logdoc, check out the section titled “Managing logs” in the XINS User Guide.

 

>Log colorizing

>Do you ever look at log files? A lot? Then, like me, your brains could use a little help to easen the interpretation of all the letters and digits that are scrolling by. This is where a log colorizer helps.

I was looking for a log colorizer tool, but found it hard to find one using Google, until I found this article: Log colorizing on a Dreamhost account. Although it’s written for Dreamhost (a US service provider), the article seemed sufficiently generic for use on other *NIX systems (like my Apple).

Note: the PCRE version mentioned in the article is outdated. Just go the the tools’ website to check out which version is now the current stable release.

Summarized: All you need is 2 akwardly named tools:

• PCRE – ‘Perl Compatible Regular Expressions’
• CCZE – a C port of RASZi’s colorize.

I thought I might be lucky and tried DarwinPorts to see if that would support CCZE, but it doesn’t:

~$ sudo port install ccze
Password:
Error: Port ccze not found

For me, PCRE installed like a breeze. But CCZE failed to build:

make -C src all
cc -c  -I. -I. -I.. -DPATCHLEVEL=\"1\" -DSYSCONFDIR=\"/Users/ernst/usr//etc\" -D_GNU_SOURCE=1 -DPKGLIBDIR=\"/Users/ernst/usr//lib/ccze\" -DHAVE_SYSTEM_H=1 -DBUILTIN=1 -Wshadow -Wpointer-arith -Waggregate-return -Wstrict-prototypes -Wmissing-prototypes -Wcast-qual -Wbad-function-cast -Wsign-compare -Wchar-subscripts -Wcomment -Wformat -Wformat-nonliteral -Wformat-security -Wimplicit -Wmain -Wmissing-braces -Wparentheses -Wreturn-type -Wswitch -Wmulticharacter -Wmissing-noreturn -Wmissing-declarations  -g -O2 -I/Users/ernst/usr//include ccze.c
cc1: error: unrecognized command line option "-Wmulticharacter"
make[1]: *** [ccze.o] Error 1
make: *** [all-recursive] Error 2

Here’s my CC version:

$ cc --version
i686-apple-darwin8-gcc-4.0.1 (GCC) 4.0.1 (Apple Computer, Inc. build 5367)
Copyright (C) 2005 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

When I resolved the issue by removing the flag from src/Makefile, I got another error:

i686-apple-darwin8-gcc-4.0.1: unrecognized option '-shared'
/usr/bin/ld: Undefined symbols:
_main
_ccze_addstr
_ccze_space
collect2: ld returned 1 exit status
make[1]: *** [apm.so] Error 1
make: *** [all-recursive] Error 2

At that point, I gave up on CCZE.