IBM Developer

Tutorial

Implement advanced logging in IBM Sterling OMS with Log4j

Learn how to configure and manage Log4j settings in IBM Sterling OMS for effective logging and troubleshooting

By Satendra Patel, Mohamed Jawahar Hussain

On this page

Logging is an important part of managing enterprise applications. It helps to identify issues and provides details for troubleshooting. IBM Sterling Order Management System (OMS) uses the Log4j utility to record trace and debug information in log files.

Based on business needs, you can modify the Log4j configuration file to control the log file location and logging level. You might also want to store Application, Agent, and Integration server logs in different locations or create custom Java loggers for specific requirements.

To learn more about Log4j, check out the "What is the Log4j vulnerability?" article.

This tutorial explains how to integrate and configure Log4j1 and Log4j2 for customized and efficient logging in IBM Sterling OMS.

Default logging behavior in IBM Sterling OMS

Log4j1

By default, IBM Sterling OMS refers to the yfs.properties file for the Log4j configuration property:

log4j.configuration=/resources/log4jconfig.xml

In the log4jconfig.xml file, the default log file path is defined as:

<param name="file" value="<INSTALL_DIR>/runtime/logs/sci${IBM_LOG_FILE}.log"/>

When trace is enabled for any out-of-the-box API or custom service, logs are written to the sci${IBM_LOG_FILE}.log file. The log file is rotated based on parameters that are specified in the configuration. If you need to customize Log4j, you can modify the configuration as required.

The SCIAppender is a Sterling-specific implementation that extends Log4j’s standard behavior and controls where logging statements are written.

  • ${IBM_LOG_FILE} is a placeholder that is used for a dynamic file name, such as an agent or integration server name.
  • The IBM_LOG_FILE property is read as a Java system property and passed as a JVM parameter.

You can configure the logger to send different categories of messages to different destinations. Categories are organized hierarchically, allowing inheritance. Each category can also be assigned a priority to indicate the severity level.

Log4j2

By default, the Log4j2 configuration in Sterling OMS is handled programmatically during application startup and does not read directly from an XML file like Log4j1.

Multiple file appenders and one console appender are configured for different Java packages in Sterling OMS.

To view the complete configuration, refer to the log4j2.xml.sample file located in the <runtime>/properties directory.

Default server log locations:

  • Application server: <runtime>/logs/sci**.log

  • Agent/Integration server: <runtime>/logs/agentserver**.log

Sterling OMS uses log4j2_extra.xml located in <runtime>/properties instead of the standard log4j2.xml file that is used by Apache Log4j2. By default, this file is empty and does not override the built-in configuration. Any content that you add to log4j2_extra.xml is appended to the default settings.

Steps to customize Log4j1

  1. Copy the application-provided log4jconfig.xml file from:

    <INSTALL_DIR>/runtime/resources/

    to

    <INSTALL_DIR>/runtime/extensions/global/resources/

    and rename it as log4jconfig_custom.xml.

  2. In the customer_overrides.properties file, add the following property:

    yfs.log4j.configuration=/resources/extn/log4jconfig_custom.xml

  3. You can modify the Log4j appender to suit your business requirements. The following table shows the configuration before and after customization.

    alt

    The ALL appender has been customized by adding and modifying key parameters.

    • <param name="Append" value="true"/>

      Controls whether new log entries are added to the existing file or if the file is overwritten when the application restarts.

      • true: Append new logs.
      • false: Overwrite the file on restart.

    • <param name="MaxBackupIndex" value="2"/> Specifies how many backup log files to keep when the log reaches its maximum size.

      Example:

      • sci.log (current file)
      • sci.log.1 (first backup)
      • sci.log.2 (second backup)

    • <param name="MaxFileSize" value="100MB" /> Defines the maximum size of a log file before it is rolled over. The value can be set in bytes, KB, or MB.

    • <param name="file" value="/opt/servers/logs/sci${IBM_LOG_FILE}_CUSTOM.log"/> Changes the log file location from the default path to a custom directory.

    • PatternLayout:

        <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%t %-7p: %-60m: %-25c{1}:
  %d%n"/>
   </layout>

      Defines how log messages are formatted. You can choose details to include and how they appear in each log entry.

      The pattern includes placeholders for details such as timestamp, logger name, thread name, log level, and the log message.

      Conversion pattern details:

      • %t: Thread name
      • %-7p: Log level (left-aligned, 7 characters)
      • %-60m: Log message (up to 60 characters)
      • %-25c{1}: Logger name (last class name, 25 characters wide)
      • %d: Date and time

      • %n: New line

        org.apache.log4j.PatternLayout is provided by Apache and generates customizable text-based log output.

      Sample log format generated by using %t %-7p: %-60m: %-25c{1}: %d%n

       Thread-4 ERROR : Order processing failed for OrderID 12345           : OrderService     : 2025-07-18 14:15:42,372

      com.sterlingcommerce.woodstock.util.frame.logex.SCIGELFLayout is a custom layout class that is provided by Sterling OMS for its logging framework. Unlike PatternLayout, it does not use formatting strings. It produces logs in Graylog Extended Log Format (GELF) with a fixed structure.

      Sample log format generated by SCIGELFLayout

       {
 "version": "1.1",
 "host": "localhost",
 "short_message": "Order processing failed for OrderID 12345", "full_message": "Exception in thread 'Thread-4'
 java.lang.NullPointerException\n\tat com.company.order.OrderService.process(OrderService.java:42)\n\t...",
 "timestamp": 1721311767.123,
 "level": 3,
 "_thread": "Thread-4",
 "_logger": "com.ibm.order.OrderService", "_application": "SterlingOMS", "_component": "OrderProcessing", "_facility": "OMS",
 "_eventID": "ORDER_FAIL_001",
 "_user": "system", "_interface": "OrderCreate", "_severity": "ERROR"
 }

      Note: In Sterling v10, the parameters rotateLogs, maxNumLogs, and maxLogSize are mandatory for all appenders. The value of maxLogSize must be set to 100000.

      The file parameter must include ${IBM_LOG_FILE}.log as part of the file name.

      • For application server logs: sci${IBM_LOG_FILE}.log
      • For agent server logs: agentserver${IBM_LOG_FILE}.log

  4. To build the extensions.jar file, go to the <INSTALL_DIR> directory and run the following command:

    ./runtime/bin/sci_ant.sh -f
