Logging Framework

OpenIG uses the objects in this section to log events to the console or to files.

ConsoleLogSink — log to standard error

Description

A log sink that writes log entries to the standard error stream.

Usage

{
     "name": string,
     "type": "ConsoleLogSink",
     "config": {
         "level": string,
         "stream": string
    }
}

Properties

"level": string, optional

The level of log entries.

Must be one of the following settings. These are ordered from most verbose to least verbose:

  • ALL (log all messages)

  • TRACE (log low-level tracing information)

  • DEBUG (log debugging information)

  • STAT (log performance measurement statistics)

  • CONFIG (log configuration information)

  • INFO (log general information)

  • WARNING (log potential problems)

  • ERROR (log serious failures)

  • OFF (log no messages)

Default: INFO.

"stream": string, optional

The standard output to use to display logs in the console.

Must be one of the following settings:

  • ERR (use standard error: System.err)

  • OUT (use standard output: System.out)

  • AUTO (select standard error or output depending on the message log level: TRACE, DEBUG, STAT, CONFIG, INFO print to System.out; WARNING and ERROR print to System.err)

Default: ERR.

Example

{
     "name": "LogSink",
     "comment": "Default sink for logging information.",
     "type": "ConsoleLogSink",
     "config": {
         "level": "DEBUG",
         "stream": "AUTO"
     }
}

Javadoc

org.forgerock.openig.log.ConsoleLogSink

FileLogSink — log to a file

Description

A log sink that writes log entries to a file using the UTF-8 character set.

Usage

{
     "name": string,
     "type": "FileLogSink",
     "config": {
         "file": configuration expression,
         "level": string
     }
}

Properties

"file": configuration expression, required

The path to the log file.

A configuration expression, described in Expressions(5) is independent of the request, response, and contexts, so do not use expressions that reference their properties. You can, however, use ${env['variable']}, ${system['property']}, and all the built-in functions listed in Functions(5).

"level": string, optional

The level of log entries.

Must be one of the following settings. These are ordered from most verbose to least verbose:

  • ALL (log all messages)

  • TRACE (log low-level tracing information)

  • DEBUG (log debugging information)

  • STAT (log performance measurement statistics)

  • CONFIG (log configuration information)

  • INFO (log general information)

  • WARNING (log potential problems)

  • ERROR (log serious failures)

  • OFF (log no messages)

Default: INFO.

Example

{
     "name": "LogSink",
     "type": "FileLogSink",
     "config": {
         "file": "${system['log'] ? system['log'] : '/tmp/proxy.log'}",
         "level": "DEBUG"
     }
}

Javadoc

org.forgerock.openig.log.FileLogSink

Slf4jLogSink — delegate log writing to SLF4J

Description

A log sink that delegates the writing of logs to SLF4J. OpenIG uses the Logback implementation of the SLF4J API. Use this log sink to define different logging behavior for routes and third-party dependencies.

A default configuration for logging is defined in OpenIG. To change the configuration, create a file $HOME/.openig/config/logback.xml. For a description of the available parameters, see the Logback website.

Usage

{
    "name": string,
    "type": "Slf4jLogSink",
    "config": {
        "base": string
    }
}

Properties

"base": string, optional

The name for a logger that can be defined in logback.xml. The logger identifies a route or third-party dependency for which to define different logging behavior.

Logger names follow a hierarchical naming rule. When an object logs a message to Slf4jLogSink, a descendant logger is created the whose name is a concatenation of the base and the object name, separated with a .. For example, when an object MyObject logs a message to to an Slf4jLogSink with base com.example.app, a logger named com.example.app.myobject is created.

The hierarchical naming allows you to configure logback.xml with different logging characteristics for different components in a route.

Default: Empty string.

Example

In the following example, requests from the client filter, MyObject, create a logger called com.example.app.myobject.

{
   "name": "MyLogSink",
       "type": "Slf4jLogSink",
       "config": {
           "base": "com.example.app"
       }
},
{
   "name": "MyObject",
       "type": "OAuth2ClientFilter",
       "config": {
           "logSink": "MyLogSink"
  }
}

The following logback.xml sets the logging level to DEBUG for requests from the client filter, and to INFO for other requests with the base com.example.app.

<?xml version="1.0" encoding="UTF-8"?><configuration>

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
 <encoder>
  <pattern>
   %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
  </pattern>
 </encoder>
</appender>

<logger name="com.example.app" level="INFO"/>
<logger name="com.example.app.myobject" level="DEBUG"/>

<root level="DEBUG">
 <appender-ref ref="STDOUT"/>
</root>

</configuration>

For an example configuration, see Separating Logs for Different Routes in the Gateway Guide.

Javadoc

org.forgerock.openig.log.Slf4jLogSink