尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
ClickStack 与 HyperDX
Loom 始终输出 OpenTelemetry 数据;HyperDX 的数据源、控制台和擦除步骤需要另行配置。
Loom 为每个操作输出一个 span,并附带日志和指标。span 带有 loom.operation、loom.org、loom.namespace、loom.agent、loom.request_id,以及存在时的 loom.user_id / enduser.id。默认情况下,Loom 按采集器(collector)的表结构,把这些数据直接写入其自身 ClickHouse 服务上的 default.otel_* 表,因此 HyperDX 无需运行任何采集器即可读取。如果设置了 LOOM_CLICKSTACK_DATABASE,这些表会位于该数据库而不是 default 中,这里以及下文的每条查询都是如此。列布局见 schemas/otel/clickstack_otel_tables.sql;如果 ClickStack 更改了其表结构,该文件必须随之更新。
模型调用 span 带有 OpenTelemetry GenAI 属性(遥测),属性键与 HyperDX 的 LLM 视图读取提供方、操作、token 用量、提示缓存占比和成本时使用的键一致。
选择导出路径
LOOM_OTEL_EXPORTER |
行为 |
|---|---|
ch |
写入同一服务上的 default.otel_traces、otel_logs、otel_metrics_sum、otel_metrics_histogram 和 otel_metrics_gauge |
otlp |
发送到 LOOM_OTEL_EXPORTER_OTLP_ENDPOINT(请求头在 LOOM_OTEL_EXPORTER_OTLP_HEADERS 中),用于 collector 或其他后端 |
| 空(默认) | 设置了 endpoint 时为 otlp,否则为 ch |
在 ch 模式下,Loom 会先检查 default.otel_traces 是否存在;如果不存在,导出器会在输出一行日志后自动禁用。创建这些表:
clickhouse-client --multiquery < schemas/otel/clickstack_otel_tables.sql
GET /v1/health?include=otel 会显示实际生效的导出器。其余 OTel 设置(导出间隔、temporality、gauge 心跳、服务名称)请参阅 遥测。
将 HyperDX 指向这些表
数据行已经在服务中,因此可以跳过 collector 和 ingestion key 的步骤。创建三个 HyperDX source:基于 otel_traces 的 traces,基于 otel_logs 的 logs,以及基于 otel_metrics_* 的 metrics。deploy/clickstack_sources.sh 会通过 HyperDX API 创建这些 source 并配置它们之间的关联(托管版 ClickStack 使用你的控制台会话 cookie HDX_COOKIE 进行身份验证)。deploy/hyperdx_dashboards.md 中列出了每个 source 的字段映射。
控制台与告警
deploy/hyperdx_dashboards.md 是配置手册:
- Loom — Memory Health:检索质量趋势(
loom.search.top_similarity)、按操作和传输方式划分的调用数与错误数、系统状态、开销与 token、按检索平面划分的延迟、写入结果,以及请求面板(速率、延迟、错误、最慢请求、按租户划分的流量、某个 trace 的日志)。 - Loom — Code Plane:索引滞后、层级滞后以及其他
loom.code.*指标。JSON 定义位于deploy/dashboards/code_plane.json。 - 引导顺序,以及已保存的搜索。
自行编写图块时有两个陷阱:
- 计数器是累计值。 除非设置
LOOM_OTEL_METRICS_DELTA_TEMPORALITY=true,否则计数器的行是其累计总数;计算速率需要取相邻数据点之间的差值,而不是求和。修改该设置时,要同时修改控制台。 - 在 HyperDX 中,空结果会被读作 0。 告警上的最小样本数保护必须返回一个处于正常范围内的值,而不是不返回任何行,否则告警会在没有数据时触发。
指标名称和建议的阈值见指标目录。
擦除
需要设置 LOOM_CLICKSTACK_DATABASE。ClickStack 没有用于删除用户数据的管理 API,因此后端(server/erasure/app/backends.py 中的 ClickStackBackend)会针对该数据库中的 OTel 表执行轻量级 DELETE FROM 语句:
| 表 | 搜索的属性列 |
|---|---|
otel_logs |
LogAttributes |
otel_traces |
SpanAttributes |
otel_metrics_gauge, _sum, _histogram, _exponential_histogram, _summary |
Attributes |
hyperdx_sessions |
ResourceAttributes |
- 用户范围匹配
LOOM_CLICKSTACK_USER_ID_KEYS中的任意一个键(默认为user_id,user.id,enduser.id,loom.user_id,langfuse.user.id),各键之间为 OR 关系,因为不同 SDK 对键名的约定并不一致。Loom 的请求 span 携带enduser.id;其模型调用 span 携带loom.user_id和langfuse.user.id,配置了 Langfuse 时,请求在解析出调用方之后打开的其他每个 span 也都携带这两个键。这些 span 同样携带loom.org,因此下文的组织保护规则同样适用。 - 命名空间范围匹配
loom.namespace或service.namespace。Loom 的导出器把service.namespace设为常量loom,并在loom.namespace中携带租户;service.namespace用于覆盖写入同一个 ClickStack 的其他发送方,其值loom永远不会被匹配。 - 组织保护。带有其他组织
loom.org标记的行绝不会被擦除。通过loom.namespace匹配到的行必须带有执行擦除的组织的loom.org。Loom 的操作和领域指标(计数器和直方图)带有loom.namespace,但不带组织,因此命名空间擦除不会处理它们:它们不包含记忆内容,但其loom.namespace标签就是命名空间名称,而个人命名空间的名称由用户的电子邮件派生。它们会一直保留,直到收集器表自身的 TTL(如果有)将其移除。没有loom.org标记、但被用户键或service.namespace(其他发送方)匹配到的行会被擦除,因为它们可能包含该主体的数据。
轻量级删除只写入行存在掩码,因此这些行会立即从所有读取中消失,其占用的字节会在下一次合并时释放;而 ALTER TABLE … DELETE 会重写每个受影响的数据分片。对于属性 map 值上没有布隆过滤器的表(指标表都没有),该谓词会进行全表扫描;loom doctor 会指出这些表。
该步骤会在删除前统计行数,并报告该数量。表或数据库不存在时视为无需擦除;任何其他失败都会使该步骤以失败告终(fail closed),并由 erasure_recovery worker 重试。
在依赖默认值之前,请先检查你的数据实际携带了哪些用户 ID 键:
SELECT DISTINCT arrayJoin(mapKeys(LogAttributes))
FROM default.otel_logs WHERE TimestampTime > now() - INTERVAL 1 DAY
该步骤所属的 saga 请参见保留与擦除。
设置
| 设置 | 默认值 | 作用 |
|---|---|---|
LOOM_OTEL_EXPORTER |
"" |
ch、otlp 或自动选择 |
LOOM_OTEL_EXPORTER_OTLP_ENDPOINT |
"" |
collector 的基础 URL |
LOOM_OTEL_EXPORTER_OTLP_HEADERS |
"" |
以逗号分隔的 K=V 请求头 |
LOOM_OTEL_ENABLED |
true |
总开关 |
LOOM_CLICKSTACK_DATABASE |
"" |
OTel 表所在的数据库;启用后可执行擦除 |
LOOM_CLICKSTACK_USER_ID_KEYS |
user_id,user.id,enduser.id,loom.user_id,langfuse.user.id |
按用户范围擦除时匹配的属性键 |