Logging Quick Guide 

This Quick Guide gives an overview of:

●      general rules that a developer has to keep in mind when using the logging infrastructure

●      preparation steps

●      usage of logging and tracing

●      configuration considerations and steps

●      performance remarks

General Rules

●      Bear 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 the SAP’s organizational structure but in areas according to his/her administration tasks. A developer, however, wants to see the details of the control flow.

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 corresponds to administration tasks and are shared between different applications. Locations refer to certain points in the coding and can be identified with package-, class-, or function-names.

●      During normal operation developers and support engineers are not looking on a running system. The administrator, however, 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 AS Java configuration no traces are written during normal operation, but logs of severity INFO and higher are.

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

●      Any error message (with severity ERROR or FATAL) is recommended to be written as a log message.

●      Log files must have an extension .log, trace files – an extension .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, there are the following predefined subcategories:

/System/Database

/System/Network

/System/Server

/System/Security

/System/UserInterface

/System/Audit (only for audit-traces written by BaseException.trc)

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 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 final clause.

    LOCATION.entering(METHOD);

  LOCATION.exiting(METHOD);

Configuration Considerations

●      The default severity setting for categories has to be INFO.

Therefore, all log messages with severity INFO or higher will be written.

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

Therefore, if you have exceptions that you always want to trace, use the traceThrowableT method of the Location class.

You can modify your logging configuration at runtime, using the SAP NetWeaver Administrator.

More information: Log Configuration with the SAP NetWeaver Administrator.

Performance remarks

●      If you have parameters, never build strings yourself, always use the {n}-replacement.

●      If you have to make calculations for traces, use the following: LOCATION.beLogged(severity).