Chapter 19. Apache CXF Logging

Abstract

This chapter describes how to configure logging in the Apache CXF runtime.

19.1. Overview of Apache CXF Logging

Overview

Apache CXF uses the Java logging utility, java.util.logging. Logging is configured in a logging configuration file that is written using the standard java.util.Properties format. To run logging on an application, you can specify logging programmatically or by defining a property at the command that points to the logging configuration file when you start the application.

Default properties file

Apache CXF comes with a default logging.properties file, which is located in your InstallDir/etc directory. This file configures both the output destination for the log messages and the message level that is published. The default configuration sets the loggers to print message flagged with the WARNING level to the console. You can either use the default file without changing any of the configuration settings or you can change the configuration settings to suit your specific application.

Logging feature

Apache CXF includes a logging feature that can be plugged into your client or your service to enable logging. Example 19.1, “Configuration for Enabling Logging” shows the configuration to enable the logging feature.

Example 19.1. Configuration for Enabling Logging

<jaxws:endpoint...>
  <jaxws:features>
    <bean class="org.apache.cxf.feature.LoggingFeature"/>
  </jaxws:features>
</jaxws:endpoint>

For more information, see Section 19.6, “Logging Message Content”.

Where to begin?

To run a simple example of logging follow the instructions outlined in a Section 19.2, “Simple Example of Using Logging”.

For more information on how logging works in Apache CXF, read this entire chapter.

More information on java.util.logging

The java.util.logging utility is one of the most widely used Java logging frameworks. There is a lot of information available online that describes how to use and extend this framework. As a starting point, however, the following documents gives a good overview of java.util.logging:

19.2. Simple Example of Using Logging

Changing the log levels and output destination

To change the log level and output destination of the log messages in the wsdl_first sample application, complete the following steps:

  1. Run the sample server as described in the Running the demo using java section of the README.txt file in the InstallDir/samples/wsdl_first directory. Note that the server start command specifies the default logging.properties file, as follows:

    PlatformCommand +

    Windows

    start java -Djava.util.logging.config.file=%CXF_HOME%\etc\logging.properties demo.hw.server.Server

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/logging.properties demo.hw.server.Server &

    +

    The default logging.properties file is located in the InstallDir/etc directory. It configures the Apache CXF loggers to print WARNING level log messages to the console. As a result, you see very little printed to the console.

  2. Stop the server as described in the README.txt file.
  3. Make a copy of the default logging.properties file, name it mylogging.properties file, and save it in the same directory as the default logging.properties file.

  4. Change the global logging level and the console logging levels in your mylogging.properties file to INFO by editing the following lines of configuration: 

    .level= INFO
java.util.logging.ConsoleHandler.level = INFO

  5. Restart the server using the following command:

    PlatformCommand +

    Windows

    start java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.server.Server

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.server.Server &

    +

    Because you configured the global logging and the console logger to log messages of level INFO, you see a lot more log messages printed to the console.

19.3. Default logging configuration file

19.3.1. Overview of Logging Configuration

The default logging configuration file, logging.properties, is located in the InstallDir/etc directory. It configures the Apache CXF loggers to print WARNING level messages to the console. If this level of logging is suitable for your application, you do not have to make any changes to the file before using it. You can, however, change the level of detail in the log messages. For example, you can change whether log messages are sent to the console, to a file or to both. In addition, you can specify logging at the level of individual packages.

Note

This section discusses the configuration properties that appear in the default logging.properties file. There are, however, many other java.util.logging configuration properties that you can set. For more information on the java.util.logging API, see the java.util.logging javadoc at: http://download.oracle.com/javase/1.5/docs/api/java/util/logging/package-summary.html.

19.3.2. Configuring Logging Output

Overview

The Java logging utility, java.util.logging, uses handler classes to output log messages. Table 19.1, “Java.util.logging Handler Classes” shows the handlers that are configured in the default logging.properties file.

Table 19.1. Java.util.logging Handler Classes

Handler ClassOutputs to

ConsoleHandler

Outputs log messages to the console

FileHandler

Outputs log messages to a file

Important

The handler classes must be on the system classpath in order to be installed by the Java VM when it starts. This is done when you set the Apache CXF environment.

Configuring the console handler

Example 19.2, “Configuring the Console Handler” shows the code for configuring the console logger.

Example 19.2. Configuring the Console Handler

handlers= java.util.logging.ConsoleHandler

The console handler also supports the configuration properties shown in Example 19.3, “Console Handler Properties”.

Example 19.3. Console Handler Properties

