Logging

Increase the Log Level on an ESS Microservice

ESS logging is configured through Quarkus.

By default, ESS microservices log at the INFO level. To change a service’s log level, update the QUARKUS_LOG_LEVEL environment variable for that service. For available log levels, see https://quarkus.io/guides/logging#logging-levels.

To change the logging level for a service and deploy it to the Kubernetes (K8s) cluster:

  1. Update the QUARKUS_LOG_LEVEL value in the service’s <service>-deployment.yaml file used to deploy into your Kubernetes cluster:

    - name: QUARKUS_LOG_LEVEL
      value: <New Log Level>
    
  2. Apply the changes to the cluster:

    kubectl apply -f <path to yaml>
    

    This restarts the service with the new log level.

For more information on Quarkus logging, see https://quarkus.io/guides/logging.

Configure Auditing

ESS services support auditing to log various system activities.

To set up specific service for auditing, see:

To configure audit messages for these services, see:

Set up LDP Service for Auditing

The following properties are available to set up LDP service to enable auditing.

Auditing Property for LDP

Description

quarkus.log.category."AuditLogger".handlers

The name of the audit handler for the LDP service.

  • To enable auditing, set the property to audit-syslog-handlers.

  • To disable auditing, leave the property unset.

Default value is unset; i.e., auditing is off by default.

To configure as an environment variable, use the QUARKUS_LOG_CATEGORY__AUDITLOGGER__HANDLERS.

quarkus.log.handler.syslog."audit-syslog-handlers".endpoint

The <host>:<port> of the Syslog server to which to send the the LDP service’s audit logs.

Default value is localhost:5140.

Alternatively, to configure as an environment variable, use QUARKUS_LOG_HANDLER_SYSLOG__AUDIT_SYSLOG_HANDLERS__ENDPOINT.

Important

The Audit messages are sent over TLS. The LDP service must import the Syslog server’s certificate into LDP’s cacerts file.

To configure the audit messages, see also:

Set up OIDC Broker Service for Auditing

The following properties are available to set up OIDC Broker service for auditing.

Auditing Property for OIDC Broker Service

Description

OIDC_AUDIT_ENABLE

To enable or disable auditing on the OIDC Broker.

  • To enable auditing, set the property to true.

  • To disable auditing, set the property to false, or leave this property unset.

Default value is unset.

OIDC_AUDIT_SYSLOG_HOST

The Syslog server’s host name to which to send the audit messages.

Default value is localhost.

OIDC_AUDIT_SYSLOG_PORT

Specifies the Syslog’s server’s port.

Default value is 5140.

OIDC_HTTP_SSL_CERTIFICATE_TRUST_STORE_FILE

Specifies the location of the OIDC Broker Service’s trust store file.

Important

The Audit messages are sent over TLS. The OIDC Broker Service must import the Syslog server’s certificate into the trust store file.

Default value is unset.

OIDC_HTTP_SSL_CERTIFICATE_TRUST_STORE_PASSWORD

Specifies the password of OIDC Broker Service’s trust store file.

To configure the audit messages for the service, see:

Configure Audit Messages

The following properties are available to configure the audit messages for the services. You can set these properties as system or environmental variables.

Property

Description

inrupt.audit.request.headers

A string or a comma-separated list of strings that determine the headers to include in request.* event messages. Only the specified headers will be included from the audit messages.

Default value: Accept,Content-Type,Link,Slug

inrupt.audit.properties.include-filter

A string or a comma-separated list of strings that determine the configuration properties to include in the service.configuration event messages. For each specified string, the Audit system performs a case-insensitive starts-with match on the property names. Only those properties that match are included in the audit messages.

For example, a value of trellis.,inrupt. includes all configuration properties that start with trellis. or inrupt., e.g., inrupt.register.registrar-agent.

Default values for:

  • LDP Service: trellis.,inrupt.

  • OIDC Broker Service: oidc_

inrupt.audit.properties.mask-filter

A string or a comma-separated list of strings that determine the properties (e.g., passwords, secret keys, etc.) to mask in the audit log messages. For each specified string, the Audit system performs a case-insensitive search for the string in the property names. Those properties whose names contain the string are masked in the audit messages.

For example, a value of secret masks the value of all properties whose name contain the string secret; e.g., inrupt.resource.secret=xxxxx.

Default values for:

  • LDP Service: password,secret

  • OIDC Broker Service: password

See also:

Retrieve Logs

ESS consists of multiple K8s pods (instances) running on multiple nodes (servers) in a K8s cluster. Kubernetes manages the orchestration of all these containers. You can retrieve the logs directly from Kubernetes or integrate into a centralized logging platform.

Retrieve Logs Directly from Kubernetes

To retrieve the logs displayed to stdout, run the kubectl logs command:

kubectl logs --follow <service app deployment>

Centralized Logging to a Backend Logging System

As your ESS deployment grows, logging to a centralized backend logging system can help manage your logs. You can set up a centralized logging system for your ESS deployment in Kubernetes. For more information, see Kubernetes: Logging.

See also: