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, you can use Kustomize overlays to update the QUARKUS_LOG_LEVEL value.

Create an overlay structure as described in Customize ESS.

Add the customization overlay:

#kustomization.yaml

...

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component

patches:
  - target:
      kind: Deployment
      name: ess-ldp
    patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: not-important
      spec:
        template:
          spec:
            containers:
              - name: ess-ldp
                env:
                  - name: QUARKUS_LOG_LEVEL
                    value: DEBUG

For more information on customizing ESS, see Customize ESS.

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:

Set up LDP Service for Auditing

To configure audit messages for these services, see:

Configure Audit Messages.

Set up LDP Service for Auditing#

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

Auditing Property for LDP
`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.

Auditing Property for LDP

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:

Configure Audit Messages.

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.`
`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`

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.

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

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.