Logging with Apache Axis2/C

In this guide Damitha Kumarage, Apache Axis2/C developer, shows how to use Axis/C's logging module effectively to write useful log messages during development and deployment. Date: Tue, 8th Jan, 2008 Level: Introductory Reads: 10084 Comments: 0 | Login or register to post comments Printer-friendly version Send to friend PDF version Post to twitter

Damitha Kumarage Technical Lead and Product Manager WSO2 Inc.

Introduction

If you are a Web services developer planning to deploy your services using the Apache Axis2/C Web services engine, this tutorial will be of interest to you. Regardless whether your Web service is a very simple one or a very complex one, having proper log messages in the service code, during development as well as production deployment, is highly useful. Logging debug messages is a tried and trusted way of debugging at development time. There are instances where log messages can be the only way to uncover a hard-to-find a bug in the code. Appropriate log messages, together with a good debugger makes a developer's life much easier. Apache Axis2/C has a built-in logging module which can be used to do just this. The aim of this tutorial is to discuss how to use this logging module effectively.

Applies To

Table of Contents

Background

When working with any development platform, the ability to write log messages is immensely useful. When I first started working on a project using Apache Axis2/C for a client, I realized how useful it would be for someone new to the Apache Axis2/C platform to have a good understanding of how to work with its logging facility. And so this tutorial came to be.

Initially I will explain how to what you need to do using the simple Axis2 HTTP server. Once you know the basics, it will be easy to understand how to carry out logging with the Axis2 Apache2 httpd module.

Log Path

When starting the simple HTTP server, you can define your log file's path as follows:

./axis2_http_server -f [your log file path]

The default log file is '$AXIS2C_HOME/logs/axis2.log' or 'axis2.log' in the current folder if the AXIS2C_HOME environment variable is not set.

Log Levels

Apache Axis2/C supports the following log levels designated by integer values:

Table:1

The Apache Axis2/C Logging API contains several functions that you can use to log messages.

AXIS2_LOG_CRITICAL(axutil_log_t * log, AXIS2_LOG_SI, axis2_char_t *format_string, ...);
AXIS2_LOG_ERROR(axutil_log_t * log, AXIS2_LOG_SI, axis2_char_t *format_string, ...);
AXIS2_LOG_WARNING(axutil_log_t * log, axis2_char_t *format_string, ...);
AXIS2_LOG_INFO(axutil_log_t * log, AXIS2_LOG_SI, axis2_char_t *format_string, ...);
AXIS2_LOG_DEBUG(axutil_log_t * log, AXIS2_LOG_SI, axis2_char_t *format_string, ...);
AXIS2_LOG_USER(axutil_log_t * log, AXIS2_LOG_SI, axis2_char_t *format_string, ...);
AXIS2_LOG_TRACE(axutil_log_t * log, AXIS2_LOG_SI, axis2_char_t *format_string, ...);

Note that AXIS2_LOG_SI is an Apache Axis2/C defined macro which is defined as #define AXIS2_LOG_SI __FILE__,__LINE__ where __FILE__ and __LINE__ are ANSI/ISO defined standard macros.

When you start the simple Apache Axis2/C server, you can set the log level you desire as follows.

./axis2_http_server -l[log level]

Here, the log level is an integer value as described in Table:1.

It is good practice to carefully consider the log level when you write a log message. For example, you need to keep in mind that the first four levels may be written to a log file during actual deployment. So you need to take some trouble to select and format the log messages belonging to those levels. It is also a good practice to write meaningful debug messages.

AXIS2_LOG_LEVEL_TRACE and AXIS2_LOG_LEVEL_USER need special attention. The AXIS2_LOG_TRACE() function is used to write trace messages for function entry and exit. If you want to use this, the choice is set at the time of compilation. I.e. you will need to build the Apache Axis2/C engine with the --enable-trace configure option. Otherwise these trace messages are not written to the log file.

The AXIS2_LOG_LEVEL_USER log level is the most important from a user's perspective. Think of the following scenario. First, assume that you don't have this kind of log level in the Apache Axis2/C engine. Suppose you are writing a very complex service for Apache Axis2/C, and you are writing debug log messages using the AXIS2_LOG_DEBUG() function. When you deploy your application in a test environment, you will find that the log file is filled with all kinds of debug messages printed from the Apache Axis2/C core, and your service log messages are hidden among the thousands of those debug lines. One solution for this is to extract your service specific log messages to a different file. The extraction can be easily done if you prefix your debug log messages with a service specific prefix as follows.

