Logging Quick Guide 

This Quick Guide gives an overview of

·        general rules that a developer has to take into consideration when using the logging infrastructure

·        preparation steps

·        usage of logging and tracing

·        configuration considerations and steps

·        performance remarks

General Rules

·        Keep in mind the difference between logs and traces. Logs are mainly addressed to an administrator of a customer system, traces – to a developer and support organization. An administrator is not interested in the details of the software architecture and of SAP’s organizational structure, but in areas according to his/her administration tasks. A developer on the other hand wants to see the details of the control flow. Of course, a log file may also be a good starting point for error analysis done by support engineers.

·        Logs are written to Categories, and traces – to Locations. Categories are semantical topics corresponding roughly to administration tasks. Locations refer to certain points in the coding and can be identified with package-, class-, or function-names.

·        Category names are not application names or names of org-units. In principle categories are shared between different applications. If you end up with categories, which correspond to your software structure, then your category design is probably wrong!

·        During normal operation developers and supporters are not looking on a running system. On the other hand the administrator has to check the system regularly. This implies that traces have not to be shown during normal operation, but logs do.

·        For performance reasons in the current J2EE Engine configuration no traces are written during normal operation, but logs of severity INFO and higher are.

·        To emphasize it again: Write into logs only such messages, which are important for an administrator, who supervises the system during normal operation. Write into traces everything, which might be important to trace erroneous behavior.

·        Messages with severity DEBUG and PATH must be written as traces, not as log messages.

·        Any error message (of severity ERROR or FATAL) has to be written as a log message. It is recommended that messages of severity ERROR or FATAL must not be written as trace messages

·        Log files must have an extension .log, trace files – .trc.

·        Use always the exception framework as a basis to define your own exceptions.

 

Preparation Steps

...

       1.      Log records are written to Categories. There are three top Categories:

/System

/Applications

/Performance

To the /System category all system related log messages belong. These logs are typically observed by a system administrator, who is not supposed to have any knowledge of the business processes.

To the /Applications category on the other hand all messages related to the business logic belong.

The /Performance category is reserved for the Single Activity Trace.

Below the /System category, we have the following predefined subcategories:

/System/Database

/System/Network

/System/Server

/System/Security

/System/UserInterface (since SP5)

/System/Audit     

only for audit-traces written by BaseException.trace

For convenience and to avoid unnecessary object creation, the following static variables are defined:

com.sap.tc.logging.Category.SYS_DATABASE;

com.sap.tc.logging.Category.SYS_NETWORK;

com.sap.tc.logging.Category.SYS_SERVER;

com.sap.tc.logging.Category.SYS_SECURITY;

com.sap.tc.logging.Category.APPLICATIONS;

com.sap.tc.logging.Category.SYS_USER_INTERFACE;

       2.      Trace records are written to Locations. In every important class, create a reference to a Location, which corresponds to the fully qualified name of this class:

private static final Location LOCATION =

location.getLocation(Locking.class);

Use a static String object to hold the name of the method.

String METHOD = “createLock(String)”;

Usage

...

       1.      If you have a message, which is important for the customer or admin, write a log record:

//this creates the category /Applications/MyApp

       2.      private static final Category CATEGORY =

Category.getCategory(Category.APPLICATIONS, "MyApp");

    CATEGORY.infoT(LOCATION, METHOD,

“User {0} logged in”, new Object[] { user });

For the other severities, use the corresponding methods warningT, errorT, fatalT.

       3.      If you have a message, which might be useful for the developer or support, write a trace record:

LOCATION.infoT(METHOD, “User {0} started transaction”,

new Object[] { user });

For the other severities, use the corresponding methods debugT, pathT, warningT, errorT.

       4.      For nontrivial methods it is convenient to trace the entry and the exit of the method. If you do trace the entry it is urgently required that you trace the exit to! If your method might throw an exception, you have to trace the exit in a finally clause.

    LOCATION.entering(METHOD);

  LOCATION.exiting(METHOD);

 

Configuration Considerations

·        The default severity setting for categories has to be INFO (so all log messages with severity INFO or higher will be written)

·        The default severity setting for locations has to be ERROR.

  => if you have Exceptions, which you always want to trace, use the traceThrowableT method of the Location class.

·        You can manually edit the log-configuration.xml file of your Categories or Location and deploy it with libraries, interfaces, or applications. To deploy a logging configuration together with your component, you have to include the XML file into its corresponding archive. The name of the XML file must be "log-configuration.xml". It must follow a particular syntax. For more information, see log-configuration.dtd.

If the log-configuration.xml file is to be deployed with an application, it must be placed in the META-INF directory of the application's archive. Currently, support for such a file located in the root of the archive is also available, but only for a backward compatibility.

If it is to be deployed with a library or interface, it must be placed in the subdirectory(ies) called "dispatcher(and/or server)/descriptors". Whether there will be an XML file only in the "dispatcher/descriptors", only in the "server/descriptors", or in both directories, depends on what kind of cluster node the component is deployed to.

·        You can use the SAP Netweaver Developer Studio to add a log-configuration.xml file to your project and configure it during development. For more information, see Log Configuration Using the SAP Netweaver Developer Studio.

You can modify your logging configuration at runtime using the Visual Administrator. For more information, see Logging Configuration Using the Visual Administrator.

Performance remarks

·        If you have parameters, never build Strings yourself, always use the {n}-replacement

·        If you have to make calculations for traces, check first if the tracing is active …

  LOCATION.beLogged(severity)