# System Administrator’s Guide

# Managing and Configuring the Trace Service

The following section describes how to configure and manage the Trace Service in Oracle Communications Services Gatekeeper:

- Introduction to the Trace Service
- Reference: Attributes and Operations for Trace Service
- Log4J Hierarchies, Loggers, and Appenders
- Configuring Trace for Access Tier servers
- Using the Log4J Configuration File

## Introduction to the Trace Service

The trace service is based on Log4J. Oracle Communications Services Gatekeeper maintains the log file, named default.log. Each service instance writes to this log file, the local file system of the server on which it executes. The trace service writes log files in the directory `$DOMAIN_HOME/servers/<server name>/trace.`

### Basic tracing

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

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

- Attribute: TracingEnabled
- Operation: attachAppender
- Operation: flushBuffers
- Operation: rollOver

### Context trace

In addition to basic tracing, context tracing generates log messages filtered on the context of a request, for example 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 in order to log messages from one or more Oracle Communications Services Gatekeeper services. For example, to log messages from the budget service and the 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 pre-defined filter types that defines 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 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 Operation: addContextCategory.
4. For each context filter to add, use Operation: addContextFilter

Below is a list of attributes and operations for configuration and maintenance for context tracing:

- Operation: addContextCategory
- Operation: addContextFilter
- Operation: createContextTraceFile
- Operation: createRootContextTraceFile
- Operation: removeContextTraceFile
- Operation: resetContextFilters

## Reference: Attributes and Operations for Trace Service

Managed object: Container ServicesTraceService

MBean: com.bea.wlcp.wlng.log.management.TraceServiceMBean

Below is a list of attributes and operations for configuration and maintenance:

- Attribute: TracingEnabled
- Operation: addContextCategory
- Operation: addContextFilter
- Operation: attachAppender
- Operation: createContextTraceFile
- Operation: createRootContextTraceFile
- Operation: resetContextFilters
- Operation: rollOver

### Attribute: TracingEnabled

Scope: Cluster

Unit: n/a

Unit: n/a

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 13-1 addContextCategory
addContextCategory
Parameter | Description
--- | ---
Identifier | ID of a context trace file.
Category | The Log4J category. The category is the package name, including sub-packages, to trace on. For example, to trace on the SMPP plug-in, enter com.bea.wlcp.wlng.plugin.sms.smpp

### Operation: addContextFilter

Scope: Cluster

Adds one of the pre-defined 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, the type shall be defined as SERVICE_PROVIDER and the value shall be set to SP1.

To add a filter that matches all requests from application ID APP1, the type shall be defined as APPLICATION and the value shall be set to APP1.

Signature:

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

Table 13-2 addContextFilter
addContextFilter
Parameter | Description
--- | ---
Identifier | ID of a context trace file.
Type | One of the defined types to filter on. Use: SERVICE_PROVIDER to filter on service provider ID. APPLICATION to filter on application ID. APPLICATION_INSTANCE to filter on application instance ID. SESSION to filter on session ID. TRANSACTION to filter on transaction ID.
Value | Value to filter on for this filter type.

### Operation: attachAppender

Scope: Cluster

Allows adding 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 13-3 attachAppender
attachAppender
Parameter | Description
--- | ---
LoggerName | Name of logger.
AppenderName | Name of Oracle Communications Services Gatekeeper internal service to attach the appender to.

### Operation: createContextTraceFile

Scope: Cluster

Creates a new context trace file.

Signature:

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

Table 13-4 createContextTraceFile
createContextTraceFile
Parameter | Description
--- | ---
Identifier | ID of the context trace file to create. Also the name of trace file. The filename has the suffix `.log`. Must be unique per managed server.
Category | The Log4J category.
Threshold | The threshold for the context trace file. Valid values are: OFF FATAL ERROR WARN INFO DEBUG TRACE ALL

### 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 13-5 createRootContextTraceFile
createContextTraceFile
Parameter | Description
--- | ---
Identifier | ID of the context trace file. Also the name of trace file. The filename has the suffix `.log`. Must be unique per managed server.