./runtime/devtoolkit/devtoolkit_extensions.xml export

  5. Go to <INSTALL_DIR> and check that the custom Log4j configuration file is included in the extensions.jar.

  6. To deploy the extensions.jar file to ensure that the application server refers to custom log4j configuration, go to the <INSTALL_DIR>/compose/ directory and run the following command:

     ./om-compose.sh setup-upg <INTALL_DIR>/extensions.jar

  7. After restarting the server, log files will be generated as:

    • sci_CUSTOM.log for the application server
    • agentserver_CUSTOM.log for the agent server

Steps to customize Log4j2

  1. Copy the content from log4j2.xml.sample to the empty log4j2_extra.xml file located in <runtime>/properties, and update the configuration as needed for your business requirements.

    System parameters

    Content added to log4j2_extra.xml is appended to the default configuration.

    Example: fileName="/opt/servers/logs/appserver${sys:IBM_LOG_FILE:-}.log" This stores the OMS server logs in the specified path with the file name appserver.log.

    Remove <AppenderRef ref="Console"/> from all loggers except the root logger to prevent them from writing to the system log.

  2. Place log4j2_extra.xml in <runtime>/properties.

  3. To build the extensions.jar file, go to <INSTALL_DIR> and run:

    ./runtime/bin/sci_ant.sh -f
./runtime/devtoolkit/devtoolkit_extensions.xml export

  4. Deploy extensions.jar to ensure that the application server uses the custom logging configuration. Go to <INSTALL_DIR>/compose/ and run:

    ./om-compose.sh setup-upg <INTALL_DIR>/extensions.jar

Full logging control with Log4j2

If you want complete control over the logging setup and do not want Sterling OMS default configurations to apply, follow this approach.

  1. In the customer_overrides.properties file, set the following property:

    yfs.log4j2.omsConfig.disable=true

  2. After disabling the default configuration:

    • Copy the contents from log4j2.sample.xml to log4j2_extra.xml.
    • Modify log4j2_extra.xml according to your requirements.

  3. Follow the same build and deployment steps as described in steps 3 and 4 of the Steps to customize Log4j2 section.

Managing agent and integration server logs

Sterling OMS provides the AGENT_LOG_APPENDER appender to capture logs from agent and integration servers. All servers running in the instance write logs to the file specified in this appender. For example:

<RollingFile name="AGENT_LOG_APPENDER" fileName="/root/installables/devtoolkit_docker/runtime/logs/agentserver${sys:IBM_LO G_FILE:-}.log"
filePattern="/root/installables/devtoolkit_docker/runtime/logs/agentserver${sys:IBM
_LOG_FILE:-}.log.D%d{yyyyMMdd}%i">

You can redirect logs for different agent or integration servers to separate log files by setting the IBM_LOG_FILE system property as a JVM argument during startup.

Example

Consider two agent servers: ScheduleOrder and ReleaseOrder. Start each server with a unique IBM_LOG_FILE value as shown:

./agentServer.sh ScheduleOrder -DIBM_LOG_FILE=ScheduleAgent
./agentServer.sh ReleaseOrder -DIBM_LOG_FILE=ReleaseAgent
  • Logs for ScheduleOrder will be stored in agentserverScheduleAgent.log.
  • Logs for ReleaseOrder will be stored in agentserverReleaseAgent.log.

This setup keeps logs separate for each JVM instance, making it easier to manage and analyze logs in multi-agent environments.

Enable logging for custom code with Log4j1

To enable logging in custom Java classes, use the com.yantra.yfc.log.YFCLogCategory logger.

A sample custom code example:

package com.custom.log;

