log parameter

Use log to enable logging data for monitoring, debugging, diagnostics, troubleshooting, security, auditing performance optimization, visibility, and historical analysis. The IBM® Sterling Intelligent Promising by default writes application level logs to the console. However, you can choose to redirect these logs to Kafka by using Log4j2 Kafka appender.

Default console logging

Console logging is enabled by default. To access the logs, use kubectl or oc commands. When a container is restarted, deleted, or re-created, the old logs are cleared.

Log4j2 Kafka appender logging

Use the Log4j2 Kafka appender to send log messages to a Kafka topic. To use the Log4j2 Kafka appender, you must have a Kafka cluster that is set up and running. All the IBM Sterling Intelligent Promising services have inbuilt support for the Lo4j2 Kafka appender.

The following table explains the optional properties that are applicable for log.
Property Default value Value type Required Description
logChannels CONSOLE string No Define the log output channel. By default, console logging is enabled. If you want to use the Log4j2 Kafka appender for logging, set the logChannels value to KAFKA.If it is set to KAFKA, specify properties specific to Kakfa. Only the GELF layout is supported implicitly.

If it is set to CONSOLE, supported layout options are PATTERN by default or GELF layout.
logLevel INFO string No Specify this property to override the log level at the individual server level. Allowed values are OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL. For more information, see Types of logLevel and precedence.
logTopic string No If you select Kafka for logging, specify the topic to which you want to log the data. logTopic is not applicable for the default console logging.
console.layout PATTERN string No

Specify the console layout format only when logChannels is CONSOLE.

Allowed values are PATTERN, GELF.
logExtraFields

array No Specify the list of extra key-value pairs to include in each log entry. These values can also be fed from environment variables.

Custom attributes in log metadata

The logging utilities include following custom attributes to enhance debugging capabilities for default console and Log4j2 Kafka appender logging.
DATACENTER
Name of the compute cluster where you host and manage Sterling Intelligent Promising deployment. For example, Dublin_data_center.
APP_NAME
Name of the application service that you are using. Allowed values can be rules, cas, search, and other services.
COMPONENT_NAME
Indicates whether the component is an API server or a backend server.
NODE_NAME
Hostname of the worker node in the cluster.
POD_NAME
Name of the pod.
POD_IP
Private IP of the pod.

Levels of log configuration

You can configure logs at the following three levels.

  1. Global log channel configuration

    Define the logChannels property with either KAFKA or CONSOLE in the SIPEnvironment globally. This log configuration is applicable to all the Sterling Intelligent Promising services.

  2. Log level configuration

    Define the logLevel property in the following scopes.

    Global level
    Configuration at this level applies to all Sterling Intelligent Promising services and servers.
    Service level
    Configuration at this level applies to a specific Sterling Intelligent Promising service where the log level is defined.
    Server level
    Configuration at this level applies to individual servers within a particular Sterling Intelligent Promising service.

    For more information, see Types of logLevel and precedence.

  3. Custom configuration

    Define custom fields such as environment names to be included in the logs. Custom configurations can be defined at the service group and SIPEnvironment levels. For a server, the final set of fields is a combination of both levels, with service-level fields holding precedence.

Configuration hierarchy

Scope Purpose Precedence
Global: SIPEnvironment The default for all services and servers. Lowest
Service level Overrides global settings for a service. Medium
Server level Customization for individual server. Highest

Example of log configuration

The following example demonstrates how to define log properties. In the logExtraFields, the value for key:env1 is QA. For the key:env2 pair, the value is sourced from an environment variable that is defined in the servers.properties. Ensure that the corresponding deployment includes this environment variable. For more information, see serverProperties parameter. 
spec:
  log:
    console:
      layout: GELF
    logLevel: DEBUG
    logChannels: CONSOLE
    logExtraFields:
      - key: env1
        value: QA
      - key: env2
        envVar: var1

Types of logLevel and precedence

The logLevel property can be configured at three levels, individual server, service group, or global (SIPEnvironment).
The default logging level is INFO. The available options are OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL.

Logging at the individual server level
Logs can be customized for each server instance. If configured, the individual server's log level takes precedence over other configurations.
Example
spec:
  active: true
  appServers:
    - active: true
      names:
        - ApiSupplies
      logLevel: DEBUG
    - active: true
      names:
        - ApiDemands
      logLevel: DEBUG
Logging at the service group level
If the log level is not set for an individual server, the configuration that is defined at the service group level is applied.

Example

spec:
  active: true
  logLevel: DEBUG
  appServers:
    - active: true
      names:
        - ApiSupplies
    - active: true
      names:
        - ApiDemands
Logging at the global level in SIPEnvironment
If the log levels for both the individual server and service group are not defined, the global configuration in SIPEnvironment is considered. If no log level is explicitly set at any level, the default INFO level is applied. This hierarchical approach allows for tailored logging control for each server instance.

Example

spec:
  license:
    accept: true 
  secret: ""
  # log: 
  #   logChannels: CONSOLE
  #   logTopic: ""
  #   logLevel: INFO
For a complete configuration, see SIPEnvironment custom resource manifest.

Log configuration for two Kafka clusters

If you are using two Kafka clusters, one for the application and another for logging, specify loggingContactPoints in the externalServices custom resource for Kafka. Also, in the secret, add the Kafka properties that are prefixed with log_. For more information, see Creating a secret.

If you want to use the same contactPoints that you defined for the application, then do not define loggingContactPoints. By default contactPoints is used to push logs to a Kafka topic. For more information about Kafka, see loggingContactPoints in kafka parameter.