### Operation: flushBuffers

Scope: Cluster

Flushes trace buffers to file. This method has effect only on FileAppenders or subclasses.

Signature:

`flushBuffers()`

Table 13-6 flushBuffers
flushBuffers
Parameter | Description
--- | ---
- | -

### Operation: removeContextTraceFile

Scope: Cluster

Removes a context trace file.

Signature:

`removeContextTraceFile(Identifier: String)`

Table 13-7 removeContextTraceFile
removeContextTraceFile
Parameter | Description
--- | ---
Identifier | ID of context trace file to remove.

### Operation: resetContextFilters

Scope: Cluster

Resets all filters associated with a context trace file.

Signature:

`resetContextFilters(Identifier: String)`

Table 13-8 resetContextFilters
resetContextFilters
Parameter | Description
--- | ---
Identifier | ID of context trace file to reset all filters for.

### Operation: rollOver

Scope: Cluster

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

Signature:

`rollOver()`

Table 13-9 rollOver
rollOver
Parameter | Description
--- | ---
- | -

## Log4J Hierarchies, Loggers, and Appenders

There is a set of Log4J Dynamic MBeans shipped with Oracle Communications Services Gatekeeper that come by default with appenders. One Log4J hierarchies is defined and displayed in the following entries in the Oracle Communications Services Gatekeeper management console under Log4J:

- log4j:hiearchy=default

To the default hierarchy, the logger rootDefault is connected, also displayed in the list:

- log4j:Location=AdminServer,logger=rootDefault

Additional loggers can be added, and additional appenders can be added to the loggers. It is possible to change both the priority of the logger and the appender to use. Parameters for the loggers and appenders can be configured.

A set of default appenders are defined:

- log4j:appender=default,Location=AdminServer
- log4j:appender=default,Location=AdminServer

Note: | The Log4J attributes are dynamic and not persisted.

To persist Log4J settings, use the configuration file:

    $DOMAIN_HOME/log4j/log4jconfig.xml

## Configuring Trace for Access Tier servers

Trace configuration for Network Tier servers is performed via the Oracle Communications Services Gatekeeper Administration Console, in <Server Name>Log4J. For Access Tier servers, there is no management attributes or operations exposed in the Oracle Communications Services Gatekeeper Administration Console. This configuration must be done directly on the MBeans using a JMX-based management console such as JConsole or using WLST.

For example, if using WLST, connect to the MBean server as described in WebLogic Scripting Tool (WSLT) and change to the custom tree where Oracle Communications Services Gatekeeper MBeans are located. Change to the Log4J directory: `cd(`'`log4J`'`)`

The settings for the Access Tier servers can be changed in the following directories:

- log4j:appender=default
- log4j:appender=default,layout=org.apache.log4j.TTCCLayout
- log4j:hiearchy=default
- log4j:logger=rootdefault

For example, to change the trace level for the Access Tier servers for the appender log4j:appender=default to WARN:

1. `cd('log4j:appender=default')`
2. `set('threshold','WARN')`

## Using the Log4J Configuration File

In addition to using the Log4J MBeans, trace can be configured using the file:

`$DOMAIN_HOME/log4j/log4jconfig.xml`

The file contains by default an empty skeleton.

The settings define in this file are updated every 30th second.

The ordering of the elements must be taken into account. Appenders must be declared before categories.

When using appenders that writes to file, the files are stored in `$DOMAIN_HOME`.

### Example Log4J Configuration file

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

- MyRootLogger
- MyMultimediaMessagingWarningLogger
- MyAccountContainerLogger

The all use the same class, `org.apache.log4j.FileAppender`.

Each appender writes to a file which name is given in the `<param name="File" value="<File name>"/>` element. The appenders also use the same layout class, `org.apache.log4j.PatternLayou`t, 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`, that is the Account service.
- `com.bea.wlcp.wlng.plugin.multimediamessaging`, that is the Parlay X Multimedia Messaging communication service.

is logged.

Listing 13-1 Example log4jconfig.xml

    <?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>