Ingesting with OpenTelemetry

Fully managed
Self-managed

Send logs, metrics, and traces to ClickHouse Observability using OpenTelemetry SDKs or a collector in your environment. The service includes a managed ingestion collector that receives telemetry over OTLP and writes it to ClickHouse Cloud.

Get your connection details

Open your service and navigate to Team Settings → Data → Managed Telemetry. Copy the OTLP HTTP endpoint and API key. The Env vars and Collector config tabs provide configuration for your service.Use the full HTTPS endpoint, including the port shown in Managed Telemetry. For a base OTLP HTTP endpoint, omit signal paths such as /v1/logs, /v1/traces, and /v1/metrics; the exporters append these paths.

Send directly from an application

Install and initialize OpenTelemetry instrumentation and an OTLP HTTP exporter for your application’s language. For SDKs that support environment-variable configuration, set these values in the application’s environment before starting it:

export OTEL_SERVICE_NAME='my-service'
export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_OTEL_ENDPOINT:4318'
export OTEL_EXPORTER_OTLP_HEADERS='authorization=Bearer%20YOUR_API_KEY'

Replace the endpoint with the exact value from Managed Telemetry and YOUR_API_KEY with your service’s API key. The %20 encodes the space between Bearer and the key in the header environment variable.Environment-variable support varies by SDK. If your SDK requires configuration in code, supply the same HTTPS endpoint, OTLP HTTP protocol, and an authorization header with the value Bearer YOUR_API_KEY. See the OpenTelemetry exporter configuration reference for language support and signal-specific overrides.These settings configure export; your application still needs instrumentation to generate telemetry. For browser session recordings, follow the Session replay guide.

Forward data from a collector

If you already collect telemetry with an OpenTelemetry collector, configure an OTLP HTTP exporter to forward it to the managed endpoint. Keep your existing receivers and processors for collecting and processing data.Set the following environment variables in the collector’s runtime:

export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_OTEL_ENDPOINT:4318'
export OTEL_EXPORTER_OTLP_API_KEY='YOUR_API_KEY'

Replace both placeholders with the values from Managed Telemetry. Add this exporter to your collector configuration:

exporters:
  otlp_http/observability:
    endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT}
    headers:
      authorization: "Bearer ${env:OTEL_EXPORTER_OTLP_API_KEY}"

Add otlp_http/observability to the exporters list of each logs, metrics, or traces pipeline you want to forward under service.pipelines. Merge it into your existing configuration, then restart or redeploy the collector to apply the changes.The example uses the current otlp_http exporter name. Older collector releases may use otlphttp; use the name supported by your distribution. See the OTLP HTTP exporter documentation for configuration options.For a complete example that collects host logs and metrics, see Local system logs and metrics.

Verify ingestion

Generate telemetry in your application, then open Search in ClickHouse Observability. Select Logs or Traces, choose a time range that includes the new events, and search for your service name.If data does not appear, check your SDK or collector logs for export errors. Verify the endpoint, authentication header, and protocol, and confirm that the application or collector can reach the managed endpoint. Also check for signal-specific exporter settings that override the base endpoint or headers.You can use Send a Test Log in Managed Telemetry to submit a sample log to the service. Verify your application’s telemetry separately to confirm its instrumentation and export configuration.

For self-managed ClickHouse Observability, an OpenTelemetry (OTel) collector receives logs, metrics, traces, and session data and writes them to ClickHouse Cloud. We recommend the official ClickStack distribution of the collector.Send data to this collector from language SDKs or agents that collect infrastructure logs and metrics. These can include OpenTelemetry collectors in an agent role, Fluentd, or Vector. For centralized collector management, Bindplane provides a ClickHouse Observability destination and tools for collecting, processing, and routing telemetry.

Sending OpenTelemetry data

Connect the collector to ClickHouse Cloud

Configure your collector in a gateway role to receive OTLP over HTTP or gRPC and forward it to ClickHouse Cloud.

We recommend using the ClickStack OpenTelemetry collectorThe ClickStack distribution provides processing and schemas compatible with ClickHouse Observability. The default schema enables automatic source detection and preconfigured column mappings.

In ClickHouse Cloud, open your service and get its connection details. Configure these environment variables in the runtime of the ClickStack distribution of the collector:

CLICKHOUSE_ENDPOINT="https://<host>:8443"
CLICKHOUSE_USER="<ingestion-user>"
CLICKHOUSE_PASSWORD="<ingestion-password>"

Use your service’s HTTPS database endpoint for CLICKHOUSE_ENDPOINT and the credentials of a dedicated ingestion user. Restart or redeploy the collector to apply the settings. It receives telemetry over OTLP and writes it to your ClickHouse Cloud service.If you use another collector distribution, configure its ClickHouse exporter with the same endpoint and credentials. See Modifying configuration for an example.For installation instructions, see Deploying the collector. Before sending production traffic, secure the collector. If you enable OTLP_AUTH_TOKEN, configure your SDKs and forwarding collectors to send that token in the authorization header.

Sending data to the collector

For a collector running locally with the default OTLP ports, point your OpenTelemetry instrumentation to the endpoints below. If your applications or agents run on another host or in another container, replace localhost with the collector hostname reachable from that environment:

HTTP (OTLP): http://localhost:4318
gRPC (OTLP): localhost:4317

For language SDKs that support environment-variable configuration, set the endpoint and protocol before starting your instrumented application:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

If the collector requires authentication, also set OTEL_EXPORTER_OTLP_HEADERS="authorization=<collector-token>", replacing <collector-token> with its OTLP_AUTH_TOKEN value. Do not add the Bearer prefix used by fully managed endpoints. These settings configure export; the application still needs instrumentation to generate telemetry.An agent using the contrib distribution of the OTel collector can forward logs over OTLP. The example below reads this structured log file. Download and decompress it to the path in include before starting the agent. If your gateway requires authentication, add an authorization header containing its token to the agent exporter.

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    compression: gzip

  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Modified as 2 collectors running on same host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

Introduction

Features

Administration

Guides

Integration partners

Self-managed

Get your connection details

Send directly from an application

Forward data from a collector

Verify ingestion

Sending OpenTelemetry data

Connect the collector to ClickHouse Cloud

Sending data to the collector

​Get your connection details

​Send directly from an application

​Forward data from a collector

​Verify ingestion

​Sending OpenTelemetry data

​Connect the collector to ClickHouse Cloud

​Sending data to the collector

Get your connection details

Send directly from an application

Forward data from a collector

Verify ingestion

Sending OpenTelemetry data

Connect the collector to ClickHouse Cloud

Sending data to the collector