Skip to main content
Skip table of contents

xUML Runtime Logger Configuration

RUNTIME 2020.7 On startup, the xUML Runtime accepts a file specifying a logger configuration (see --logging.config.file  on xUML Runtime Command Line Options). The configuration file is a JSON file in which you can specify logging details like which logging data to write where.

Concepts

The logging concept of the xUML Runtime is build around the concepts of channels and sinks.

Click here to expand an example logger configuration file...

This file reflects the default logger configuration with some filters added.

JS
{
  "channels": {
    "access": {
      "sinks": {
        "default": {
          "type": "daily_rotated_file",
          "params": {
            "name_pattern": "logs/transaction_%Y-%m-%d.log"
          },
          "formatter": {
            "type": "pattern",
            "params": {
              "pattern": "{timestamp:%Y-%m-%d\t%T\t%z}\t{trx_id}\t{session_id}\t{component}\t{elapsed_ms}\t{trx_status}\t{domain}\t{trx_entry_type}\t{param1}\t{param2}\t{correlation_id}"
            }
          },
          "filters": [
            {
              "trx_level": ["SERVICE"],
              "domains": ["*", "!PSTATE", "!CONVERSATION"]
            },
            {
              "trx_level": ["IO_INTERNAL"],
              "domains": ["PSTATE", "CONVERSATION"]
            }
          ]
        }
      }
    },
    "error": {
      "sinks": {
        "default": {
          "type": "daily_rotated_file",
          "params": {
            "name_pattern": "logs/bridgeserver_%Y-%m-%d.log"
          },
          "formatter": {
            "type": "pattern",
            "params": {
              "pattern": "[{timestamp:%F %T %z}][{session_id:010}][{level}][Internal][{domain}][{code}][{message}]"
            }
          },
          "filters": [
            {
              "level": ["Info"],
              "domains": ["*"]
            }
          ]
        },
	    "monitoring": {
          "type": "std_err",
          "formatter": {
            "type": "pattern",
            "params": {
              "pattern": "e2eruntime[{pid}[{timestamp:%F %T UTC}[{level}[Internal[{domain}[{code}[[{message}]]"
            }
          }
        }
      }
    }
  }
}

ElementDescriptionAllowed Values / Examples
channel

A channel is an object that describes the data that will be written to a log file. It is identified by a channel name.

The following channel names are reserved for internal use of the xUML Runtime:

  • error
  • access
  • channels starting with "xUML" in any casing
errorWrite service logging data (bridgeserver log).
accessWrite transaction logging data.
sink

A channel can contain an arbitrary number of sinks. Sinks define the logging output and how it is written:

  • log file name and path patterns
  • log file format
  • logged content

Sink names are not important but you need them to access the logging configurations via the xUML Runtime API.
Do not rename the sinks of the access and error channels.


Configuring Sinks

Sinks define the logging output and how it is written. You can define name and path of the log file, the log file format and filter out data to be logged.

PropertyDescriptionAllowed ValuesExample
type


Define whether to write to a file (daily or hourly rotation), or to std_out or std_err.std_outWrite logs to std_out.
"type": "hourly_rotated_file",
"params": {
"name_pattern": logs/transaction_%Y-%m-%d-%H.log"
}
std_errWrite logs to std_err.
daily_rotated_fileWrite to a daily rotated log file.
hourly_rotated_fileWrite to an hourly rotated log file.
paramsDefine parameters of the sink. At the moment, only accepted parameter is name_pattern to define the name of the log file.name_patternDefines the relative path and file name pattern of the log file. See Name Patterns for Log Files for available placeholders.
formatter
typeDefine in which format the log data will be logged to the log file.jsonLog the log file data in JSON format.

Example 1:

"formatter" : { 
   "type" : "pattern" ,
  "params": {
     "pattern" : "{timestamp:%Y-%m-%d\t%T\t%z}\t..."
  }
}

Example 2:

"formatter" : { 
  "type": "json"
}
patternLog the log file data according to a given pattern. The used pattern is defined in the params attribute via attribute pattern.
paramsIf format type is pattern, specify the log file pattern.
See Format Variables for Log File Content for more on the available variables.
legacy_utc

Enable UTC timestamp for monitoring logs.

This is a legacy option. Do not use.

trueUse UTC in timestamp.
falseDo not use UTC in timestamp.

filters

levelProvide an array of service log levels to let pass through the filter.

One of None, Fatal, Error, Warning, Info and Debug (case-sensitive).
Refer to Bridge Server Log Levels of an xUML Service for more information.

