Centralize your observability stack with OpenTelemetry

Learn about OpenTelemetry integration for centralized observability and telemetry data.

OpenTelemetry (OTel) is an open-source observability framework designed to provide consistent and reliable ways to collect telemetry data across distributed systems. It is a project under the Cloud Native Computing Foundation (CNCF) as an incubating project. Its goal is to provide a unified standard and toolset for instrumenting, generating, and exporting telemetry data from modern applications, making it easier to monitor, debug, and understand complex services.

The goal of Keycloak is to support OpenTelemetry Logs, Metrics, and Traces to create a centralized observability stack without any additional deployment overhead.

General options

Keycloak provides support for global settings of telemetry data export. It means that you can configure connection parameters to a single OpenTelemetry collector that will be used for all supported components.

In order to have OpenTelemetry enabled, at least one component needs to be turned on, for example Traces.

The OpenTelemetry feature is enabled by default. Disable the feature in order to disable OpenTelemetry components.

Endpoint

You can configure the OpenTelemetry collector’s global endpoint that is shared across all components by using the telemetry-endpoint option. The default value is http://localhost:4317.

You can change the endpoint via CLI as follows:

bin/kc.[sh|bat] start --telemetry-endpoint=http://my-otel-endpoint:4317

Service name

You can configure the global OpenTelemetry service name used for identifying the exporter of the telemetry data. The default service name is keycloak, specified via the telemetry-service-name property, which takes precedence over service.name defined in the telemetry-resource-attributes property.

You can change the service name via CLI as follows:

bin/kc.[sh|bat] start --telemetry-service-name=my-keycloak-iam

Protocol

You can configure the global OpenTelemetry transport protocol used as a communication channel between Keycloak and the OpenTelemetry collector. The default value is grpc.

Keycloak supports these communication protocols:

  • grpc (default)

  • http/protobuf

You can change the protocol via CLI as follows:

bin/kc.[sh|bat] start --telemetry-protocol=http/protobuf

Traces

See the Root cause analysis with tracing guide.

You can override the global OpenTelemetry settings via the Tracing options if you want to export traces to a different OpenTelemetry collector.

Logs

OpenTelemetry Logs support is Preview and is not fully supported. This feature is disabled by default.

To enable start the server with --features=preview or --features=opentelemetry-logs
The OpenTelemetry feature (opentelemetry) needs to be turned on (by default).

It is possible to export Keycloak’s logs to the OpenTelemetry collector and be managed by various logging backends that support OpenTelemetry.

Enable Logs

You can enable OpenTelemetry Logs via CLI as follows:

bin/kc.[sh|bat] start --features=opentelemetry-logs --telemetry-logs-enabled=true

For more information on how to set up logging, see the Configuring Logging guide.

Log level

By default, all log levels are exported by Keycloak. You can optionally configure the most verbose log level to be exported via the telemetry-logs-level option.

For example, if you want only to export WARN and ERROR logs, you can change the log level via the CLI as follows:

bin/kc.[sh|bat] start --telemetry-logs-level=WARN

Development setup

For development purposes, you can use the Grafana OTel-LGTM service, containing OpenTelemetry Collector and backends for logs (Loki), metrics (Prometheus), and traces (Tempo).

grafana otel lgtm
Figure 1. Service architecture

You can start the service by using Docker/Podman as follows:

docker run -p 3000:3000 -p 4317:4317 -p 4318:4318 --rm -ti grafana/otel-lgtm

Then, you can navigate to Grafana UI by accessing localhost:3000 and then you can explore all the data sent to OpenTelemetry Collector.

Relevant options

Type or Values Default

telemetry-endpoint

OpenTelemetry endpoint to connect to.

CLI: --telemetry-endpoint
Env: KC_TELEMETRY_ENDPOINT

Available only when any of available OpenTelemetry components (Logs, Traces) is turned on

String

http://localhost:4317

telemetry-protocol

OpenTelemetry protocol used for the communication between server and OpenTelemetry collector.

CLI: --telemetry-protocol
Env: KC_TELEMETRY_PROTOCOL

