托管 ClickStack 入门

本页面显示的是 OpenTelemetry 路径。使用本指南顶部附近的选择器，可在 OpenTelemetry (推荐) 和 Vector 之间切换。

准备摄取环境

若要启动新的 OpenTelemetry Collector，请安装 Docker。对于 Kubernetes，请使用 Helm 部署 collector。
若要使用现有 collector，请以 gateway 角色运行它，并确保其发行版包含 ClickHouse exporter。您将在本指南中添加所需配置。

配置托管 ClickStack

选择摄取源和 collector 配置

从您的 ClickHouse Cloud 服务中启动 ClickStack。在 ClickStack 的入门页面上，选择开始摄取。在选择摄取源页面上，选择 OpenTelemetry。

推荐使用 OpenTelemetryOpenTelemetry 为日志、追踪、指标和会话提供预配置的架构。

启动新的收集器
使用现有收集器

ClickStack 会使用 default 管理员凭据生成收集器命令。建议使用专用摄取凭据，以便将摄取访问与管理操作分开，并避免依赖管理员密码。

创建专用摄取凭据（推荐）

在 ClickHouse Cloud 中，打开服务的 SQL 控制台并运行：

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

在生成的命令中，将 CLICKHOUSE_USER="default" 替换为 CLICKHOUSE_USER="clickstack-ingest"，并将 CLICKHOUSE_PASSWORD 设置为专用用户的密码。

若要继续使用 default 管理员凭据，请从启动收集器选项卡复制命令。ClickStack 会预先填入服务端点。将密码占位符替换为服务密码。如果您不再拥有该密码，请获取或重置连接信息。该命令格式如下：

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

将 <host> 和 <your_password_here> 替换为 ClickHouse Cloud 服务的相应值，然后运行该命令。收集器将在前台运行。请保持此终端处于打开状态，并使用第二个终端运行本指南中的其余命令。

此命令会在未经身份验证的情况下暴露 OTLP 端口，仅适用于本地评估。在发送生产流量前，请保护收集器。

选择配置现有收集器，然后调整收集器配置。将收集器作为应用程序与 ClickHouse Cloud 之间的网关运行。以下配置会添加所需的 ClickHouse exporter 和信号管道。该示例使用 ClickStack 生成的 default 凭据。若要使用专用摄取凭据，请按照启动新的收集器选项卡中的可选设置操作。在两个 ClickHouse exporter 块中，将 username: default 替换为 username: clickstack-ingest，并将 password 设置为专用用户的密码。请将以下组件合并到现有配置中，而不要替换无关的 receiver、processor、exporter 或 extension。

必需的收集器组件收集器发行版必须包含 ClickHouse exporter 和 routing connector。OpenTelemetry Collector Contrib 发行版包含这两个组件。

该示例添加了 OTLP receiver、批处理和内存限制、Session Replay 路由以及 ClickHouse exporter。将端点和密码占位符替换为 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]

复用现有的 OTLP receiver，并保留其身份验证和 TLS 设置。如果配置已使用示例中的组件或管道 ID，请合并或重命名它们，而不要创建重复的 ID。在端口 4317 和 4318 上运行两个 receiver 会导致端口冲突。合并配置后，请使用现有部署流程重新加载或重启收集器。有关配置 OpenTelemetry 收集器的更多信息，请参阅使用 OpenTelemetry 摄取。

发送测试数据

使用当前时间戳发送一条测试日志：

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

如果使用现有的 collector，请将 http://localhost:4318 替换为其 OTLP HTTP 端点。如果 receiver 需要身份验证，请在 curl 命令中添加所需的请求头。请求成功时将返回 HTTP/1.1 200 OK。

开始探索并确认数据已摄取

当 ClickStack 检测到 OpenTelemetry 数据源后，选择 开始探索，打开搜索视图。搜索 ClickStack ingestion test。结果中应显示服务名称为 clickstack-docs-test 的测试事件。

为应用程序添加埋点

使用受支持的 OpenTelemetry SDK 发送应用程序的链路追踪和日志。

收集主机日志

转发由以 agent 角色运行的 OpenTelemetry Collector 收集的主机日志。

监控 Kubernetes

从 Kubernetes 集群收集日志、指标和链路追踪。

探索其他集成

查找其他应用程序和遥测数据源的指南。

样本日志、链路追踪和指标

从公网演示环境加载数据并诊断问题。本指南假定您已启动一个新的本地 OpenTelemetry Collector。若您配置的是现有 collector，请根据您的部署调整端点和身份验证设置。

本地日志和指标

在 macOS 或 Linux 上收集本地文件和系统指标。

使用 otelgen 生成数据

发送一小批合成 OTLP 日志、链路追踪和指标。

使用 telemetrygen 生成数据

为多个服务生成可配置的 OpenTelemetry 信号。

投入生产环境

查阅有关摄取凭据、安全、数据保留和运维的指南。

估算资源

根据预期摄取量评估所需的计算资源。

开始使用

功能特性

管理 ClickStack

指南

集成合作伙伴

开始之前

创建 ClickHouse Cloud 服务

准备摄取环境

配置托管 ClickStack

选择摄取源和 collector 配置

发送测试数据

开始探索并确认数据已摄取

后续步骤

发送应用程序和基础设施数据

为应用程序添加埋点

收集主机日志

监控 Kubernetes

探索其他集成

探索样本数据

样本日志、链路追踪和指标

本地日志和指标

生成合成数据

使用 otelgen 生成数据

使用 telemetrygen 生成数据

为生产环境做好准备

投入生产环境

估算资源

​开始之前

​创建 ClickHouse Cloud 服务

​准备摄取环境

​配置托管 ClickStack

选择摄取源和 collector 配置

发送测试数据

开始探索并确认数据已摄取

​后续步骤

​发送应用程序和基础设施数据

为应用程序添加埋点

收集主机日志

监控 Kubernetes

探索其他集成

​探索样本数据

样本日志、链路追踪和指标

本地日志和指标

​生成合成数据

使用 otelgen 生成数据

使用 telemetrygen 生成数据

​为生产环境做好准备

投入生产环境

估算资源

开始之前

创建 ClickHouse Cloud 服务

准备摄取环境

配置托管 ClickStack

后续步骤

发送应用程序和基础设施数据

探索样本数据

生成合成数据

为生产环境做好准备