Logging

Log format

Log entries are JSON-formatted.

Listing 1. Default log format

{
    "message": "%message %ex",
    "logger": "%logger",
    "severity": "%level",
    "level": "%level",
    "user": "%X{user}",
    "client": "%X{client}",
    "page": "%X{page}",
    "request": "%X{request}",
    "execution": "%X{execution}",
    "traceId": "%X{traceId}",
    "spanId": "%X{spanId}",
    "correlationId": "%X{correlationId}",
    "customTraceHeaders": "%X{customTraceHeaders}",
    "thread": "%thread",
    "@timestamp": "%date{\"yyyy-MM-dd'T'HH:mm:ss.SSS\", UTC}Z"
}

The keys in the JSON output are:

@timestamp: ISO 8601 timestamp in UTC.
thread: The name of the thread that emitted the log entry.
logger: The fully qualified name of the logger.
severity and level: The log level (INFO, WARN, and so on). Both keys carry the same value for compatibility with different log-aggregation systems.
message: The log message, followed by any exception stack trace.
user, client, page, request, execution: Diagnostic context for the log entry — user ID, client ID, page impression ID, HTTP request ID, and execution ID. Each key only appears if the corresponding context applies.
traceId, spanId, correlationId: Distributed-tracing identifiers.
customTraceHeaders: Custom trace headers passed by the client.

To customize the JSON format, set com.unblu.logging.consoleJsonLogFormat to a JSON template of your choice.

To switch to a plain-text format, set com.unblu.logging.consoleUseJsonLogFormat to false.

Log levels

Unblu logging supports different log levels (ERROR, WARN, INFO, and DEBUG). By default, the log level for Unblu is set to INFO and the log level for integrated third-party libraries is set to WARN.

The root level for Unblu can be changed using com.unblu.logging.rootLevel.

The root level for third-party libraries can be changed using configuration properties.

You can set log levels for individual loggers (packages or classes) using the following notation:

com.unblu.logging.level.<loggerName>=<level>

If, for example, the log level is to be set to DEBUG for the logger com.unblu.review.server.filter, you must add the following configuration setting:

com.unblu.logging.level.com.unblu.review.server.filter=DEBUG

When analyzing issues in the Collaboration Server, it can be useful to trace HTTP requests. To do so, set com.unblu.logging.level.com.unblu.platform.server.core.internal.WrapperServlet to the log level TRACE.

If you’ve enabled WebSockets, you can also trace WebSocket requests by setting com.unblu.logging.level.com.unblu.runtime.server.websocket.jetty.GenericWebSocketCreator to TRACE.

You can change logging levels for the server only, the client only, or for shared code as required.

For both server and client: com.unblu.logging.level.<loggerName>
For only the server: com.unblu.server.logging.level.<loggerName>
For only the client: com.unblu.client.logging.level.<loggerName>

For the client, only the log levels ERROR, WARN, and INFO are available.

Changing log levels at runtime

If enabled, superadmins can change log levels at runtime from the Global Configuration interface.

To enable this feature, set the IMMUTABLE configuration property com.unblu.loglevel.allowDynamicLogLevelChange to true. Once you’ve done so and restarted Unblu, you see a Log level entry in the sidebar of the Global Configuration interface.

How log levels work

Loggers are organized hierarchically. The root logger sits above every other logger and is named ROOT.

The Log level page distinguishes between two kinds of entry:

Logger entries, such as com.unblu.runtime.server.servlet.jetty.WrapperServlet, are fully qualified Java class names. Their trailing segments are therefore capitalized. Setting the log level on an individual logger affects only that logger.
Package entries, such as com.unblu.runtime.server, have an all-lowercase trailing segment. Setting the log level on a package cascades to every package and logger underneath it.

Changes to ROOT apply to every logger in the system. Don’t change the ROOT log level on production systems. Setting the ROOT log level to DEBUG or TRACE can have a noticeable negative impact on Unblu’s performance.

Changing a log level

To change a log level, complete the following steps:

Open the Global Configuration interface and click Log level in the sidebar.
Find the logger or package you want to change:
- Enter the name of a logger in the search field to filter the list.
- Use the level filter to show only loggers at a specific level.
- Use the Root, Unblu, Third party, and Changed toggles to scope the list.
- Click a logger name to drill into its package: a breadcrumb filter appears next to the toggle buttons, and the list expands to include the package and any sub-packages. Click an earlier segment of the breadcrumb to widen the scope back up. The search field overrides the breadcrumb filter, so clear it first if you’ve entered a filter term.
- Choose a sort order from the sort dropdown.
Select a log level on the row.

Any change you make is broadcast to all pods and takes effect immediately. Unblu doesn’t verify that the change was applied on every pod.

A dynamic level change persists until you reset it or until the Collaboration Server restarts.

Resetting a log level

To revert a logger or package to its default log level, click Reset on its row.

Some loggers display a Reset button even though no superadmin has changed them. Unblu adjusts certain log levels at startup to suppress noisy defaults, and the UI can’t distinguish those internal changes from user-initiated ones.

Setting a log level from the row’s level menu counts as a dynamic change, even if the level matches the logger’s default. Only Reset clears a dynamic change.

The Reset button on the ROOT row doesn’t work. Unblu doesn’t track the original level of the root logger, so resetting it has no effect.

Log levels and personally identifiable information (PII)

The DEBUG and TRACE log levels can produce log entries that contain personally identifiable information (PII) or conversation IDs. By default, Unblu therefore restricts dynamic log level changes to the log levels ERROR, WARN, INFO, and OFF. While this restriction is active, DEBUG and TRACE aren’t selectable in the UI, and the Log level page shows a banner explaining the restriction.

To enable the DEBUG and TRACE log levels for dynamic log level changes, set the configuration property com.unblu.loglevel.restrictToComplianceSafeLevels to false. The property is IMMUTABLE and requires a server restart.

Profiling database queries

You can configure Unblu to log database queries that may indicate a performance issue:

com.unblu.profiling.slowQueryThreshold sets the threshold, in milliseconds, beyond which Unblu logs the query.
com.unblu.profiling.highRowCountThreshold sets the threshold for the number of rows beyond which Unblu logs the query. Even a search is unlikely to return more than 1,000 rows, so a query returning a very large number of rows may indicate a problem.

Advanced configuration

All logging-related configuration settings are listed in the com.unblu.platform.server.core.LoggingConfiguration section of the Configuration Properties reference.