云数据库 ClickHouse 企业版ClickStack服务，是基于ClickHouse与OpenTelemetry构建的高性能可观测解决方案。它无缝融合了日志（Logs）、调用链（Traces）和指标（Metrics），提供统一的可观测体验，开发者和运维人员无需在不同工具间切换，即可全程跟踪并解决问题。同时，ClickStack内置智能可观测数据分析AI助手，能够自动查询OTel可观测数据（Traces/Logs/Metrics），通过SQL查询和结构化RCA流程，自动完成可观测性故障排查与根因定位。本文为您介绍ClickStack的相关使用方法。
前提条件
云数据库 ClickHouse 企业版支持直接一键开通ClickStack能力。
云数据库 ClickHouse 社区兼容版ClickStack能力目前处于邀测阶段，如需开启请提交工单联系技术支持加白处理。
开启服务
登录云数据库ClickHouse控制台，在页面左上角，选择集群所在的地域。
在集群列表页面，选择对应版本的实例列表，单击目标集群ID。
在左侧导航栏单击ClickStack。
在对话框中，建议勾选自动创建表和导入示例数据，并按需决定是否支持公网访问大模型，然后单击确定。开启服务预计需要5～10分钟。
重要勾选支持公网访问大模型会产生额外费用，需要按需开启。
支持在服务开通完成后再单独开启公网访问大模型。
参数
说明
自动创建表
创建数据库
clickobserve_service，并在此库下创建表otel_logs,otel_traces,otel_metrics_gauge,otel_metrics_histogram,otel_metrics_sum,otel_metrics_summary,otel_traces_trace_id_ts,otel_traces_trace_id_ts_mv,otel_metrics_exponential_histogram。
导入示例数据
会向logs、traces、metrics表导入符合OpenTelemetry协议的样例数据，压缩前不到200MB。
支持公网访问大模型
大模型服务只能通过公网出口访问，因此为了使用可观测数据智能AI助手，需要为ClickStack服务节点开启公网访问能力。勾选该选项后，系统将在当前账号下使用当前实例所属VPC自动创建一个公网NAT网关、一个弹性公网IP（EIP）以及配置一条SNAT路由规则，通过该网关支持ClickStack节点访问公网大模型。
服务开启后，如果本机IP不在实例的白名单中，系统将提示自动添加。
开通公网访问大模型能力
如果您在开启ClickStack服务时未勾选支持公网访问大模型，可观测数据智能AI助手将无法正常使用。您可以在服务开通后通过以下两种方式开通该能力。
在ClickHouse控制台一键开通
登录云数据库ClickHouse控制台，在页面左上角，选择集群所在的地域。
在集群列表页面，选择对应版本的实例列表，单击目标集群ID。
在左侧导航栏单击ClickStack。
在公网访问提示栏中，单击开通公网访问大模型。
ClickStack服务将进入公网开通中状态，预计需要1～2分钟。开通过程中无法访问ClickStack服务，开通完成后状态恢复。
开通完成后，您可以在ClickStack页面查看自动创建的公网NAT实例ID、EIP实例ID以及EIP公网地址。
手动配置
如果您需要更灵活的网络配置，可以手动创建EIP和NAT网关。
步骤一：创建弹性公网IP（EIP）
- 登录弹性公网IP管理控制台。
选择与ClickHouse集群相同的地域，创建一个弹性公网 IP实例。
步骤二：创建公网NAT网关并绑定EIP
如果ClickHouse集群所属VPC下无公网NAT网关实例，单击创建公网NAT网关，选择与ClickHouse集群相同的地域和VPC，并选择步骤一中创建的弹性公网IP实例进行绑定。
如果ClickHouse集群所属VPC下已存在公网NAT网关实例，在公网NAT网关控制台的实例列表页面，单击对应实例的更多 > 绑定弹性公网IP，选择步骤一中创建的EIP进行绑定。
步骤三：创建SNAT条目
前往公网 NAT 网关页面，进入目标NAT网关实例详情页面。
单击SNAT管理选项卡，然后单击创建SNAT条目。
SNAT条目粒度选择ECS/弹性网卡粒度。
在ECS/弹性网卡选项中，选择名称为
rds-eni-<ClickHouse实例ID>-webui的辅助弹性网卡。选择弹性公网IP地址为步骤一中创建的EIP。
单击确定，等待SNAT条目创建完成。
公网访问资源释放
出于业务安全考虑，ClickHouse实例释放时不会自动删除创建的NAT网关以及EIP实例，释放实例后需要在相应控制台进行手动释放。
资源释放：
对于一键开通的公网资源
由ClickStack服务自动创建的NAT与EIP资源可以通过标签
createdby:<实例ID>进行筛选并删除。对于手动创建的公网资源
需要结合业务使用情况决定是否需要删除。
使用流程
主页面
，可在当前页面查看对应log的信息。可观测数据智能AI助手
可观测数据智能AI助手可以协助进行OTEL可观测数据相关表的数据分析工作，可以自动识别实例中OTEL可观测数据相关的库表信息，自动根据业务需求构造查询语句获取可观测数据，最后自动化分析并返回诊断结果，应用场景主要包括：业务趋势分析、数据量分析、RCA异常根因诊断等。
前提条件
已开通公网访问大模型能力。
使用方法
在ClickStack主页面，单击页面左侧导航栏的AI NoteBook按钮。
在AI助手聊天窗口中，输入您需要分析的问题，AI助手将自动查询可观测数据并返回分析结果。
常见场景展示
（1）定位业务日志错误率
问题案例：
帮我分析一下过去一个小时里，我的OpenClaw程序有没有什么异常
帮我分析一下过去10分钟，我的管控trace数据哪些组件错误率较高
诊断结果
结论
根据对 clickobserve_service.otel_traces 表在 2026-05-06 19:50:00 至 2026-05-06 20:00:00 时间范围内的采样分析：
错误率统计
- 整体错误率约为 0.32%（基于 7 个 0.5 秒时间窗口的采样数据，共 248,077 个 Span）
- 错误 Span 总量：917
- 正常 Span（OK + UNSET）：207,150
StatusCode 分布
StatusCode 数量 占比 备注
UNSET 139,911 74.7% -
OK 66,247 23.08% -
ERROR 919 0.32% -
证据
- 查看 artifact 源自 /artifacts/sessions/c-b859bd2-3942-4d85-b636-51dae0d****/sql_results.json
局限性
- 采样偏差：由于 ClickHouse 的 max_rows_to_read 限制（20 万行），无法覆盖所有数据 10 分钟数据，实际样本有偏差
- 时间窗口代表性：采样点分布在 19:50~20:00 之间，如可能存在仅大量数据的区间被遗漏
- 误差范围：实际错误率可能在 0.2% ~ 0.5% 之间浮动
后续步骤（如需要更精确分析）
- 如需精确错误率，可能需要调整查看完成加采样比的和数量
- 如对异常感兴趣的，可以一步查询 StatusMessage 或 Events 字段获取错误详情
- 对有 SpanName 或 ServiceName 做更深下钻，定位具体是哪些服务的异常贡献（2）根因诊断
问题案例：
帮我分析一下最近一个小时，我的管控组件日志有没有报错，并分析他们的错误原因
为什么我有一个网关请求报错了，requestId/traceId = ea7d2925-3422-4920-9ab1-b22dd3d85b2f，帮我分析一下详细原因
诊断结果
错误数据分析结论
基于对 clickobserve_service.otel_traces 表在 2026-05-06 19:50:00 至 20:00:00 时间范围内的采样分析，以下是错误采样数据和错误分析结果。
一、错误类型分布
HTTP 状态码 错误数量 占比 类型 描述
404 81 -64% 资源不存在 -
500 19 -10% 服务器内部错误 -
503 3 -2% 服务不可用 -
206 1 -2% 部分内容传输 可视为边缘可能 1000 万请求偶发
二、典型错误案例分析
案例 1：404 Not Found — 资源文件路径不存在
- TraceId：b1b97380c855083a23ec76ace14e53be
- SpanName：GET
- 请求路径：http://test-xxxx.com/api/v1.0/clusterInstances/3463****
- 错误原因：目标资源ID 19 36317596 对于目标服务器不存在，确认服务部署和路由配置中 TraceId 下所有关联 Span 均为 404
- 证据链接：/artifacts/sessions/c-b859bd2-3942-4d85-b636-51dae0d18ae/sql_results.json行22
案例 2：503 Service Unavailable — 服务暂时不可用
- TraceId：b1b97380c855083a23ec76ace14e53be
- SpanName：GET / POST
- 请求路径：http://test-xxxx.com/api/v1.0/replicatSets/308351****/myfd
- 证据链接：/artifacts/sessions/c-b859bd2-3942-4d85-b636-51dae0d18ae/sql_results.json行22
案例 3：STS 服务调用报错
- SpanName：POST https://sts.cn-hangzhou.null/
- 错误类型：.null 域名，即域名解析错误或 DNS 解析失败
- STS 服务可能在配置中缺少域名
- 证据链接：/artifacts/sessions/c-b859bd2-3942-4d85-b636-51dae0d18ae/sql_results.json行10
案例 4：基础错误 Error 类型
...会话管理
AI助手支持创建并管理多个会话，您可以进行以下操作：
新建会话：在服务页面单击顶部的+按钮，输入会话名称创建新的会话。
删除会话：在服务页面单击顶部的删除按钮，即可删除当前会话。
重命名会话：在服务页面单击顶部的编辑按钮，输入新名称后按回车确认。
切换输出模式
AI助手支持两种输出模式，您可以通过聊天窗口中的切换按钮进行切换：
流式输出（默认）：实时逐步展示分析结果，响应速度更快。
普通输出：等待分析完成后一次性展示完整结果。
自定义大盘
服务提供预设大盘供您直接使用，您可以单击左侧导航栏的PRESETS>Services查看。您也可以创建自定义大盘，将感兴趣的指标聚合展示在同一个报表中。
单击页面左侧导航栏的Create Dashboard。
单击Add New Tile。
设置数据源与指标，并单击保存。
Data Source 选择 otel_logs，聚合方式选择 Count of Events。
服务配置
如果您在开启服务时勾选了自动创建表，则已为您自动配置对应表的服务配置。您也可以按需配置其他表作为数据源。
单击页面左侧导航栏的Team Settings。
在Sources区域配置数据源，用于定义logs、metrics、traces数据来源于哪个表，以及列的映射关系。数据配置请参见下方：
logs
otel_logs 数据源的 Source Settings 配置如下：
Name：
otel_logsSource Data Type：Log
Server Connection：ClickHouse 实例 ID（如
cc-bp1vxxx）Database：
clickobserve_serviceTable：
otel_logsTimestamp Column：
TimestampTimeDefault Select：
Timestamp, ServiceName as service, SeverityText as level, Body
metrics
在 HyperDX 中配置 otel_metrics 数据源，各字段设置如下：
Name：
otel_metricsSource Data Type：OTEL Metrics
Server Connection：选择对应的 ClickHouse 实例
Database：
clickobserve_serviceGauge Table：
otel_metrics_gaugeHistogram Table：
otel_metrics_histogramSum Table：
otel_metrics_sumSummary Table：
otel_metrics_summaryExponential Histogram Table：
otel_metrics_exponential_histogramCorrelated Log Source：
otel_logs
配置完成后单击 Save Source 保存。
traces
在 Source Settings 页面配置 otel_traces 链路追踪数据源，主要字段如下：
Name：
otel_tracesSource Data Type：Trace
Server Connection：对应 ClickHouse 实例 ID
Database：
clickobserve_serviceTable：
otel_tracesTimestamp Column：
TimestampDefault Select：
Timestamp, ServiceName as service, StatusCode as level, round(Duration / 1e6...)Duration Expression：
Duration，精度设为 NanosecondTrace Id Expression：
TraceIdSpan Id Expression：
SpanIdParent Span Id Expression：
ParentSpanIdSpan Name Expression：
SpanNameSpan Kind Expression：
SpanKindCorrelated Log Source：
otel_logsCorrelated Metric Source：
otel_metricsStatus Code Expression：
StatusCodeStatus Message Expression：
StatusMessageService Name Expression：
ServiceNameResource Attributes Expression：
ResourceAttributesEvent Attributes Expression：
SpanAttributesSpan Events Expression：
EventsImplicit Column Expression：
SpanName
在Connections区域配置连接配置，用于配置可观测服务与云数据库ClickHouse实例的连接。默认会创建一个到本实例的连接配置。其中Host表示与云数据库ClickHouse实例的Endpoint，仅支持使用VPC地址。若您配置实例Endpoint后在实例控制台上修改Endpoint地址，则需要重新配置。
在ClickHouse Client Settings区域，配置可观测服务在云数据库ClickHouse实例上的查询参数。
用户偏好
您可以在左侧导航栏下方，单击用户名，然后选择User Preferences，设置用户偏好。