Начало работы с Управляемым ClickStack

В сервисе ClickHouse Cloud запустите ClickStack. На странице ClickStack Начало работы выберите Начать ингестию.

На странице Выберите источник ингестии выберите OpenTelemetry.

CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, CREATE VIEW ON default.* TO `clickstack-ingest`;

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

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]

Отправьте тестовую запись журнала с текущей временной меткой:

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

Если вы используете существующий коллектор, замените http://localhost:4318 на его конечную точку OTLP HTTP. Если приёмник требует аутентификации, добавьте необходимый заголовок в команду curl.

При успешном запросе возвращается HTTP/1.1 200 OK.

После того как ClickStack обнаружит источники данных OpenTelemetry, выберите Начать изучение, чтобы открыть представление Search. Найдите ClickStack ingestion test.

В результатах должно отображаться тестовое событие с именем сервиса clickstack-docs-test.

В своём сервисе ClickHouse Cloud запустите ClickStack. На странице ClickStack Getting Started выберите Start ingestion.

На странице Choose an ingestion source выберите Vector.

Vector — это высокопроизводительный, независимый от вендоров конвейер данных обсервабилити, особенно популярный для приёма логов благодаря своей гибкости и низкому потреблению ресурсов.

При использовании Vector вместе с ClickStack схему определяете вы. Она может соответствовать соглашениям OpenTelemetry либо содержать поля, специфичные для ваших событий.

Создайте базу данных и таблицу

Создайте базу данных и таблицу перед настройкой sink в Vector.

В ClickHouse Cloud откройте SQL Console вашего сервиса и создайте базу данных:

Например, создайте базу данных для журналов:

CREATE DATABASE IF NOT EXISTS logs

Затем создайте таблицу, схема которой соответствует структуре ваших логов. В приведённом ниже примере используется классический формат логов доступа Nginx:

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);

Ваша таблица должна соответствовать выходной схеме, которую формирует Vector. При необходимости скорректируйте схему под свои данные, руководствуясь рекомендуемыми лучшими практиками работы со схемами.

Мы настоятельно рекомендуем разобраться, как в ClickHouse работают первичные ключи, и выбирать ключ сортировки с учётом характерных для вас шаблонов доступа к данным. См. рекомендации для ClickStack по выбору первичного ключа.

Настройте sink для ClickHouse

После создания таблицы добавьте sink ClickHouse в конфигурацию Vector:

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>"

Замените your_input на входные данные из вашего существующего конвейера. Замените <host> и <your_password_here> на значения вашего сервиса ClickHouse Cloud. При необходимости измените целевую базу данных или таблицу.

CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT ON logs.nginx_logs TO `clickstack-ingest`;

Сохраните обновлённую конфигурацию, затем перезагрузите или перезапустите Vector с использованием вашего текущего процесса развертывания.

Дополнительные примеры ингестии данных с помощью Vector приведены в разделе Ингестия с помощью Vector, а расширенные параметры описаны в документации по sink ClickHouse для Vector.

Создайте источник данных ClickStack

Создайте источник данных для таблицы, которую наполняет ваш конвейер Vector. ClickStack предложит создать его при первом входе в систему.

Форма предзаполняется выражениями для стандартной схемы OpenTelemetry. Для таблицы Nginx, созданной в этом руководстве, задайте для источника следующие значения:

Таблица Nginx не содержит столбца Body. В поле Body Expression укажите:

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, '"'
)

Остальные настройки source описаны в справочнике по конфигурации ClickStack.

Отправьте тестовое событие на вход существующего конвейера Vector.

Дополнительные примеры источников и преобразований Vector см. в разделе Приём данных с помощью Vector.

После создания источника данных выберите Start exploring, чтобы открыть представление Search. Выберите источник данных для своей таблицы и убедитесь, что в нём есть отправленное вами событие.