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:

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

Set up LDP Service for Auditing
Set up Solid OIDC Broker 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	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.

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:

Configure Audit Messages.

Set up Solid OIDC Broker Service for Auditing#

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

Auditing Property for the Solid OIDC Broker Service	Description
`OIDC_AUDIT_ENABLE`	To enable or disable auditing on the Solid 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 Solid OIDC Broker Service’s trust store file. Important The Audit messages are sent over TLS. The Solid 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 the Solid OIDC Broker Service’s trust store file.

To configure the audit messages for the service, see:

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.` Solid 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` Solid OIDC Broker Service: `password`

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.
Solid 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
Solid OIDC Broker Service: password

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.