import org.w3c.dom.Document;
import com.yantra.yfc.dom.YFCDocument;
import com.yantra.yfc.log.YFCLogCategory;
import com.yantra.yfs.japi.YFSEnvironment;

public class CustomLogger {

    private static YFCLogCategory logger = YFCLogCategory.instance(CustomLogger.class);

    public Document printCustomLogs(YFSEnvironment env, Document inDoc) {
        logger.beginTimer("### Inside printCustomLogs BeginTimer ###");
        logger.info("### Inside printCustomLogs Info ###");
        logger.warn("### Inside printCustomLogs Warn ###");

        if (logger.isDebugEnabled()) {
            logger.debug("### Inside printCustomLogs Debug ###");
            logger.debug("### Input Doc::" + YFCDocument.getDocumentFor(inDoc).getString());
        }

        logger.endTimer("### Inside printCustomLogs EndTimer ###");
        return inDoc;
    }
}

If your custom code uses the com.yantra.yfc.log.YFCLogCategory logger and its package is not listed in the log4jconfig_custom.xml file, add a logging category for that package.

To make it log like the default product configuration, copy an existing entry (for example, com.ibm) and replace it with your custom package name:

<category name="com.custom.log" class="com.yantra.yfc.log.YFCLogCategory" additivity="false">
    <level class="com.yantra.yfc.log.YFCLogLevel" value="VERBOSE" />
    <appender-ref ref="CONSOLE" />
    <appender-ref ref="ALL" />
    <appender-ref ref="NEWRELIC_APPENDER" />
</category>

Enable logging for custom code with Log4j2

To enable logging for more Java packages without manually editing the log4j2_extra.xml file, define the following properties in the customer_overrides.properties file:

Property 1: yfs.log4j2.customPackages=<comma-separated list of package names>

Example: yfs.log4j2.customPackages=com.ibm.orders,com.ibm.inventory

Property 2 (optional): yfs.log4j2.customPackage.<packagename>.level=<logging level>

If not defined, the default level is VERBOSE.

Example:

yfs.log4j2.customPackage.com.ibm.orders.level=DEBUG yfs.log4j2.customPackage.com.ibm.inventory.level=INFO

Enable trace for a custom service or OOTB API

To enable tracing by using the System Management Console (SMC):

  1. Locate the client.jar file.

  2. Open a terminal and go to the directory containing client.jar.

  3. Run the following command:

    java -jar client.jar -mode SMC -s localhost:9080 -u admin -p password

    Replace the host, port, username, and password with your environment details.

  4. After the System Management Console starts, go to Tools → Trace Components

    alt

  5. Click Add.

  6. Set Component Type to Services or API.

  7. Choose the Component Name (for example, getOrderDetails).

  8. Select the Trace Level. Available options are: VERBOSE, DEBUG, SQLDEBUG, and TIMER.

    alt

Important points

  • You can enable tracing in two ways:

    a. Using the System Management Console

    b. Using the modifyTraces API

    Sample modifyTraces API input:

    <Traces> <Trace Action="ADD" Level="VERBOSE" Name="getOrderDetails" TraceTTL="60" Type="API"/> </Traces>

  • If no logging level is set through the console, the level defaults to INFO or uses the value that is defined in log4jconfig.xml, whichever is lower.

  • For production, use INFO or WARN levels to maintain performance. Enable detailed logging (like DEBUG) only for short diagnostic periods.

  • Sterling OMS supports two types of logging levels:

    Application logging levels (used in code): ERRORDTL < ERROR < WARN < INFO

    Diagnostic logging levels (used for tracing): TIMER < SQLDEBUG < DEBUG < VERBOSE

  • Application levels are cumulative. Enabling INFO includes all levels from INFO to ERRORDTL.

  • Diagnostic levels work the same way. Enabling VERBOSE includes all diagnostic levels from VERBOSE to TIMER, plus all application levels.

  • DEBUG and VERBOSE generate detailed logs, including XML inputs and intermediate data. Use them carefully, especially in production.

Trace levels

TIMER – Shows how long each event takes to complete. Useful for identifying performance issues.

SQLDEBUG – Displays the actual SQL queries that are executed within the component. Helps with database tuning.

DEBUG – Provides details that are needed to troubleshoot components that aren’t working as expected.

VERBOSE – Gives complete and detailed information about the component’s behavior.

Logging levels summary

Logging Level DEFAULT (No Trace) TIMER SQLDEBUG DEBUG VERBOSE
ERRORDTL X X X X X
ERROR X X X X X
INFO X X X X X
WARN X X X X X
TIMER X X X X
SQLDEBUG X X X
DEBUG X X
VERBOSE X

Summary

This tutorial showed how to configure and customize Log4j1 and Log4j2 in the IBM Sterling Order Management System. It covered default logging behavior, customization steps, and best practices for managing application, agent, and integration server logs. You also learned how to enable logging for custom Java code and control trace levels by using the System Management Console. By following the steps, you can create an efficient and organized logging setup for easier debugging and monitoring.