Logging (Local development)

Maverics is capable of integrating with log aggregation systems to consume and process logs.

Log records are sent to Syslog (Linux, MacOS, and Kubernetes) or Windows Event Viewer (Windows) and include a maverics identifier. The sizing or overwriting of system logs must be configured from your operating system via logrotate (usually /etc/logrotate.d/rsyslog or /etc/logrotate.conf). For more information on managing log settings, see the logrotate documentation.

Most log aggregation platforms (ELK, Loggly, etc.) can accept log streams via Syslog.

To run Maverics in debug mode, set the MAVERICS_DEBUG_MODE environment variable to true. Logging will be much more verbose when running in debug mode.

Log attributes

The orchestrator emits structured logs with a set of pre-defined key-value pairs.

Trace ID

traceID can be used to trace a given request through the system. The ID used is unique to an HTTP request. To maximize the utility of the traceID, consider pairing it with HTTP server access logs.

Strata recommends enabling Access Logs to provide the most insight into how requests flow through the system.

Session ID

sessionID is used to tie logs back to a user's session. The sessionID is fixed for the lifetime of a users sessions whereas the traceID is unique to a HTTP request. For more on sessionID logging, please see the docs.

Service ID

service identifies the source of logs. For example, service=samlProvider, service=proxyProvider,service=apis, or service=oidcProvider.

Service Extension Logging

Logs emitted from service extension include seName, seFuncName, and seChecksum.

• seName is the name of the service extension defined in the orchestrator configuration.

• seFuncName is the name of the function defined in the service extension.

• seChecksum is used to identify the content of the service extension. The checksum will change when the service extensions are updated.

For more information on how to configure service extension logging, see Service extensions.

Configuration options

Logging options can be set in the logger section of the Maverics config file.

Level

level determines the verbosity of the Orchestrator logs. For example, level: error will only show error logs (when debug mode is off). The following log levels are supported:

• debug

• info

• error

Enabling debug mode from the command line (-v/--verbose) or through the environment variable (MAVERICS_DEBUG_MODE) will take precedence over the level field.

Log Session IDs

logSessionID is used to append a session identifier in log messages. This setting is useful when filtering logs to isolate a problem with a particular session.

The identifier printed in the logs corresponds to a particular session, but it is not the actual session ID itself and hence cannot be used to impersonate a user's session.

Time format

timeFormat is used to change the formatting of the log timestamps. For example, a time format of timeFormat: ANSIC will create timestamps in the format ts=:"Mon Jan 2 15:04:05 2006".

The following format names are supported (case-insensitive):

Custom time formats can be specified with a layout string using the date in the examples above (Jan 2 15:04:05 2006) as per Golang's time format. For example:

logger:
  timeFormat: "2006-01-02 15:04:05 MST"

Orchestrator logs are always in UTC. When setting a custom timeFormat string as above, the MST time zone abbreviation (or -0700 offset) in the layout string does not change this but will set the position of UTC or -0000 in the timestamp.

Filters

Filters are a mechanism for suppressing log messages. Each filter defines a function that will be used to test potential log output. If any filter finds a match in any of the elements of a log line, the log line will not be output.

Use log filters with caution. Strata advises to only enable log filters if absolutely necessary. There is the possibility of inadvertently suppressing critical security logs. In addition, log filters can negatively impact orchestrator performance.

Type

The type of pattern matching algorithm. Can be either contains or regex.

Contains

Contains looks for an exact match in log messages.

Regex

The regex filter uses a regex engine to find matches for the given pattern in log messages.

You can use tools such as regex101 (choose Golang) to test your regex against log messages you would like to filter.

Poorly constructed regex can impact Orchestrator performance. Use anchors (^ or $) where possible, and counters or ranges (.{0,15}) instead of “greedy” wildcards (.*).

Pattern

The pattern to use for matching text.

Field Ordering

fieldOrdering organizes the fields in the log output. When enabled, the fields and their values will appear in the following order:
ts , level, service, traceID, sessionID, msg, <OTHERS>. Any additional fields will be listed after msg.

Field ordering incurs a performance impact. If performance is a concern, leave this option disabled.

Enabled

When enabled, field ordering will be applied to log messages.

Examples

logger:
  level: debug
  logSessionID: true 
  timeFormat: UnixDate
  fieldOrdering: 
    enabled: true

Log Filter

logger:
  filters:
    - type: regex
      pattern: '^content to be filtered$'
    - type: contains
      pattern: 'exact match'