Contribute in GitHub:

Configuring logging and tracing for Voice Gateway

Like other configuration for the voice gateway, logging and tracing levels are configured as Docker environment variables, as described in Configuration environment variables for Voice Gateway. For information about the messages that are written to the logs, see Voice Gateway system messages

Changing the default log and trace configuration
Setting the log file language
Setting the log file time zone
Configuring log file viewing permissions

Changing the default log and trace configuration

You can change the default log and trace configuration by setting environment variables for each of the containers.

Logging environment variables

The following Docker environment variables are used to configure the log settings:

Table 1. Environment variables for configuring SIP Orchestrator logging
Environment variable	Default	Description
LOG_LEVEL	`info` (Version 1.0.2 and later) `audit` (prior to Version 1.0.2)	The log level for the SIP Orchestrator. Valid values for 1.0.2 onward, from least information to most information, are: `off`, `severe`, `warning`, `info`, `fine`, `finest`, and `all`. Prior to 1.0.2, the valid options are: `off`, `severe`, `warning`, `audit`, `fine`, `finest`, and `all`. When set to `fine`, `finest`, or `all`, the logs might contain sensitive PHI, PII, and PCI DSS data.
LOG_MAX_FILES	`5`	The maximum number of SIP Orchestrator log files, trace files, and exception summary log files. When this limit is reached, the oldest file is deleted and a new file is created. For example, when this variable is set to 5, the SIP Orchestrator generates up to 5 message logs, 5 trace logs, and 5 exception summaries.
LOG_MAX_FILE_SIZE	`100`	The maximum size in megabytes (MB) that a SIP Orchestrator log file can reach before a new file is created.

Table 2. Environment variables for configuring Media Relay logging
Environment variable	Default	Description
MEDIA_RELAY_LOG_LEVEL	`INFO`	The log level for the Media Relay. Valid values from least information to most information are `INFO`, `DEBUG`, or `TRACE`. Note that when set to `DEBUG` or `TRACE`, the logs might contain sensitive PHI, PII, and PCI DSS data.
MEDIA_RELAY_LOG_ROTATION_FILE_COUNT	`10`	The number of Media Relay log files to keep in rotation for the Bunyan logging module.
MEDIA_RELAY_LOG_ROTATION_PERIOD	`1d`	The period at which the Bunyan logging module rotates the log files. By default, log files are rotated on a 24-hour basis.

Table 3. Environment variables for configuring Speech to Text Adapter logging and tracing
Environment variable	Default	Description
`LOG_LEVEL`	`debug`	The log level for the Speech to Text Adapter. Set the log level to `info`, `debug`, or `trace`. Note that when set to `debug` or `trace`, the logs might contain sensitive PHI, PII, and PCI DSS data.

Tracing environment variables

These Docker environment variables for the SIP Orchestrator are used to control various aspects of the tracing:

Table 4. Environment variables for configuring tracing
Environment variable	Default	Description
ENABLE_AUDIT_MESSAGES	`true`	Set to `false` to disable audit messages.
ENABLE_TRANSCRIPTION_AUDIT_MESSAGES	`false`	Set to `true` to enable audit transcription messages. Note that when these messages are enabled, they are printed to the logs and might contain sensitive PHI, PII, and PCI DSS data.
LATENCY_REPORTING_THRESHOLD	`1000`	Threshold in milliseconds for reporting round-trip conversation latency.
RELAY_LATENCY_REPORTING_THRESHOLD	`1000`	Threshold in milliseconds for reporting Media Relay latencies.
WLP_LOGGING_MESSAGE_FORMAT	`basic`	Valid values are `basic`, `json`. Added in version 1.0.2
WLP_LOGGING_MESSAGE_SOURCE	`message`	The list of comma-separated sources that route to the messages.log file. Valid values are `message`, `trace`, `accessLog`, `ffdc`, and `audit`. This property applies only when WLP_LOGGING_MESSAGE_FORMAT is set to `json`. Added in version 1.0.2.
WLP_LOGGING_CONSOLE_FORMAT	`basic`	Valid values are `basic`, `json`. Added in version 1.0.2.
WLP_LOGGING_CONSOLE_SOURCE	`message`	The list of comma-separated sources that route to the console. Valid values are `message`, `trace`, `accessLog`, `ffdc`, and `audit`. This property applies only when WLP_LOGGING_CONSOLE_FORMAT set to `json`. Added in version 1.0.2.

When JSON logging is enabled, tenant ID and session ID are added in the form of name-value pairs to the log and trace records. See Table 4 for how to enable JSON logging in the SIP Orchestrator. These name-value pairs are displayed in the following locations:

The messages.log file when that log is configured to use JSON format
Console output when your console is configured to use JSON format
Records sent by logstashCollector to Logstash

{
  "type": "liberty_message",
  "host": "e0b68506590f",
  "ibm_userDir": "/opt/ibm/wlp/usr/",
  "ibm_serverName": "defaultServer",
  "message": "CWSGW0003I: The call to the Voice Gateway disconnected for the following reason = BYE received  sessionID = EwhF6GX99x   Length of call = 4,909 ms tenantID = watson-conversation",
  "ibm_threadId": "00000083",
  "ibm_datetime": "2019-05-30T17:53:19.759+0000",
  "ibm_messageId": "CWSGW0003I",
  "module": "com.ibm.ws.cgw.session.FullDuplexSession",
  "loglevel": "INFO",
  "ibm_sequence": "1559238799759_0000000000066",
  "ext_SIPCallId": "EwhF6GX99x",
  "ext_SIPSessionId": "wlp_2_0",
  "ext_SIPASId": "wlp_2",
  "ext_thread": "Default Executor-thread-60",
  "ext_tenantID": "watson-conversation",
  "ext_sessionID": "EwhF6GX99x"
}

Setting the log file language

If you want the log messages to be generated in a language other than English, you can choose a different language by changing the locale of each container. To change the locale, set both of the following environment variables:

Table 5. Environment variables for locale and language
Environment variable	Default
LC_ALL	en_US.UTF-8
LANG	en_US.UTF-8

To learn more about locales and these variables, see Locale on the Ubuntu wiki.

For example, the following variables set the log file language to Spanish:

LC_ALL=es_ES.UTF-8
LANG=es_ES.UTF-8

You can choose from the following supported languages:

Table 6. Supported languages
Language	Character set value
Brazilian Portuguese	pt_BR.UTF-8
French	fr_FR.UTF-8
German	de_DE.UTF-8
Italian	it_IT.UTF-8
Japanese	ja_JP.UTF-8
Spanish	es_ES.UTF-8
Simplified Chinese	zh_CN.UTF-8
Traditional Chinese	zh_TW.UTF-8

Setting the log file time zone

You can change the time zone of the messages in the log files by configuring the time zone for each container. To configure the time zone, set the TZ environment variable for each container to the corresponding zone name from the International Assigned Numbers Authority (IANA) Time Zone Database. For example, the following configuration sets the time zone to America/New_York.

TZ=America/New_York

For more information about the IANA time zones, see Time Zone Database.

Configuring log file viewing permissions

During the Voice Gateway deployment, the server logs that are created don't give permissions to other users, -rw-r---. See Logging and tracing configuration

If you want to create the server log files with read permissions for other users, you can set the WLP_SKIP_UMASK property in your deployment configuration file to true. This configuration allows the log file to be created with updated viewing permissions, -rw-r-r-.

Table 7. Log file viewing permissions environment variables.
Environment variable	Default
WLP_SKIP_UMASK	false