Changing the Log Level at Runtime

1. Overview

The VeridiumID platform supports changing the logging level of specific Java classes or packages while the services are running, no restart, no configuration file edit on the host.

A single JSON document, edited centrally in websecadmin and stored in ZooKeeper, defines which loggers run at which level. Every service watches that document and applies the changes to its own logging context within seconds.

This is intended for temporary, targeted diagnostics: raising a class to DEBUG while reproducing an issue, then returning it to INFO once the investigation is closed.

2. Architecture and mechanism

2.1. Components

2.2. End-to-end flow

1. Edit the JSON document (logging.json) in websecadmin and saves it.

2. websecadmin validates the document and writes it to the ZooKeeper node /log-streaming/logging.json.

3. ZooKeeper fires a notification (NodeDataChanged) to every connected service.

4. In each service, LoggingZookeeperObserver receives the new document and GenericLoggingConfigStorage locates the section whose name matches the service's own identity.

5. The configuration is compared against the previously applied state, and ChangeLogLevelHandler reconfigures the Log4j2 LoggerContext accordingly (updateLoggers()).

The level change is applied in memory, to the loggers already created in the JVM. The on-disk log4j2.xml file is not touched and the process is not restarted.

2.3. Propagation and timing

• Propagation is push-based (ZooKeeper)

• The mechanism never restarts a service. Applying a level change is a live, in-memory reconfiguration of the running process.

• If a service runs as multiple instances (nodes), the change reaches all of them at once, there is no need to apply it node by node.

• If a service is restarted later, for an unrelated reason (a deployment, maintenance, a crash), it re-reads the node on startup and re-applies the stored levels, so the setting is not lost

3. Configuration file

3.1. Location

ZooKeeper node: /log-streaming/logging.json

Edit via: websecadmin → Advanced Configuration → /log-streaming/logging.json

Access requires an administrative role (ADMIN, APPADMIN, or SYSCONFIG). Every save is audited.

3.2. Structure

{
  "services": [
    {
      "name": "ver_tomcat",
      "loggers": [
        {
          "logLevel": "DEBUG",
          "packagesNames": ["com.veridiumid.websec"]
        }
      ]
    },
    {
      "name": "ver_selfservice",
      "loggers": [
        {
          "logLevel": "DEBUG",
          "packagesNames": ["com.veridiumid.ssp"]
        }
      ]
    }
  ]
}

The example above is a valid document.

3.3. Field reference

3.4. Supported services reference

The name field is not the module name , it is the runtime ServiceName the service is started with (-DServiceName). The table below lists every service that currently supports this mechanism, together with its ServiceName and its root Java package.

If a ServiceName is not set on a service, it falls back to ver_noname and will not match any entry.

3.5. Reference configuration

The document below contains an entry for every supported service. It is safe to apply as is: each rule is set to INFO (the normal operating level), so applying it changes nothing until you edit it.

To investigate an issue, change logLevel to DEBUG for the service(s) you need, and recommended is to narrow packagesNames from the root package to the specific class under investigation.

{
  "services": [
    {
      "name": "ver_tomcat",
      "loggers": [
        { 
          "logLevel": "INFO", 
          "packagesNames": ["com.veridiumid.websec"] 
        }
      ]
    },
    {
      "name": "ver_websecadmin",
      "loggers": [
        { 
           "logLevel": "INFO", 
           "packagesNames": ["com.veridiumid.admin"] 
        }
      ]
    },
    {
      "name": "ver_fido",
      "loggers": [
        { 
          "logLevel": "INFO", 
          "packagesNames": ["com.veridiumid.webauthn"] 
        }
      ]
    },
    {
      "name": "ver_selfservice",
      "loggers": [
        { 
          "logLevel": "INFO", 
          "packagesNames": ["com.veridiumid.ssp"] 
        }
      ]
    }
  ]
}

Keeping all four services listed at all times is recommended: it serves as a ready template, so during an incident/investigation you only flip a level instead of reconstructing the document.

4. Accepted log levels

logLevel accepts the following values (case-insensitive):

OFF · FATAL · ERROR · WARN · INFO · DEBUG · TRACE · ALL

• INFO — the normal operating level

• DEBUG — the level normally used for diagnostics

• TRACE — it produces a very high log volume

5. Operating procedure

5.1. Enable debug logging for a class

1. Open websecadmin → Advanced Configuration and select the node /log-streaming/logging.json.

2. Locate the entry for the target service (or add one, using the correct name).

3. Add a logger rule with logLevel: "DEBUG" and the target class or package in packagesNames.

4. Save. The change propagates to all instances of the service within seconds.

5.2. Verify the change took effect

• Confirm DEBUG lines from the target class appear in the service log.

• If nothing changes, check the service log for Unknown service name detected, this indicates the name did not match.

5.3. Revert after the investigation

Set the rule's logLevel back to INFO or remove the package name and save.

Note: in order to have debug logs for Shibboleth, the following procedure should be applied:

1. Go to websecadmin → Advanced → shibboleth → idp.properties

2. add below line in the file and press save

idp.loglevel.root=DEBUG

6. Best practices and limitations

• Always use the exact name. A mismatched name fails silently (only a warning in the log).

• Target narrowly. Prefer a specific class or a leaf package over a broad package such as com.veridiumid. Broad DEBUG produces large log volume and may write sensitive data to the logs.

• Treat changes as temporary. Because the setting persists across restarts, an enabled DEBUG will stay active indefinitely. Return it to INFO once the investigation is closed.

• Use DEBUG, not TRACE, unless TRACE is specifically required, and only for short periods.

• Scope: the mechanism currently covers websec, websecadmin, fido and selfservice.

7. Troubleshooting

Last updated: August 17, 2026