Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Getting started with Managed ClickStack

View as MarkdownEdit this pageReport an issueSet up docs MCP

Deploy Managed ClickStack on ClickHouse Cloud, send a test event through your ingestion pipeline, and confirm that the event is available in the ClickStack UI.

ClickHouse Cloud operates the ClickHouse backend while you retain control over the ingestion pipeline and schema. Managed ClickStack 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
  • 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 and your own schema.

Create a ClickHouse Cloud service

Complete Create a ClickHouse service in the ClickHouse Cloud quickstart. Before continuing, confirm that the service is running.

Prepare your ingestion environment

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.

Start ingestion

On the Choose an ingestion source page, select OpenTelemetry.

Select OpenTelemetry as the ingestion source

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.

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.

ClickStack logs view showing the ClickStack ingestion test event

Prepare your ingestion environment

Start with an existing Vector pipeline that can send data to ClickHouse.

Set up Managed ClickStack

Choose Vector and configure ingestion

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

Start ingestion

On the Choose an ingestion source page, select Vector.

Select Vector as the ingestion source

Vector 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 with ClickStack, you define the schema. It can follow OpenTelemetry conventions or use fields specific to your events.

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:

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:

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.

We strongly recommend understanding how Primary keys work in ClickHouse and choosing an ordering key based on your access patterns. See the ClickStack-specific guidance on choosing a primary key.

Configure the ClickHouse sink

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

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.

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:

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 or the Vector ClickHouse sink documentation for advanced options.

Create a ClickStack data source

Create a data source for the table populated by your Vector pipeline. ClickStack 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:

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

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.

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

You now have a Managed ClickStack service, a working ingestion path, and a test event that you can inspect in ClickStack.

Next steps

If another guide requires your ClickHouse Cloud endpoint or password, gather or reset your connection details before continuing.

Send application and infrastructure data

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

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

Use a sample dataset to explore ClickStack with richer telemetry:

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

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

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.

See all ClickStack sample data and demos.

Prepare for production

Review production and sizing guidance before using ClickStack for sustained workloads:

Going to production

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

Estimate resources

Size compute for your expected ingest volume.

For deployment tasks, see the Managed ClickStack deployment guide.

Navigation