"filters" : [ 
   {
     "trx_level" : [ "SERVICE" ],
     "domains" : [ "*" , "!PSTATE" , "!CONVERSATION" ]
   },
   {
     "trx_level" : [ "IO_INTERNAL" ],
     "domains" : [ "PSTATE" , "CONVERSATION" ]
   }
]
trx_levelProvide an array of transaction log levels to let pass through the filter.One of NONE, CUSTOM, SERVICE, IO_EXTERNAL and IO_INTERNAL (case-sensitive).
Refer to Transaction Log Levels of an xUML Service for more information.
domainsProvide an array of error domains let pass through the filter. You can invert the filtering by adding a ! sign in front of a domain name. ["*"] Nothing is filtered.


list of domains
["<domain_1>", "<domain_2>, ...] 

Let logs containing one of the listed domains pass through the filter.

You can invert the filtering by adding a ! sign in front of a domain name, so !domain_1 will not let logs with this domain pass through the filter.

Name Patterns for Log Files

As a name pattern for log files to use in attribute name_pattern, you can use all specifiers listed on boost Date Time Format Flags.

We recommend to use the following subset:

PatternDescription
%Yyear, 4 digits
%mmonth, 2 digits
%dday of the month, 2 digits
%Hhour, 24-hour format, 2 digits
%Mminute, 2 digits
%Ssecond, 2 digits

Format Variables for Log File Content

Find below all available format variables for xUML service (bridgeserver) logs and transaction logs

You can format the output using the : sign followed by a format string. Reasonable format strings are:

PatternDescriptionExample Output
Format Patterns For Date/Time Variables
%YYear as a 4-digit decimal number.
2020
%mMonth as a 2-digit decimal number (range [01,12]).
07
%dDay of the month as a decimal number (range [01,31]).
15
%F
Equivalent to %Y-%m-%d.
2020-07-15
%HHour as a 2-digit decimal number, 24 hour clock (range [00-23])
16
%MMinute as a 2-digit decimal number (range [00,59])
34
%SSecond as a 2-digit decimal number (range [00,60])
25
%TEquivalent to "%H:%M:%S" (the ISO 8601 time format).
16:34:25
%zOffset from UTC in the ISO 8601 format, or no characters if the time zone information is not available.
+0200
Format Patterns for Numeric Variables
099Sign-aware zero-padding for numeric types, where 0 is the indicator to apply the padding and 99 the maximum padding width.010 → 10-digit number with leading zeros.

If you want to apply more sophisticated formatting, find more options on the {fmt} documentation pages for string formats and cpp documentation pages for date/time formats.

Available Variables for Service Logs

Refer to xUML Service Standard Log for more information on this log.

FieldTypeDescriptionExample Usage
codeStringerror code
{code}
domainStringerror domain
{domain}
levelStringerror level
{level}
messageStringerror message details
{message}
pidNumeric

process id

{pid}
{pid:010}
session_idNumeric

session id

{session_id}
{session_id:010}
timestampDateTime

timestamp when the log occurred

{timestamp}
{timestamp:%F %T %z}

Available Variables for Transaction Logs

Refer to Contents of the Transaction Log for more information on the listed variables.

FieldTypeDescriptionExample Usage
componentStringname of the component
{component}
correlation_idStringcorrelation ID
{correlation_id}
domainStringerror domain name
{domain}
elapsed_msNumeric

milliseconds since session start

{elapsed_ms}
{elapsed_ms:010}
param1Stringparameter 1
{param1}
param2Stringparameter 2
{param2}
session_idNumeric

session ID

{session_id}
timestampDateTime

timestamp when the log occurred

{timestamp}
{timestamp:%F %T %z}
trx_entry_typeStringlog type
{trx_entry_type}
trx_idStringtransaction ID
{trx_id}
trx_statusStringstatus
{trx_status}

Example Patterns for Emulating the Classic Log Format

LogExample Definition
xUML Service Log (bridgeserver)
{timestamp:%Y-%m-%d\t%T\t%z}\t{trx_id}\t{session_id}\t{component}\t{elapsed_ms}\t{trx_status}\t{domain}\t{trx_entry_type}\t{param1}\t{param2}\t{correlation_id}
Transaction Log
[{timestamp:%F %T %z}][{session_id:010}][{level}][Internal][{domain}][{code}][{message}]
Monitoring
e2eruntime[{pid}[{timestamp:%F %T UTC}[{level}[Internal[{domain}[{code}[[{message}]]
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.