14 Managing and Configuring the Trace Service

Basic tracing

For basic tracing, the root logger rootdefault maintains the trace file.

Following is a list of attributes and operations for configuration and maintenance for basic tracing:

• Attribute: TracingEnabled

• Operation: attachAppender

• Operation: flushBuffers

• Operation: rollOver

Context trace

Context tracing generates log messages filtered on the context of a request,, in addition to basic tracing; for example, for a certain service provider or application. New context trace files can be added, and context filters and context categories can be applied to these files. Context categories can be added to the context trace file to log messages from one or more Oracle Communications Services Gatekeeper services. For example, to log messages from the Budget service and the Short Message Peer-to-Peer Protocol (SMPP) plug-in to a context trace file, the context categories for these are added to the context trace file. Context trace filters narrow the generated log messages to requests that match a given context filter. A context filter has predefined filter types that define what to filter on. For a given filter type, the value to match is defined. This is used for tracing on individual service providers, applications, and so on.

The workflow for defining a context trace file is:

1. In the Oracle Communications Services Gatekeeper Administration Console, choose Container Services >TraceService .

2. Select Operation: createContextTraceFile, or Operation: createRootContextTraceFile.

3. For each context category to add for the context trace file, use Operation: addContextCategory.

4. For each context filter to add, use Operation: addContextFilter.

Attribute: TracingEnabled

Scope: Cluster

Unit: Not applicable

Format: Boolean

Specifies whether trace should be enabled or not.

Use:

• true to enable tracing

• false to disable tracing

Operation: addContextCategory

Scope: Cluster

Adds a Log4J context category.

Signature:

addContextCategory(Identifier: String, Category: String)

Table 14-1 describes these parameters.

Operation: addContextFilter

Scope: Cluster

Adds one of the predefined filter types to the appender with the identified name.

The filter is a name/value pair, where the type identifies the filter type to use, and the value is the value of the filter.

All trace information that matches the filter is written to the context trace file.

When the Trace service receives information about a request, it checks if the request matches the context filter. If it matches, the trace information is written to file. All filters must match for the trace to be written.

Examples:

To add a filter that matches all requests from service provider ID SP1, set the type to SERVICE_PROVIDER and the value to SP1.

To add a filter that matches all requests from application ID APP1, set the typetto APPLICATION and the value to APP1.

Signature:

addContextFilter(identifier: String, type: String, value: String)

Table 14-2 describes these parameters.

Operation: attachAppender

Scope: Cluster

Allows adding a named appender to named loggers. Each Oracle Communications Services Gatekeeper internal service has a default FileAppender that outputs to a file with the same name as the Oracle Communications Services Gatekeeper internal service.

Signature:

attachAppender(LoggerName: String, AppenderName: String)

Table 14-3 describes these parameters.

Operation: createContextTraceFile

Scope: Cluster

Creates a new context trace file.

Signature:

createContextTraceFile(Identifier : String, Category: String, Threshold: String)

Table 14-4 describes these parameters.

Operation: createRootContextTraceFile

Scope: Cluster

Creates a new root context trace file. Adds a context trace file under root trace directory and associates it with the root logger

Signature:

createRootContextTraceFile(Identifier: String)

Table 14-5 describes this parameter.

Operation: flushBuffers

Scope: Cluster

Flushes trace buffers to file. This operation affect only FileAppenders or subclasses.

Signature:

flushBuffers()

Operation: removeContextTraceFile

Scope: Cluster

Removes a context trace file.

Signature:

removeContextTraceFile(Identifier: String)

Table 14-6 describes this parameter.

Operation: resetContextFilters

Scope: Cluster

Resets all filters associated with a context trace file.

Signature:

resetContextFilters(Identifier: String)

Table 14-7 describes this parameter.

Operation: rollOver

Scope: Cluster

Rotates log files. This will invoke the rollOver() method on all registered RollingFileAppenders.

Signature:

rollOver()

Example Log4J Configuration file

Following is an example where the following named appenders are declared:

• MyRootLogger

• MyMultimediaMessagingWarningLogger

• MyAccountContainerLogger

All these appenders use the same class, org.apache.log4j.FileAppender.

Each appender writes to a file whose name is given in the <param name="File" value="<File name>"/> element. The appenders also use the same layout class, org.apache.log4j.PatternLayout, and ConversionPattern.

The appenders are used by a set of categories, where the name attribute defines which class to trace. The categories also define which Log4J priority that shall be logged.

In the example, the following services are logged:

Everything under:

• com.bea.wlcp.wlng.account, which is the Account service.

• com.bea.wlcp.wlng.plugin.multimediamessaging, which is the Parlay X Multimedia Messaging communication service.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" debug="false">
<appender name="MyRootLogger" class="org.apache.log4j.FileAppender">
<param name="File" value="A1.log"/>
<param name="Append" value="false"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%t %-5p %c{2} - %m%n"/>
</layout>    
</appender>                 
<appender name="MyMultimediaMessagingWarningLogger" class="org.apache.log4j.FileAppender">
<param name="File" value="MMS_WARN.log"/>
<param name="Append" value="false"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%t %-5p %c{2} - %m%n"/>
</layout>    
</appender>           
<appender name="MyAccountContainerLogger" class="org.apache.log4j.FileAppender">
<param name="File" value="Account.log"/>
<param name="Append" value="false"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
</layout>    
</appender>           
<category name="org.apache.log4j.xml">
<priority value="info"/>    
</category>
<!-- log for a certain service... -->
<category name="com.bea.wlcp.wlng.account">
<priority value="DEBUG"/>
<appender-ref ref="MyAccountContainerLogger"/>
</category>  
<!-- end log for a certain service... -->
<!-- log for a certain service... -->
<category name="com.bea.wlcp.wlng.plugin.multimediamessaging">
<priority value="WARN"/>
<appender-ref ref="MyMultimediaMessagingWarningLogger"/>
</category>  
<!-- end log for a certain service... -->
<root>
<priority value="debug"/>
<appender-ref ref="MyRootLogger"/>
</root>
</log4j:configuration>