java.util.logging.ConsoleHandler.level = WARNING
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

The configuration properties shown in Example 19.3, “Console Handler Properties” can be explained as follows:

The console handler supports a separate log level configuration property. This allows you to limit the log messages printed to the console while the global logging setting can be different (see Section 19.3.3, “Configuring Logging Levels”). The default setting is WARNING.

Specifies the java.util.logging formatter class that the console handler class uses to format the log messages. The default setting is the java.util.logging.SimpleFormatter.

Configuring the file handler

Example 19.4, “Configuring the File Handler” shows code that configures the file handler.

Example 19.4. Configuring the File Handler

handlers= java.util.logging.FileHandler

The file handler also supports the configuration properties shown in Example 19.5, “File Handler Configuration Properties”.

Example 19.5. File Handler Configuration Properties

java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter

The configuration properties shown in Example 19.5, “File Handler Configuration Properties” can be explained as follows:

Specifies the location and pattern of the output file. The default setting is your home directory.

Specifies, in bytes, the maximum amount that the logger writes to any one file. The default setting is 50000. If you set it to zero, there is no limit on the amount that the logger writes to any one file.

Specifies how many output files to cycle through. The default setting is 1.

Specifies the java.util.logging formatter class that the file handler class uses to format the log messages. The default setting is the java.util.logging.XMLFormatter.

Configuring both the console handler and the file handler

You can set the logging utility to output log messages to both the console and to a file by specifying the console handler and the file handler, separated by a comma, as shown in Configuring Both Console Logging and File.

Configuring Both Console Logging and File

Logging

handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

19.3.3. Configuring Logging Levels

Logging levels

The java.util.logging framework supports the following levels of logging, from the least verbose to the most verbose:

  • SEVERE
  • WARNING
  • INFO
  • CONFIG
  • FINE
  • FINER
  • FINEST

Configuring the global logging level

To configure the types of event that are logged across all loggers, configure the global logging level as shown in Example 19.6, “Configuring Global Logging Levels”.

Example 19.6. Configuring Global Logging Levels

.level= WARNING

Configuring logging at an individual package

level

The java.util.logging framework supports configuring logging at the level of an individual package. For example, the line of code shown in Example 19.7, “Configuring Logging at the Package Level” configures logging at a SEVERE level on classes in the com.xyz.foo package.

Example 19.7. Configuring Logging at the Package Level

com.xyz.foo.level = SEVERE

19.4. Enabling Logging at the Command Line

Overview

You can run the logging utility on an application by defining a java.util.logging.config.file property when you start the application. You can either specify the default logging.properties file or a logging.properties file that is unique to that application.

Specifying the log configuration file on application

start-up

To specify logging on application start-up add the flag shown in Example 19.8, “Flag to Start Logging on the Command Line” when starting the application.

Example 19.8. Flag to Start Logging on the Command Line

-Djava.util.logging.config.file=myfile

19.5. Logging for Subsystems and Services

Overview

You can use the com.xyz.foo.level configuration property described in the section called “Configuring logging at an individual package” to set fine-grained logging for specified Apache CXF logging subsystems.

Apache CXF logging subsystems

Table 19.2, “Apache CXF Logging Subsystems” shows a list of available Apache CXF logging subsystems.

Table 19.2. Apache CXF Logging Subsystems

SubsystemDescription

org.apache.cxf.aegis

Aegis binding

org.apache.cxf.binding.coloc

colocated binding

org.apache.cxf.binding.http

HTTP binding

org.apache.cxf.binding.jbi

JBI binding

org.apache.cxf.binding.object

Java Object binding

org.apache.cxf.binding.soap

SOAP binding

org.apache.cxf.binding.xml

XML binding

org.apache.cxf.bus

Apache CXF bus

org.apache.cxf.configuration

configuration framework

org.apache.cxf.endpoint

server and client endpoints

org.apache.cxf.interceptor

interceptors

org.apache.cxf.jaxws

Front-end for JAX-WS style message exchange, JAX-WS handler processing, and interceptors relating to JAX-WS and configuration

org.apache.cxf.jbi

JBI container integration classes

org.apache.cxf.jca

JCA container integration classes

org.apache.cxf.js

JavaScript front-end

org.apache.cxf.transport.http

HTTP transport

org.apache.cxf.transport.https

secure version of HTTP transport, using HTTPS

org.apache.cxf.transport.jbi

JBI transport

org.apache.cxf.transport.jms

JMS transport

org.apache.cxf.transport.local

transport implementation using local file system

