Log masking

Overview Copied

Log masking applies ordered regular-expression replacements to log lines before they are written. You define a rules file (YAML or JSON) that lists one or more rules. Each rule has:

The file must contain a top-level maskingRules array. The same starter rules file is shipped with native binaries as templates/log-masking-rules.yaml and is also the source for the YAML file bundled with Java log-masking packages (for example under config/geneos-log-masking/ or resources/geneos-log-masking/).

If a native process cannot load the rules file, a critical message is written to the log destination describing the failure; fix the path or file contents before relying on masking.

Example rules Copied

Rules are evaluated in list order; each rule runs on the whole line after the previous rule’s replacements.

Simple: replace a full match (example.com hostnames) Copied

The shipped log-masking-rules.yaml (for example under config/geneos-log-masking/ on Web Server) includes a rule that matches fully qualified names under example.com or example.con and replaces the entire hostname with a fixed string. Log lines are unchanged except where this pattern matches.

  - name: FQDN_example_com_or_con
    regex: '(?i)\b(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+example\.(?:com|con)(?!\.[A-Za-z0-9-])\b'
    replacement: '[redacted-host]'

Example: a line containing https://app.example.com/path becomes https://[redacted-host]/path (only the hostname segment is matched and substituted).

More complex: keep scheme and path, redact host (capture groups) Copied

Use parentheses in regex to define capture groups, then reference them in replacement as $1, $2, and so on. The rule below keeps http:// or https://, keeps everything after the authority (path, query string, fragment), and replaces only the host part (including an optional :port) with a fixed label.

  - name: RedactHttpUrlAuthority
    regex: '(https?://)([^/?#]+)(.*)'
    replacement: '$1[redacted-host]$3'

Examples

Before After
call https://anyhost.anydomain/patha/pathb ok call https://[redacted-host]/patha/pathb ok
GET http://anyhost/health GET http://[redacted-host]/health
x https://anyhost.anydomain:234/patha?q=1 x https://[redacted-host]/patha?q=1

Native processes (C++) Copied

Command-line option: -logMaskingRules <path-to-file>

<path-to-file> may be absolute or relative. YAML (.yaml, .yml) or JSON (.json) is supported.

Applies to: Gateway, Netprobe, Webslinger, Licence Daemon, Fix Analyser Agent, and Fix Analyser 2 Netprobe builds.

Pass the option when starting the binary, for example:

./gateway2.linux_64 -setup gateway.setup.xml -logMaskingRules /opt/geneos/config/masking-rules.yaml

Java components (Log4j2 and Logback) Copied

System property: geneos.logMasking.rules — path to the same YAML or JSON rules file used for native masking.

The product ships small Geneos log masking libraries (Java 11 bytecode; use JVM 11+):

Module Purpose
geneos-log-masking.jar Core rules engine and YAML/JSON parsing (com.itrsgroup.logmasking).
geneos-log-masking-log4j.jar Log4j2 layout: com.itrsgroup.logmasking.log4j2.LogMaskingPatternLayout (plugin name LogMaskingPatternLayout).
geneos-log-masking-logback.jar Logback layout: com.itrsgroup.logmasking.logback.LogMaskingPatternLayout.

Use the Log4j2 adapter together with the core JAR on the classpath for Active Console, Gateway Setup Editor (when using the bundled Log4j2 configuration), and Web Dashboard / Web Server. Use the Logback adapter with the core JAR for Java plug-ins and other Logback-based processes.

Example templates ship with the product:

If geneos.logMasking.rules is unset or empty, layouts behave like a normal pattern layout (no masking).

Active Console 2 and Gateway Setup Editor Copied

The installation includes resources/geneos-log-masking/ with JARs, log-masking-rules.yaml, and Log4j2 templates. The shipped ActiveConsole.gci file lists optional JVM system properties under -jvmargs. To enable masking:

  1. Edit ActiveConsole.gci and uncomment the line that sets Dgeneos.logMasking.rules (it points at resources/geneos-log-masking/log-masking-rules.yaml by default), or replace that value with the path to your own rules file.
  2. Log4j2 is already configured to use LogMaskingPatternLayout when the property is set, as in log4j2-log-masking.template.xml.

The same pattern applies to Gateway Setup Editor settings embedded in the same ActiveConsole.gci (GSE runs in-process with the same JVM arguments).

Web Dashboard (Web Server) Copied

Under config/geneos-log-masking/ you will find JARs, log-masking-rules.yaml, and the Log4j2 template. The run and no_jre/run scripts (Linux and Unix) define an optional shell variable LOG_MASKING and pass $LOG_MASKING on the java command line (after -Dlog4j2.configurationFile=...). To enable masking:

  1. Open run or no_jre/run in the Web Dashboard installation directory.
  2. Uncomment the line that sets LOG_MASKING to -Dgeneos.logMasking.rules=${SCRIPTPATH}/config/geneos-log-masking/log-masking-rules.yaml, or set it to your own rules file path.

On Windows, open run.bat or no_jre/run.bat and uncomment the line set LOG_MASKING=-Dgeneos.logMasking.rules=config\geneos-log-masking\log-masking-rules.yaml (or adjust the path). The java command already includes %LOG_MASKING%.

If you start Web Dashboard using the geneosws service script instead of run, add the same -Dgeneos.logMasking.rules=... JVM option to the java invocation in that script (or mirror the LOG_MASKING pattern from run).

Netprobe and embedded Java Copied

See also Copied

["Geneos"] ["Geneos > Gateway"] ["Technical Reference"]

Was this topic helpful?