在 ClickHouse Cloud 的 Managed…

当需要把 OpenTelemetry Collector 接入 ClickHouse Cloud 的 Managed ClickStack 服务、发送合成遥测并确认数据可见时使用。

适用场景

解决思路

1. Step 0：先问用户两个问题确定路径——是否已有 gateway 角色的 collector（无则新建，有则配置现有）；新建路径再问用 Docker Compose（推荐）还是单独 docker 命令。记录 COLLECTOR_PATH（new/existing）与 DEPLOY_MODE（compose/run）。
2. Step 1：提前批量申请权限，让用户对 openssl rand、clickhousectl cloud、jq、docker/docker compose、curl 这些命令前缀选择“always allow”；并提醒 clickhousectl 安装（curl … | sh）和 CREATE USER/GRANT 这两类语义审批无法被前缀规则预清，需显式批准。
3. Step 2：创建 700 权限工作目录与 0600 的 collector.env，用 umask 177 写入 SERVICE_REF、OTLP_AUTH_TOKEN=$(openssl rand -hex 32)、CLICKHOUSE_USER=hyperdx_ingest、CLICKHOUSE_PASSWORD=$(openssl rand -hex 24)Aa1-、HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=otel；键名必须精确（密码必须叫 CLICKHOUSE_PASSWORD），密码需含大写与 URL 非保留特殊字符（避免 @ : / ? # %），env 文件用不带引号的 KEY=VALUE。
4. Step 2 续：每个后续步骤的 shell 都以标准 preamble 开头：WORKDIR="${WORKDIR:-$HOME/clickstack-otel-collector}"; ENV_FILE="$WORKDIR/collector.env"; [ -f "$WORKDIR/creds.env" ] && . "$WORKDIR/creds.env"; set -a; . "$ENV_FILE"; set +a。
5. Step 3：用 which clickhousectl 单独检查是否存在，缺失才执行 curl -fsSL https://clickhouse.com/cli | sh 安装；运行 clickhousectl cloud auth status，必须使用 API key 认证（OAuth 只读）；不要让用户把 API key 粘贴到聊天里，而是让其在单独终端执行 clickhousectl cloud auth login --api-key <key-id> --api-secret <key-secret>（Admin 角色）。
6. Step 3 续：轮询直到 API key 显示 Active，并用 clickhousectl cloud service list --json | jq -r '.[].name' 做与 ref 无关的真实调用验证；若新 shell 报 No credentials found，则从 $HOME/.clickhouse/credentials.json 用 jq 生成 0600 的 $WORKDIR/creds.env（export CLICKHOUSE_CLOUD_API_KEY / CLICKHOUSE_CLOUD_API_SECRET），之后每个 shell 都加载它。
7. Step 4：运行标准 preamble 后解析服务——UUID 用 clickhousectl cloud service get "$SERVICE_REF" --json > "$WORKDIR/svc.json"，名称用 clickhousectl cloud service list --json | jq --arg n "$SERVICE_REF" '.[] | select(.name==$n)' > "$WORKDIR/svc.json"；提取 SERVICE_ID、SERVICE_NAME、STATE，并用 jq 把端口 tonumber|floor 得到 CLICKHOUSE_ENDPOINT（https://host:8443，避免 8443.0）；用 grep -q 判断后把 SERVICE_ID 与 CLICKHOUSE_ENDPOINT 追加进 env 文件。
8. Step 4 续：STATE 必须为 running，否则让用户启动或等待；执行 clickhousectl cloud service query --id "$SERVICE_ID" --query "SELECT version()" 确认服务已唤醒且 Query API key 已就绪（首次会打印 Provisioning Query API endpoint + key）。
9. Step 5：本地计算密码哈希 PW_HASH=$(printf %s "$CLICKHOUSE_PASSWORD" | openssl dgst -sha256 | awk '{print $NF}')，绝不把明文密码放进 SQL；逐条执行（Query API 不允许 multi-statement）：CREATE USER IF NOT EXISTS hyperdx_ingest IDENTIFIED WITH sha256_hash BY '$PW_HASH'，再 ALTER USER hyperdx_ingest IDENTIFIED WITH sha256_hash BY '$PW_HASH'。
10. Step 5 续：执行 GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, CREATE VIEW ON otel.* TO hyperdx_ingest；若旧镜像日志出现引用 default 的 ACCESS_DENIED，则补 GRANT SELECT, INSERT, CREATE TABLE ON default.* TO hyperdx_ingest 并重启容器；用 SHOW GRANTS FOR hyperdx_ingest 验证。
11. Step 6a（compose）：先 docker info 确认 Docker 运行；写入 $WORKDIR/docker-compose.yaml（image clickhouse/clickstack-otel-collector:latest，env_file ./collector.env，端口 4317/4318/13133，restart unless-stopped，网络 clickstack-net）；若已存在无容器的孤儿 clickstack-net 则 docker network rm 后 ( cd "$WORKDIR" && docker compose up -d )。
12. Step 6b（run）：docker network create clickstack-net 2>/dev/null || true；docker rm -f clickstack-otel-collector 后 docker run -d --name clickstack-otel-collector --network clickstack-net --env-file "$ENV_FILE" -p 4317:4317 -p 4318:4318 -p 13133:13133 clickhouse/clickstack-otel-collector:latest（绝不用 -e 传密钥）。
13. Step 6c（existing）：在现有 collector 配置中加入 ClickHouse exporter（database otel、endpoint ${env:CLICKHOUSE_ENDPOINT}、username hyperdx_ingest、password ${env:CLICKHOUSE_PASSWORD}、ttl 720h、retry_on_failure），并加入 otlp/hyperdx receiver、batch 与 memory_limiter 处理器、routing/logs connector 及 clickhouse/rrweb exporter（logs_table_name hyperdx_sessions），配置 traces/metrics/logs-in/logs-out-default/logs-out-rrweb 五条 pipeline；用 --env-file 或 systemd EnvironmentFile 提供环境变量后 reload。
14. Step 6d：用 docker ps --filter name=clickstack-otel-collector --format '{{.Status}}'、curl -fsS http://localhost:13133/、docker logs --tail 40 clickstack-otel-collector 确认健康；健康启动应看到 [seed] OK 与 goose: up to current file version、Everything is ready，并按错误信息定位（516 密码问题、403 空密码、TLS/dial 端点格式、default ACCESS_DENIED 旧镜像）。
15. Step 7：用 telemetrygen 的 Docker 镜像（ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest）发送遥测；定义 tg() 辅助函数把输出重定向到 $WORKDIR/telemetrygen.log（因为输出会回显含 token 的 authorization 头），只打印 "<signal> exit=$?"；header 语法为 authorization="$OTLP_AUTH_TOKEN"。
16. Step 7 续：发送多样遥测——logs 覆盖 checkout(Info,9) 与 payment(Error,17) 两个服务及不同 body；traces 覆盖 checkout(--child-spans 4 --status-code Ok) 与 payment(--child-spans 3 --status-code Error)；metrics 覆盖 Sum、Gauge、Histogram 三种类型；属性参数整体用单引号包裹以保留内层双引号（如 --otlp-attributes 'deployment.environment="production"'）。
17. Step 7 续：以退出码和行数判断成功，绝不打印生成器日志（含 token，且结束时必有 rpc error: code = Canceled 属正常关闭）；等待约 15 秒后用 clickhousectl cloud service query 查询 system.tables 确认 otel 库表存在，再用 system.parts 按 table 统计 sum(rows) 确认 otel_logs、otel_traces、otel_metrics_sum、otel_metrics_gauge、otel_metrics_histogram 均非零；缺失时查 collector 日志、grep -c Unauthenticated "$TG_LOG"、复查 endpoint 的 https 与 :8443、再等 30 秒重查。
18. Step 8：先执行 clickhousectl cloud service query --id "$SERVICE_ID" --query "SELECT 1" 确认服务已唤醒（失败则等待重试直到返回 1）；然后逐步引导用户在 Cloud 控制台左侧菜单选 ClickStack → Getting Started 完成 onboarding，跳过任何要求配置 collector/启动 ingestion 的提示，数据源会自动检测；若检测不到，重跑 SELECT 1 唤醒后重试。
19. Step 9：输出摘要（引用而非打印 token，不显示 SQL 密码），说明 collector 仍在运行、如何停止（Compose 用 docker compose down/up -d，单独 Docker 用 docker stop/start clickstack-otel-collector）、应用可向 localhost:4317/4318 发送 OTLP 并带 authorization 头、以及服务会 idle-suspend 需唤醒。
20. Cleanup（仅用户明确要求时）：Compose 用 ( cd "$WORKDIR" && docker compose down )；单独 Docker 用 docker rm -f clickstack-otel-collector 与 docker network rm clickstack-net；执行 DROP USER IF EXISTS hyperdx_ingest；可选删除 collector.env、svc.json、docker-compose.yaml；不要删除 otel 数据库。

适用边界 · 注意事项

• 需要完整 Kubernetes 部署（Helm、K8s Secrets）的场景不在本技能范围内。
• 没有 ClickHouse Cloud 账号、Admin API key 或 Managed ClickStack 服务时无法执行。
• 用户不愿安装 clickhousectl 或无法运行 Docker 时，新建本地 collector 的路径不可用。