AXIS2_LOG_DEBUG(env->log, AXIS2_LOG_SI, "[your_service_prefix] This is your test debug message");

which will result in something akin to

[Tue Oct 23 10:41:42 2007] [debug] test_service.c(30) [your_service_prefix] This is your test debug message

As Apache Axis2/C comes with the AXIS2_LOG_LEVEL_USER log level, it is easier to do this. In your services, just use AXIS2_LOG_LEVEL_USER to log your debug messages. Then start the server with log level 5 as below.

./axis2_http_server -l5

When this is deployed in your test environment, only errors and critical errors from the Apache Axis2/C core are printed to the log file, apart from your user level debug messages. So you can easily read your user level log messages.

Log File Size

You can define the maximum size of the log file by using the option

./axis2_http_server -s[maximum log file size in megabytes]

When the current log file reaches this limit, it is moved as <log file name>.log.old and a new file is opened for logging. The default maximum log file size is 1MB.

When Deployed as an Apache2 httpd Module

To use logging effectively with the Apache2 httpd module, you need to know three configuration parameters related to logging.

In the httpd.conf file,

Axis2LogFile /tmp/axis2.log
Axis2LogLevel debug
Axis2MaxLogFileSize 2

You can understand the meaning of the parameters by their names. Keep in mind that the log file must contain permissions enabling the Apache2 owner to read, write, and execute. The log levels for the Apache2 httpd module are:

Table:2

When Deployed in a Simple TCP Server

For the simple TCP server, the steps to follow are the same as for the simple Axis2 HTTP server.

When starting the server, you can define your log file's path as follows:

./axis2_tcp_server -f [your log file path]

When you start the Apache Axis2/C TCP server, you can set the log level you desire as follows:

./axis2_tcp_server -l[log level]

You can define the maximum size of the log file by using the option

./axis2_tcp_server -s[maximum log file size in mega bytes]

Using Logging at a Web Service Client Code

In your client code, when you create your environment, you need to give the log file as follows:

axutil_env_t *env = axutil_env_create_all([your log file name], [log level]);

When your client runs, the log messages will be written to a file in $AXIS2C_HOME/logs/your_log_file_name.log. If instead you use

axutil_env_t *env = axutil_env_create_all([log file path and name], [log level]);

then the log will be written to the designated path. (Note: Log file path here should be a fully qualified path). Else you even can do without specifying a log file path or name.

axutil_allocator_t *allocator = NULL;
allocator = axutil_allocator_init(NULL);
axutil_env_t *env = axutil_env_create(allocator);

Since you have not given an explicit file path to write your log, where would it be written? To the standard output of course.

Writing Your Own Logging Module

It is true that the Apache Axis2/C logging module is not as versatile as something you can find on a good logging application such as Apache log4c, log4j or Commons Logging component. If you need more from your logging module in Apache Axis2/C, you can write your own logging module and compile it with Apache Axis2/C. For example, one of the projects I worked on required writing errors and critical errors to syslog. The rest of the log messages had to be written to the axis2c log file. This cannot be achieved using the built-in Apache Axis2/C logging module. Therefore, I wrote my own log.c file implementing the log API in the file axutil_log.h. You need to write two files which are similar to util/include/axutil_log_default.h(say your_log.h ) and util/src/log.c(say your_log.c). In your_log.h you need to provide constructors for your logging struct. Then in the your_log.c you can implement the logging functionlity to suite your requirements. Once you write these files you need to compile them with the axutil component. Once this is done you can plug in your new log into the Axis2/C environment as follows.

allocator = axutil_allocator_init(NULL);
error = axutil_error_create(allocator);
your_log = axutil_your_log_create(allocator, NULL, "log file name.log");
environment = axutil_env_create_with_error_log(allocator, error, your_log);

Summary

In this tutorial, we discussed how to write log messages effectively using the Apache Axis2/C logging module. When starting the Simple Axis2 Server or Simple TCP Server one can give several options related to logging. They are log file name, log file size, logging level. Similar options can be included in the Apache2 configuration file when using Apache httpd module for Axis2/C. We also discussed how to expand the Axis2/C logging functionlity by writing your own logging modules.

Resources

1. WSO2 WSF/C - is an Open Source framework for providing and consuming Web services
2. Apache Axis2/C - is an Open Source Web services engine written in C.

Author

Damitha Kumarage, Senior Software Engineer at WSO2, committer Apache Software Foundation, damitha at wso2 dot com