Logging Redaction#

Added in version 2.2.0.

Starting in 2.2, ESS supports configurable redaction of JSON log messages.

Configure Redaction Rules#

For an ESS service, operators can configure various INRUPT_LOGGING_REDACTION_{NAME}_ settings to create the redaction rules.

To specify a rule for an ESS service, the operator:

  1. Determines a {NAME} to use for the redaction rule. See also Uniqueness of Rule Name.

  2. Determines the target of the redaction rule by setting one of the following configurations for the service:

    INRUPT_LOGGING_REDACTION_{NAME}_FIELD

    To target a specific log message field.

    INRUPT_LOGGING_REDACTION_{NAME}_PATTERN

    To target log message text that matches a specified pattern.

    INRUPT_LOGGING_REDACTION_{NAME}_EXCEPTION

    To target an exception message class.

  3. Specify the action in INRUPT_LOGGING_REDACTION_{NAME}_ACTION:

    Action

    Description

    REPLACE

    Default. Replaces the matching text with a specified replacement.

    PLAIN

    Leaves the matching field unprocessed. Only available if the redaction target is a field (i.e., INRUPT_LOGGING_REDACTION_{NAME}_FIELD).

    DROP

    Suppresses the matching field. Only available if the redaction target is a field (i.e., INRUPT_LOGGING_REDACTION_{NAME}_FIELD).

    PRIORITIZE

    Changes the log level of the matching message.

    SHA256

    Replaces the matching text with its hash.

    Alternatively, the operator can omit INRUPT_LOGGING_REDACTION_{NAME}_ACTION to use the default REPLACE; however, it is recommended to explicitly set the action.

  4. Specifies any associated configuration for the specified action:

    • If the action is REPLACE, the operator can specify INRUPT_LOGGING_REDACTION_{NAME}_REPLACEMENT (or use the default [REDACTED]).

    • If the action is to PRIORITIZE, the operator can specify the INRUPT_LOGGING_REDACTION_{NAME}_LEVEL (or use the default DEBUG).

Considerations#

Uniqueness of Rule Name#

Configurations with the same name, including redaction configurations, override the preceding value. For example, assume an operator has created the following redaction configuration for a service:

Configuration

Value

INRUPT_LOGGING_REDACTION_RULE1_FIELD

userid

INRUPT_LOGGING_REDACTION_RULE1_ACTION

PLAIN

These configurations create a configuration rule that:

  • Targets the field userid and

  • Uses the PLAIN action, which leaves the userid value as is.

If later on, the operator wants to update the target field to username instead of userid, the operator can update INRUPT_LOGGING_REDACTION_RULE1_FIELD configuration value to username.

With this configuration update, the updated configuration rule now:

  • Targets the field username and

  • Uses the PLAIN action, which leaves the username value as is.

However, consider if another operator wants to create a new redaction rule for this service. If this operator also uses RULE1 for the {NAME} and decides to use the default replace action, the operator may decide to only set the following configuration:

Configuration

Value

INRUPT_LOGGING_REDACTION_RULE1_FIELD

password

The second operator may assume that with this configuration, the redaction rule will use the default replace action with the default replacement [REDACTED]. Instead, the service has the following configurations in place:

Configuration

Value

INRUPT_LOGGING_REDACTION_RULE1_FIELD

password

INRUPT_LOGGING_REDACTION_RULE1_ACTION

PLAIN

Because the redaction configurations depend on a user-specified {NAME}:

  • Ensure the uniqueness of the {NAME} when creating new redaction rules.

  • Explicitly specify the action.