Available only when any of available OpenTelemetry components (Logs, Traces) is turned on

grpc, http/protobuf

grpc

telemetry-resource-attributes

OpenTelemetry resource attributes characterize the telemetry producer.

Values in format key1=val1,key2=val2.

CLI: --telemetry-resource-attributes
Env: KC_TELEMETRY_RESOURCE_ATTRIBUTES

Available only when any of available OpenTelemetry components (Logs, Traces) is turned on

List

telemetry-service-name

OpenTelemetry service name.

Takes precedence over service.name defined in the telemetry-resource-attributes property.

CLI: --telemetry-service-name
Env: KC_TELEMETRY_SERVICE_NAME

Available only when any of available OpenTelemetry components (Logs, Traces) is turned on

String

keycloak

Traces

Type or Values Default

tracing-enabled

Enables the OpenTelemetry tracing.

CLI: --tracing-enabled
Env: KC_TRACING_ENABLED

Available only when 'opentelemetry' feature is enabled

true, false

false

tracing-endpoint

OpenTelemetry endpoint to connect to for traces.

If not given, the value is inherited from the telemetry-endpoint option.

CLI: --tracing-endpoint
Env: KC_TRACING_ENDPOINT

Available only when Tracing is enabled

String

http://localhost:4317

tracing-protocol

OpenTelemetry protocol used for the telemetry data.

If not given, the value is inherited from the telemetry-protocol option.

CLI: --tracing-protocol
Env: KC_TRACING_PROTOCOL

Available only when Tracing is enabled

grpc, http/protobuf

grpc

tracing-resource-attributes

OpenTelemetry resource attributes present in the exported trace to characterize the telemetry producer.

Values in format key1=val1,key2=val2. If not given, the value is inherited from the telemetry-resource-attributes option. For more information, check the Tracing guide.

CLI: --tracing-resource-attributes
Env: KC_TRACING_RESOURCE_ATTRIBUTES

Available only when Tracing is enabled

DEPRECATED. Resource attributes are not directly related to Tracing and you should use the Telemetry option which takes precedence. Use: telemetry-resource-attributes.

List

tracing-service-name

OpenTelemetry service name.

Takes precedence over service.name defined in the tracing-resource-attributes property. If not given, the value is inherited from the telemetry-service-name option.

CLI: --tracing-service-name
Env: KC_TRACING_SERVICE_NAME

Available only when Tracing is enabled

DEPRECATED. Service name is not directly related to Tracing and you should use the Telemetry option which takes precedence. Use: telemetry-service-name.

String

keycloak

Logs

Type or Values Default

telemetry-logs-enabled

Enables exporting logs to a destination handling telemetry data (OpenTelemetry Logs).

CLI: --telemetry-logs-enabled
Env: KC_TELEMETRY_LOGS_ENABLED

Available only when feature 'opentelemetry-logs:v1' is enabled

true, false

false

telemetry-logs-endpoint

Telemetry (OpenTelemetry) endpoint to export logs to.

If not given, the value is inherited from the telemetry-endpoint option.

CLI: --telemetry-logs-endpoint
Env: KC_TELEMETRY_LOGS_ENDPOINT

Available only when Telemetry Logs functionality ('telemetry-logs-enabled') is enabled

String

telemetry-logs-level

The most verbose log level exported to the telemetry endpoint.

For more information, check the Telemetry guide.

CLI: --telemetry-logs-level
Env: KC_TELEMETRY_LOGS_LEVEL

Available only when Telemetry Logs functionality ('telemetry-logs-enabled') is enabled

off, fatal, error, warn, info, debug, trace, all

all

telemetry-logs-protocol

Telemetry (OpenTelemetry) protocol used for exporting logs.

If not given, the value is inherited from the telemetry-protocol option.

CLI: --telemetry-logs-protocol
Env: KC_TELEMETRY_LOGS_PROTOCOL

Available only when Telemetry Logs functionality ('telemetry-logs-enabled') is enabled

grpc, http/protobuf
On this page
Edit this guide