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

# Getting started with Self-managed ClickHouse Observability

> Getting started with Self-managed ClickHouse Observability

> [!NOTE]
>
> This page covers **self-managed ClickHouse Observability**. For the recommended fully managed experience, see the documentation [here](https://clickhouse.com/docs/clickstack/observability/getting-started.md).

Deploy Self-managed ClickHouse Observability on ClickHouse Cloud, send a test event through your ingestion pipeline, and confirm that the event is available in the observability UI.

ClickHouse Cloud operates the ClickHouse backend while you retain control over the ingestion pipeline and schema. Self-managed ClickHouse Observability provides:

* Automatic scaling of compute, independent of storage
* Low-cost and effectively unlimited retention based on object storage
* Independent isolation of read and write workloads with [warehouses](https://clickhouse.com/docs/products/cloud/features/infrastructure/warehouses.md)
* Integrated authentication
* Automated backups
* Security and compliance features
* Seamless upgrades

## Before you begin

You can also send data directly to ClickHouse using a [supported integration](https://clickhouse.com/docs/integrations/home.md) and your own schema.

### Create a ClickHouse Cloud service

Complete [Create a ClickHouse service](https://clickhouse.com/docs/get-started/setup/cloud.md#1-create-a-clickhouse-service) in the ClickHouse Cloud quickstart. Before continuing, confirm that the service is running.

**OpenTelemetry**

> [!TIP]
>
> This page is showing the **OpenTelemetry** path. Use the guide selector near the top of the guide to switch between **OpenTelemetry** (recommended) and **Vector**.

### Prepare your ingestion environment

* To start a new [OpenTelemetry Collector](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md), install [Docker](https://docs.docker.com/get-docker/). For Kubernetes, deploy the collector with [Helm](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#configuring-the-collector-self-configured).
* To use an existing collector, run it in the [gateway role](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#collector-roles-self-configured) and ensure that its distribution includes the [ClickHouse exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/clickhouseexporter). You will add the required configuration in this guide.

## Set up Self-managed ClickHouse Observability

### 1. Choose an ingestion source and collector setup

From your ClickHouse Cloud service, open ClickHouse Observability. On the **Getting Started** page, select **Start ingestion**.

![Start ingestion](https://mintcdn.com/private-7c7dfe99/E1Oh1nXf1f-XPStr/images/clickstack/getting-started/start_ingestion.webp?fit=max\&auto=format\&n=E1Oh1nXf1f-XPStr\&q=85\&s=85347702d968ca5646fc176d067f9e5a)

On the **Choose an ingestion source** page, select [OpenTelemetry](https://opentelemetry.io/).

> [!NOTE]
>
> **OpenTelemetry recommended**
>
> OpenTelemetry provides preconfigured schemas for logs, traces, metrics, and sessions.

![Select OpenTelemetry as the ingestion source](https://mintcdn.com/private-7c7dfe99/E1Oh1nXf1f-XPStr/images/clickstack/getting-started/select_source_toggle.webp?fit=max\&auto=format\&n=E1Oh1nXf1f-XPStr\&q=85\&s=10ae315c29fee050894a657177f233da)

> [tab] Start a new collector
>
> The UI generates the collector command with the `default` administrator credentials. We recommend dedicated ingestion credentials to keep ingestion access separate from administration and avoid relying on the administrator password.
>
> > [accordion] Create dedicated ingestion credentials (recommended)
> >
> > In ClickHouse Cloud, open your service's SQL console and run:
> >
> > ```sql theme={null}
> > CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
> > GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, CREATE VIEW ON default.* TO `clickstack-ingest`;
> > ```
> >
> > In the generated command, replace `CLICKHOUSE_USER="default"` with `CLICKHOUSE_USER="clickstack-ingest"` and set `CLICKHOUSE_PASSWORD` to the dedicated user's password.
>
> To continue with the `default` administrator credentials, copy the command from the **Start Collector** tab. The UI pre-populates the service endpoint. Replace the password placeholder with your service password. If you no longer have it, [gather or reset your connection details](https://clickhouse.com/docs/products/cloud/guides/sql-console/connection-details.md).
>
> The command follows this format:
>
> ```shell theme={null}
> docker run -e CLICKHOUSE_ENDPOINT="https://<host>:8443" \
>     -e CLICKHOUSE_USER="default" \
>     -e CLICKHOUSE_PASSWORD="<your_password_here>" \
>     -p 4317:4317 -p 4318:4318 \
>     clickhouse/clickstack-otel-collector:latest
> ```
>
> Replace `<host>` and `<your_password_here>` with the values for your ClickHouse Cloud service, then run the command.
>
> The collector runs in the foreground. Leave this terminal open and use a second terminal for the remaining commands in this guide.
>
> > [!NOTE]
> >
> > This command exposes the OTLP ports without authentication and is intended for local evaluation. Before sending production traffic, [secure the collector](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#securing-the-collector-self-configured).

> [tab] Use an existing collector
>
> Select **Configure existing collector**, then adapt your collector configuration.
>
> Run the collector as a gateway between your applications and ClickHouse Cloud. The configuration below adds the required ClickHouse exporters and signal pipelines.
>
> The example uses the `default` credentials generated by the UI. To use dedicated ingestion credentials, follow the optional setup on the **Start a new collector** tab. In both ClickHouse exporter blocks, replace `username: default` with `username: clickstack-ingest` and set `password` to the dedicated user's password.
>
> Merge the following components into your existing configuration rather than replacing unrelated receivers, processors, exporters, or extensions.
>
> > [!NOTE]
> >
> > **Collector components required**
> >
> > Your collector distribution must include the [ClickHouse exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/clickhouseexporter) and [routing connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/routingconnector). The OpenTelemetry Collector Contrib distribution includes both components.
>
> The example adds OTLP receivers, batching and memory limiting, Session Replay routing, and ClickHouse exporters.
>
> Replace the endpoint and password placeholders with the credentials generated by ClickStack:
>
> ```yaml theme={null}
> receivers:
>   otlp/hyperdx:
>     protocols:
>       grpc:
>         include_metadata: true
>         endpoint: "0.0.0.0:4317"
>       http:
>         cors:
>           allowed_origins: ["*"]
>           allowed_headers: ["*"]
>         include_metadata: true
>         endpoint: "0.0.0.0:4318"
> processors:
>   batch:
>   memory_limiter:
>     # 80% of maximum memory up to 2G, adjust for low memory environments
>     limit_mib: 1500
>     # 25% of limit up to 2G, adjust for low memory environments
>     spike_limit_mib: 512
>     check_interval: 5s
> connectors:
>   routing/logs:
>     default_pipelines: [logs/out-default]
>     error_mode: ignore
>     table:
>       - context: log
>         statement: route() where IsMatch(attributes["rr-web.event"], ".*")
>         pipelines: [logs/out-rrweb]
> exporters:
>   clickhouse/rrweb:
>     database: default
>     endpoint: <clickhouse_cloud_endpoint>
>     password: <your_password_here>
>     username: default
>     ttl: 720h
>     logs_table_name: hyperdx_sessions
>     timeout: 5s
>     retry_on_failure:
>       enabled: true
>       initial_interval: 5s
>       max_interval: 30s
>       max_elapsed_time: 300s
>   clickhouse:
>     database: default
>     endpoint: <clickhouse_cloud_endpoint>
>     password: <your_password_here>
>     username: default
>     ttl: 720h
>     timeout: 5s
>     retry_on_failure:
>       enabled: true
>       initial_interval: 5s
>       max_interval: 30s
>       max_elapsed_time: 300s
>
> service:
>   pipelines:
>     traces:
>       receivers: [otlp/hyperdx]
>       processors: [memory_limiter, batch]
>       exporters: [clickhouse]
>     metrics:
>       receivers: [otlp/hyperdx]
>       processors: [memory_limiter, batch]
>       exporters: [clickhouse]
>     logs/in:
>       receivers: [otlp/hyperdx]
>       exporters: [routing/logs]
>     logs/out-default:
>       receivers: [routing/logs]
>       processors: [memory_limiter, batch]
>       exporters: [clickhouse]
>     logs/out-rrweb:
>       receivers: [routing/logs]
>       processors: [memory_limiter, batch]
>       exporters: [clickhouse/rrweb]
>
> ```
>
> Reuse your existing OTLP receiver and preserve its authentication and TLS settings. If your configuration already uses the component or pipeline IDs in the example, merge or rename them instead of creating duplicate IDs. Running two receivers on ports `4317` and `4318` causes a port conflict.
>
> After merging the configuration, reload or restart the collector using your existing deployment process.
>
> For further details on configuring OpenTelemetry collectors, see [Ingesting with OpenTelemetry](https://clickhouse.com/docs/clickstack/observability/ingesting-data/opentelemetry.md).

### 2. Send test data

Send a test log with the current timestamp:

```shell theme={null}
NOW_NANO="$(date +%s)000000000"

curl -i "http://localhost:4318/v1/logs" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "resourceLogs": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {"stringValue": "clickstack-docs-test"}
      }]
    },
    "scopeLogs": [{
      "scope": {"name": "clickstack-docs-test"},
      "logRecords": [{
        "timeUnixNano": "${NOW_NANO}",
        "severityText": "INFO",
        "body": {"stringValue": "ClickStack ingestion test"}
      }]
    }]
  }]
}
EOF
```

If you use an existing collector, replace `http://localhost:4318` with its OTLP HTTP endpoint. If the receiver requires authentication, add the required header to the `curl` command.

A successful request returns `HTTP/1.1 200 OK`.

### 3. Start exploring and confirm ingestion

After the UI detects the OpenTelemetry data sources, select **Start exploring** to open the **Search** view. Search for `ClickStack ingestion test`.

The result should include the test event with the `clickstack-docs-test` service name.

![Logs view showing the ClickStack ingestion test event](https://mintcdn.com/private-7c7dfe99/jC7TL_OYAmc51b5p/images/clickstack/getting-started/clickstack_ingestion_test.webp?fit=max\&auto=format\&n=jC7TL_OYAmc51b5p\&q=85\&s=86fd06cbc3ea0128ca072f671879c469)

**Vector**

### Prepare your ingestion environment

Start with an [existing Vector pipeline](https://clickhouse.com/docs/clickstack/observability/ingesting-data/vector.md) that can send data to ClickHouse.

## Set up Self-managed ClickHouse Observability

### 1. Choose Vector and configure ingestion

From your ClickHouse Cloud service, open ClickHouse Observability. On the **Getting Started** page, select **Start ingestion**.

![Start ingestion](https://mintcdn.com/private-7c7dfe99/E1Oh1nXf1f-XPStr/images/clickstack/getting-started/start_ingestion.webp?fit=max\&auto=format\&n=E1Oh1nXf1f-XPStr\&q=85\&s=85347702d968ca5646fc176d067f9e5a)

On the **Choose an ingestion source** page, select [Vector](https://vector.dev/).

![Select Vector as the ingestion source](https://mintcdn.com/private-7c7dfe99/E1Oh1nXf1f-XPStr/images/clickstack/getting-started/select_source_vector_toggle.webp?fit=max\&auto=format\&n=E1Oh1nXf1f-XPStr\&q=85\&s=ac5e9d904ba085db20bfe1a25541dd13)

[Vector](https://vector.dev) is a high-performance, vendor-neutral observability data pipeline, especially popular for log ingestion due to its flexibility and low resource footprint.

When using Vector, you define the schema. It can follow OpenTelemetry conventions or use fields specific to your events.

> [!NOTE]
>
> **Existing Vector pipeline required**
>
> Continue with this guide if you already run Vector with an input pipeline. The data sent through the pipeline must include a **timestamp column** or equivalent time field, which you select when configuring the data source in the observability UI.
>
> The steps below add a ClickHouse sink to your existing pipeline.

#### Create a database and table

Create a database and table before configuring the Vector sink.

In ClickHouse Cloud, open your service's SQL console and create a database:

For example, create a database for logs:

```sql theme={null}
CREATE DATABASE IF NOT EXISTS logs
```

Then create a table whose schema matches the structure of your log data. The example below assumes a classic Nginx access log format:

```sql theme={null}
CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr);
```

Your table must align with the output schema produced by Vector. Adjust the schema as needed for your data, following the recommended [schema best practices](https://clickhouse.com/docs/concepts/best-practices/select-data-type.md).

We strongly recommend understanding how [Primary keys](https://clickhouse.com/docs/concepts/core-concepts/primary-indexes.md) work in ClickHouse and choosing an ordering key based on your access patterns. See the [performance-tuning](https://clickhouse.com/docs/clickstack/self-configured/managing/performance-tuning.md#choosing-a-primary-key) guidance on choosing a primary key.

#### Configure the ClickHouse sink

Once the table exists, add a ClickHouse sink to your Vector configuration:

```yaml theme={null}
sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "https://<host>:8443"
    database: logs
    table: nginx_logs
    format: json_each_row
    skip_unknown_fields: true
    auth:
      strategy: basic
      user: default
      password: "<your_password_here>"
```

Replace `your_input` with the input from your existing pipeline. Replace `<host>` and `<your_password_here>` with the values for your ClickHouse Cloud service. If required, change the target database or table.

> [accordion] Use dedicated ingestion credentials (recommended)
>
> For production, create a dedicated user and grant it access to the Vector target table. In ClickHouse Cloud, open your service's SQL console and run:
>
> ```sql theme={null}
> CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
> GRANT SELECT, INSERT ON logs.nginx_logs TO `clickstack-ingest`;
> ```
>
> Replace `default` with `clickstack-ingest` in the Vector sink and set `password` to the dedicated user's password.

Save the updated configuration, then reload or restart Vector using your existing deployment process.

For more examples of ingesting data with Vector, see [Ingesting with Vector](https://clickhouse.com/docs/clickstack/observability/ingesting-data/vector.md) or the [Vector ClickHouse sink documentation](https://vector.dev/docs/reference/configuration/sinks/clickhouse/) for advanced options.

#### Create a data source

Create a data source for the table populated by your Vector pipeline. The UI prompts you to create one on your first login.

The form pre-populates expressions for the default OpenTelemetry schema. For the Nginx table created in this guide, configure the source with these values:

| Setting | Value |
| - | - |
| **Name** | `Nginx logs` |
| **Source Data Type** | Log |
| **Server Connection** | `Default` |
| **Database** | `logs` |
| **Table** | `nginx_logs` |
| **Timestamp Column** | `time_local` |
| **Default SELECT** | `time_local, remote_addr, status, request` |
| **Service Name Expression** | `'nginx'` |
| **Log Level Expression** | `multiIf(status >= 500, 'ERROR', status >= 400, 'WARN', 'INFO')` |
| **Log Attributes Expression** | `map('http.remote_addr', toString(remote_addr), 'http.status_code', toString(status), 'http.request', request)` |
| **Resource Attributes Expression** | `map('service.name', 'nginx')` |
| **Displayed Timestamp Column** | `time_local` |
| **Trace ID Expression** | `''` |
| **Span ID Expression** | `''` |
| **Implicit Column Expression** | `request` |

The Nginx table doesn't contain a `Body` column. Set **Body Expression** to:

```sql theme={null}
concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%i:%S %z'), '] ',
  '"', request, '" ',
  toString(status), ' ',
  toString(body_bytes_sent), ' ',
  '"', http_referer, '" ',
  '"', http_user_agent, '" ',
  '"', http_x_forwarded_for, '" ',
  toString(request_time), ' ',
  toString(upstream_response_time), ' ',
  '"', http_host, '"'
)
```

For other source settings, see the [configuration reference](https://clickhouse.com/docs/clickstack/self-configured/managing/config.md).

### 2. Send test data

Send a representative event through the input of your existing Vector pipeline.

For more Vector source and transformation examples, see [Ingesting with Vector](https://clickhouse.com/docs/clickstack/observability/ingesting-data/vector.md).

### 3. Start exploring and confirm ingestion

After creating the data source, select **Start exploring** to open the **Search** view. Select the data source for your table and confirm that it contains the event you sent.

![Logs in the observability UI](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/getting-started/clickstack_managed_ui.webp?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=ad38540d5c1caccbfab8fda4cc74e981)

You now have a Self-managed ClickHouse Observability service, a working ingestion path, and a test event that you can inspect in the observability UI.

## Next steps

If another guide requires your ClickHouse Cloud endpoint or password, [gather or reset your connection details](https://clickhouse.com/docs/products/cloud/guides/sql-console/connection-details.md) before continuing.

### Send application and infrastructure data

Choose a guide for the data that you want to send to your service:

> [card] [Instrument an application](https://clickhouse.com/docs/clickstack/observability/ingesting-data/sdks/index.md)
>
> Send application traces and logs with a supported OpenTelemetry SDK.

> [card] [Collect host logs](https://clickhouse.com/docs/clickstack/observability/integration-examples/host-logs.md)
>
> Forward host logs from an OpenTelemetry Collector running in the agent role.

> [card] [Monitor Kubernetes](https://clickhouse.com/docs/clickstack/observability/integration-examples/kubernetes.md)
>
> Collect logs, metrics, and traces from a Kubernetes cluster.

> [card] [Explore other integrations](https://clickhouse.com/docs/clickstack/observability/integration-examples/index.md)
>
> Find guides for additional applications and telemetry sources.

### Explore sample data

Use a sample dataset to explore the UI with richer telemetry:

> [card] [Sample logs, traces, and metrics](https://clickhouse.com/docs/clickstack/observability/example-datasets/sample-data.md)
>
> ![](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/example-trace-dashboard.webp?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=17574be8fe26283dc6c4f964227f1143)
>
> Load data from the public demo and diagnose an issue. This guide assumes that you started a new local OpenTelemetry Collector. If you configured an existing collector, adapt the endpoint and authentication settings to your deployment.

> [card] [Local logs and metrics](https://clickhouse.com/docs/clickstack/observability/example-datasets/local-data.md)
>
> ![](https://mintcdn.com/private-7c7dfe99/y4_YksnkJMz9sseb/images/clickstack/host-logs/host-logs-dashboard.webp?fit=max\&auto=format\&n=y4_YksnkJMz9sseb\&q=85\&s=453e8043bcd28219befc351def4d6cbd)
>
> Collect local files and system metrics on macOS or Linux.

### Generate synthetic data

Use a generator to test ingestion without an existing application or dataset:

> [card] [Generate data with otelgen](https://clickhouse.com/docs/clickstack/observability/example-datasets/otelgen.md)
>
> Send a short burst of synthetic OTLP logs, traces, and metrics.

> [card] [Generate data with telemetrygen](https://clickhouse.com/docs/clickstack/observability/example-datasets/telemetrygen.md)
>
> Generate configurable OpenTelemetry signals across several services.

See [all sample data and demos](https://clickhouse.com/docs/clickstack/observability/example-datasets/index).

### Prepare for production

Review production and sizing guidance before using your service for sustained workloads:

> [card] [Going to production](https://clickhouse.com/docs/clickstack/self-configured/managing/production.md)
>
> Review ingestion credentials, security, retention, and operational guidance.

> [card] [Estimate resources](https://clickhouse.com/docs/clickstack/self-configured/managing/estimating-resources.md)
>
> Size compute for your expected ingest volume.

For deployment tasks, see the [Self-managed ClickHouse Observability deployment guide](https://clickhouse.com/docs/clickstack/self-configured/deployment/managed.md#additional-tasks).