Getting started with Managed ClickStack

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, install Docker. For Kubernetes, deploy the collector with Helm.
To use an existing collector, run it in the gateway role and ensure that its distribution includes the ClickHouse exporter. You will add the required configuration in this guide.

Set up Managed ClickStack

Choose an ingestion source and collector setup

From your ClickHouse Cloud service, launch ClickStack. On the ClickStack Getting Started page, select Start ingestion.On the Choose an ingestion source page, select OpenTelemetry.

OpenTelemetry recommendedOpenTelemetry provides preconfigured schemas for logs, traces, metrics, and sessions.

Start a new collector
Use an existing collector

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

Create dedicated ingestion credentials (recommended)

In ClickHouse Cloud, open your service’s SQL console and run:

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. ClickStack 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.The command follows this format:

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.

This command exposes the OTLP ports without authentication and is intended for local evaluation. Before sending production traffic, secure the 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 ClickStack. 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.

Collector components requiredYour collector distribution must include the ClickHouse exporter and routing connector. 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:

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.

Send test data

Send a test log with the current timestamp:

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.

Start exploring and confirm ingestion

After ClickStack 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.

Next steps

Send application and infrastructure data

Instrument an application

Send application traces and logs with a supported OpenTelemetry SDK.

Collect host logs

Forward host logs from an OpenTelemetry Collector running in the agent role.

Monitor Kubernetes

Collect logs, metrics, and traces from a Kubernetes cluster.

Explore other integrations

Find guides for additional applications and telemetry sources.

Explore sample data

Sample logs, traces, and metrics

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.

Local logs and metrics

Collect local files and system metrics on macOS or Linux.

Generate synthetic data

Generate data with otelgen

Send a short burst of synthetic OTLP logs, traces, and metrics.

Generate data with telemetrygen

Generate configurable OpenTelemetry signals across several services.

Prepare for production

Going to production

Review ingestion credentials, security, retention, and operational guidance.

Estimate resources

Size compute for your expected ingest volume.

Get started

Features

Managing ClickStack

Guides

Integration partners

Before you begin

Create a ClickHouse Cloud service

Prepare your ingestion environment

Set up Managed ClickStack

Choose an ingestion source and collector setup

Send test data

Start exploring and confirm ingestion

Next steps

Send application and infrastructure data

Instrument an application

Collect host logs

Monitor Kubernetes

Explore other integrations

Explore sample data

Sample logs, traces, and metrics

Local logs and metrics

Generate synthetic data

Generate data with otelgen

Generate data with telemetrygen

Prepare for production

Going to production

Estimate resources

​Before you begin

​Create a ClickHouse Cloud service

​Prepare your ingestion environment

​Set up Managed ClickStack

Choose an ingestion source and collector setup

Send test data

Start exploring and confirm ingestion

​Next steps

​Send application and infrastructure data

Instrument an application

Collect host logs

Monitor Kubernetes

Explore other integrations

​Explore sample data

Sample logs, traces, and metrics

Local logs and metrics

​Generate synthetic data

Generate data with otelgen

Generate data with telemetrygen

​Prepare for production

Going to production

Estimate resources

Before you begin

Create a ClickHouse Cloud service

Prepare your ingestion environment

Set up Managed ClickStack

Next steps

Send application and infrastructure data

Explore sample data

Generate synthetic data

Prepare for production