org.apache.cxf.transport.servlet

HTTP transport and servlet implementation for loading JAX-WS endpoints into a servlet container

org.apache.cxf.ws.addressing

WS-Addressing implementation

org.apache.cxf.ws.policy

WS-Policy implementation

org.apache.cxf.ws.rm

WS-ReliableMessaging (WS-RM) implementation

org.apache.cxf.ws.security.wss4j

WSS4J security implementation

Example

The WS-Addressing sample is contained in the InstallDir/samples/ws_addressing directory. Logging is configured in the logging.properties file located in that directory. The relevant lines of configuration are shown in Example 19.9, “Configuring Logging for WS-Addressing”.

Example 19.9. Configuring Logging for WS-Addressing

java.util.logging.ConsoleHandler.formatter = demos.ws_addressing.common.ConciseFormatter
...
org.apache.cxf.ws.addressing.soap.MAPCodec.level = INFO

The configuration in Example 19.9, “Configuring Logging for WS-Addressing” enables the snooping of log messages relating to WS-Addressing headers, and displays them to the console in a concise form.

For information on running this sample, see the README.txt file located in the InstallDir/samples/ws_addressing directory.

19.6. Logging Message Content

Overview

You can log the content of the messages that are sent between a service and a consumer. For example, you might want to log the contents of SOAP messages that are being sent between a service and a consumer.

Configuring message content logging

To log the messages that are sent between a service and a consumer, and vice versa, complete the following steps:

  1. Add the logging feature to your endpoint’s configuration.
  2. Add the logging feature to your consumer’s configuration.
  3. Configure the logging system log INFO level messages.

Adding the logging feature to an endpoint

Add the logging feature your endpoint’s configuration as shown in Example 19.10, “Adding Logging to Endpoint Configuration”.

Example 19.10. Adding Logging to Endpoint Configuration

<jaxws:endpoint ...>
  <jaxws:features>
    <bean class="org.apache.cxf.feature.LoggingFeature"/>
  </jaxws:features>
</jaxws:endpoint>

The example XML shown in Example 19.10, “Adding Logging to Endpoint Configuration” enables the logging of SOAP messages.

Adding the logging feature to a consumer

Add the logging feature your client’s configuration as shown in Example 19.11, “Adding Logging to Client Configuration”.

Example 19.11. Adding Logging to Client Configuration

<jaxws:client ...>
   <jaxws:features>
      <bean class="org.apache.cxf.feature.LoggingFeature"/>
    </jaxws:features>
</jaxws:client>

The example XML shown in Example 19.11, “Adding Logging to Client Configuration” enables the logging of SOAP messages.

Set logging to log INFO level messages

Ensure that the logging.properties file associated with your service is configured to log INFO level messages, as shown in Example 19.12, “Setting the Logging Level to INFO”.

Example 19.12. Setting the Logging Level to INFO

.level= INFO
java.util.logging.ConsoleHandler.level = INFO

Logging SOAP messages

To see the logging of SOAP messages modify the wsdl_first sample application located in the InstallDir/samples/wsdl_first directory, as follows:

  1. Add the jaxws:features element shown in Example 19.13, “Endpoint Configuration for Logging SOAP Messages” to the cxf.xml configuration file located in the wsdl_first sample’s directory:

    Example 19.13. Endpoint Configuration for Logging SOAP Messages

    <jaxws:endpoint name="{http://apache.org/hello_world_soap_http}SoapPort"
                createdFromAPI="true">
  <jaxws:properties>
    <entry key="schema-validation-enabled" value="true" />
  </jaxws:properties>
  <jaxws:features>
    <bean class="org.apache.cxf.feature.LoggingFeature"/>
  </jaxws:features>
</jaxws:endpoint>
  2. The sample uses the default logging.properties file, which is located in the InstallDir/etc directory. Make a copy of this file and name it mylogging.properties.

  3. In the mylogging.properties file, change the logging levels to INFO by editing the .level and the java.util.logging.ConsoleHandler.level configuration properties as follows: 

    .level= INFO
java.util.logging.ConsoleHandler.level = INFO

  4. Start the server using the new configuration settings in both the cxf.xml file and the mylogging.properties file as follows:

    PlatformCommand +

    Windows

    start java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.server.Server

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.server.Server &

    +

  5. Start the hello world client using the following command:

    PlatformCommand +

    Windows

    java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.client.Client .\wsdl\hello_world.wsdl

    +

    UNIX

    java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.client.Client ./wsdl/hello_world.wsdl

    +

The SOAP messages are logged to the console.