Logging in Knox

Sergei Tikhomirov

Logging settings

The Knox logging settings are defined in the log4j 2 format. The Knox Gateway component has two parameters that manage the logging process:

  • gateway-log4j2.xml template — it contains the logging configuration for the gateway and the audit process.

  • knoxshell-log4j2.xml — it contains the logging configuration for the HTTP client.

You can find the default contents of these files in the Knox configuration parameters.

To alter the logging behavior, edit the file parameters according to the log4j 2 logging rules.

Available logs

The Gateway component generates several files with various logging information. All of the mentioned files are stored in the var/log/knox directory:

  • gateway-audit.log — logs from the Audit facility that tracks Knox actions.

  • gateway.log — logs for the internal gateway operations.

  • gateway.err — logs that contain error descriptions (e.g. SLF4J: Class path contains multiple SLF4J bindings).

Some files may have a date in their name according to the time-based rolling policy that’s defined in the logging settings. Viewing logs is available only via CLI, use the following command:

$ cat var/log/knox/<log_file>

Audit logs

The audit logs are saved in the following format:

EVENT_PUBLISHING_TIME ROOT_REQUEST_ID|PARENT_REQUEST_ID|REQUEST_ID|LOGGER_NAME|TARGET_SERVICE_NAME|USER_NAME|PROXY_USER_NAME|SYSTEM_USER_NAME|ACTION|RESOURCE_TYPE|RESOURCE_NAME|OUTCOME|LOGGING_MESSAGE

where:

  • EVENT_PUBLISHING_TIME — the time when a record was written.

  • ROOT_REQUEST_ID — currently empty.

  • PARENT_REQUEST_ID — currently empty.

  • REQUEST_ID — a unique value representing the current request.

  • LOGGER_NAME — the name of a logger.

  • TARGET_SERVICE_NAME — the name of a Hadoop service. Can be empty if an audit record is not linked to any Hadoop service, for example, an audit record for topology deployment.

  • USER_NAME — the name of a user that initiated a session with Knox.

  • PROXY_USER_NAME — mapped user name.

  • SYSTEM_USER_NAME — currently empty.

  • ACTION — the type of action that was executed. The following actions are defined: authentication, authorization, redeploy, deploy, undeploy, identity-mapping, dispatch, access.

  • RESOURCE_TYPE — the type of resource for which an action was executed. The following resource types are defined: uri, topology, principal.

  • RESOURCE_NAME — the name of a resource. For the topology resource type, it is the name of a topology. For uri — it is inbound or dispatch request path. For principal — the name of a mapped user.

  • OUTCOME — the action result type. Following outcomes are defined: success, failure, unavailable.

  • LOGGING_MESSAGE — a logging message. Contains tracking information.

For example, here’s a log entry with fields mapped:

EVENT_PUBLISHING_TIME   25/01/23 12:25:31
ROOT_REQUEST_ID
PARENT_REQUEST_ID       |
REQUEST_ID              |27742083-7b22-4a87-8aa8-9befa06efcdc
LOGGER_NAME             |audit
TARGET_SERVICE_NAME     |
USER_NAME               |
PROXY_USER_NAME         |
SYSTEM_USER_NAME        |
ACTION                  |access
RESOURCE_TYPE           |uri
RESOURCE_NAME           |/gateway/homepage/favicon.ico
OUTCOME                 |success
LOGGING_MESSAGE         |Response status: 404

Gateway logs

The gateway logs are saved in the following format:

EVENT_PUBLISHING_TIME REQUEST_ID LOG_LEVEL TARGET_SERVICE_NAME LOGGING_MESSAGE

where:

  • EVENT_PUBLISHING_TIME — the time when an event occurred.

  • REQUEST_ID — a unique value representing the current request.

  • LOG_LEVEL — a level at which an event occurred. See possible logging levels.

  • TARGET_SERVICE_NAME — the name of a Hadoop service.

  • LOGGING_MESSAGE — a logging message. Contains tracking information.

For example, a gateway.log record may look like so:

2025-01-23 12:25:31,908 27742083-7b22-4a87-8aa8-9befa06efcdc WARN  knox.gateway (GatewayFilter.java:doFilter(202)) - Failed to match path /favicon.ico
Found a mistake? Seleсt text and press Ctrl+Enter to report it