> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingesting with OpenTelemetry

> Configure OpenTelemetry SDKs and collectors to send logs, metrics, and traces to fully managed ClickHouse Observability.

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> 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.
>
> ![Managed Telemetry showing the masked OTLP HTTP endpoint and API key](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-managed-telemetry.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=e63a2ac2e6ab996d3fc360ebe0f487a5)
>
> 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:
>
> ```shell theme={null}
> 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](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/) 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](https://clickhouse.com/docs/clickstack/observability/features/session-replay.md).
>
> ## 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:
>
> ```shell theme={null}
> 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:
>
> ```yaml theme={null}
> 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](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter) for configuration options.
>
> For a complete example that collects host logs and metrics, see [Local system logs and metrics](https://clickhouse.com/docs/clickstack/observability/example-datasets/local-data.md).
>
> ## Verify ingestion
>
> Generate telemetry in your application, then open [Search](https://clickhouse.com/docs/clickstack/observability/features/search.md) 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.

> [tab] Self-managed
>
> 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](#installing-otel-collector-managed-self-configured) of the collector.
>
> Send data to this collector from [language SDKs](https://clickhouse.com/docs/clickstack/observability/ingesting-data/sdks.md) or agents that collect infrastructure logs and metrics. These can include OpenTelemetry collectors in an [agent role](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#collector-roles-self-configured), [Fluentd](https://www.fluentd.org/), or [Vector](https://vector.dev/). For centralized collector management, [Bindplane](https://clickhouse.com/docs/clickstack/observability/integration-partners/bindplane.md) 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](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#collector-roles-self-configured) to receive OTLP over HTTP or gRPC and forward it to ClickHouse Cloud.
>
> > [!NOTE]
> >
> > **We recommend using the ClickStack OpenTelemetry collector**
> >
> > The 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](https://clickhouse.com/docs/products/cloud/guides/sql-console/connection-details.md). Configure these environment variables in the runtime of the ClickStack distribution of the collector:
>
> ```shell theme={null}
> 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](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#creating-an-ingestion-user-self-configured). 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](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#modifying-otel-collector-configuration-managed-self-configured) for an example.
>
> For installation instructions, see [Deploying the collector](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#configuring-the-collector-self-configured). Before sending production traffic, [secure the collector](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#securing-the-collector-self-configured). 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](https://clickhouse.com/docs/clickstack/observability/ingesting-data/sdks.md) that support environment-variable configuration, set the endpoint and protocol before starting your instrumented application:
>
> ```shell theme={null}
> 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](https://github.com/open-telemetry/opentelemetry-collector-contrib) can forward logs over OTLP. The example below reads this [structured log file](https://datasets-documentation.s3.eu-west-3.amazonaws.com/http_logs/access-structured.log.gz). 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.
>
> ```yaml theme={null}
> # 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]
> ```