cx-telemetry-querying

遥测查询技能

将此技能用作任何可通过遥测数据回答的调查、调试或数据问题的入口。它可以帮助你判断相关信号位于何处（指标、日志、追踪、RUM），并告知你查询前应加载哪些参考文件。

加载参考文件

查询前，加载所选类别的参考文件：

类别	加载这些文件
日志	references/dataprime-reference.md + references/logs-querying.md
Span / 追踪	references/dataprime-reference.md + references/spans-querying.md
指标	references/promql-guidelines.md + references/metrics-querying.md
RUM（前端）	references/dataprime-reference.md + references/rum-querying.md + references/rum-fields.md
仅 DataPrime 语法	references/dataprime-reference.md

---

安全性

所有查询命令（cx logs、cx spans、cx metrics、cx dataprime、cx search-fields）均为只读，并且支持 --read-only 模式。它们不会修改数据，无需添加 --yes 即可自由运行。

---

快速路由指南

对于以下一目了然、某个类别明显是首选的情况，请参考此表：

问题类型	首选	备选
UI 行为、页面加载、前端错误	RUM	追踪（与后端相关时）
端点延迟、吞吐量、错误率	指标	追踪（查看单个请求的详情）
服务间依赖关系、请求流	追踪	日志（查看调试输出）
特定错误消息、堆栈追踪	日志	追踪（查看请求上下文）
基础设施健康状况（CPU、内存、磁盘）	指标	-
业务事件（购买、注册）	视情况而定——参见发现工作流	-

对于模糊问题（例如，“用户上周花了多少钱？”），相关信号可能位于任何类别中。请遵循下文的发现工作流。

---

发现工作流

如果答案可能存在于多个类别中，请并行执行发现，以找出最佳数据源。

第 1 步：搜索指标

检查是否存在相关指标：

cx metrics search --name '*transaction*'
cx metrics search --name '*payment*'
cx metrics search --name '*revenue*'
cx metrics search --description "total purchase amount"

如果找到匹配的指标，请加载 references/promql-guidelines.md + references/metrics-querying.md 并继续。

第 2 步：搜索日志和 Span 字段

使用语义字段搜索查找相关的 DataPrime 路径：

cx search-fields "transaction amount" --dataset logs
cx search-fields "payment total" --dataset spans
cx search-fields "purchase value" --dataset logs --limit 10

如果你知道某个应该出现在数据中的具体值，但不知道它存储在哪个字段中，请改用值搜索。它会返回匹配的字段键及示例值，你也可以据此推断字段类型（字符串、数值、枚举等）：

cx search-fields "payment_failed" -s value --dataset logs
cx search-fields "grpc.status.UNAVAILABLE" -s value --dataset spans
cx search-fields "eu-west-1" -s value --dataset all

要求： cx search-fields 需要活动配置文件中有 Coralogix API 密钥或 OAuth 凭据。如果缺少凭据，请提示用户运行 cx profiles add <name>。

如果找到匹配字段：

• 对于日志：加载 references/dataprime-reference.md + references/logs-querying.md
• 对于Span：加载 references/dataprime-reference.md + references/spans-querying.md

第 3 步：搜索代码库

如果发现结果不明确，或者你需要验证某个指标/字段实际表示什么，请搜索代码库：

• 查找指标注册代码（例如，prometheus.NewCounter、metrics.record）
• 查找输出该字段的日志语句（例如，logger.info("transaction", ...)）
• 查找 Span 属性（例如，span.setAttribute("purchase.amount", ...)）

这有助于确认其语义含义，并帮助你选择正确的类别。

第 4 步：选择并查询

根据发现结果，选择信号最明确的类别，加载其参考文件（参见加载参考文件），然后执行查询。

---

回退与切换方向

如果初始路径没有结果，请切换到另一个支柱。

切换路径示例：

• 指标为空 → 尝试 traces（每个请求的数据）或日志（事件记录）
• 日志为空 → 尝试 traces（结构化 span 属性）或指标（聚合计数器）
• Traces 为空 → 尝试日志（基于文本的调试输出）

不要在一次尝试失败后就停止。下结论认为数据不存在之前，至少尝试两个支柱。

---

CLI 命令参考

命令	用途	使用时机
cx schema	将完整命令树输出为 JSON	发现所有可用命令及其标志
cx metrics search --name <pattern>	按名称查找指标	发现指标的第一步
cx metrics search --description <text>	语义化指标搜索	知道想找什么，但不知道名称时
cx search-fields "<text>" --dataset logs	按描述查找日志字段	探索基于日志的问题
cx search-fields "<text>" --dataset spans	按描述查找 span 字段	探索基于 trace 的问题
cx search-fields "<value>" -s value --dataset logs	查找包含已知值的日志字段	知道某个值，但不知道它存在哪个日志字段中时——返回值还会显示字段类型
cx search-fields "<value>" -s value --dataset spans	查找包含已知值的 span 字段	知道某个值，但不知道它存在哪个 span 属性中时
cx search-fields "<value>" -s value --dataset all	同上，同时搜索日志和 spans	想要一次搜索日志和 spans 时
cx spans "filter $l.serviceName == '<service>'" --limit 10	按服务搜索 spans	调查特定服务时
cx dataprime list	列出 DataPrime 命令/函数	构建日志或 span 查询时
cx dashboards search "<description>"	按自然语言描述查找现有仪表板	创建新仪表板前——先检查是否已有相关仪表板
cx dashboards query-search --description "<text>"	查找查询覆盖某主题的仪表板组件	了解某个主题目前已如何受到监控
cx dashboards query-search --field "<field-path>"	查找引用特定字段的组件	为已知字段复用现有 PromQL/DataPrime 模式

---

示例

示例 1：业务问题（数据来源不明确）

问题：“上周用户在平台上花了多少钱？”

方法：

1. 搜索指标：cx metrics search --name '*revenue*' 和 cx metrics search --name '*transaction*'
2. 搜索日志字段：cx search-fields "transaction amount" --dataset logs
3. 搜索 span 字段：cx search-fields "payment total" --dataset spans
4. 如果存在 payment_total_usd 之类的指标，加载指标参考并运行范围查询
5. 如果只有日志包含相关数据，加载日志参考并使用 DataPrime 聚合
6. 如果 traces 中有 purchase.amount 属性，加载 spans 参考

示例 2：延迟问题（首选路径明确）

问题：“结账路由的平均延迟是多少？”

方法：

1. 首先尝试指标：cx metrics search --name '*checkout*latency*' 或 cx metrics search --name '*http*duration*'
2. 如果存在直方图指标，加载指标参考并使用 histogram_quantile
3. 如果没有指标，则改查 traces：加载 spans 参考并聚合 span 时长

示例 3：前端性能（RUM）

问题：“为什么用户的仪表板页面加载缓慢？”

方法：

1. 这显然是一个 RUM 问题——加载 references/rum-querying.md + references/rum-fields.md + references/dataprime-reference.md
2. 使用 cx dataprime query --source rum.events '...' 查询 Web Vitals 和页面加载时间
3. 如果 RUM 显示后端调用缓慢，则切换到 spans 参考，调查 API 调用

示例 4：错误排查（日志 + 追踪）

问题：“为什么支付端点出现了 500 错误？”

方法：

1. 检查错误率指标 → 加载指标参考资料
2. 搜索错误日志 → 加载日志参考资料
3. 获取失败请求的追踪信息 → 加载跨度参考资料
4. 交叉比对：在日志中查找追踪 ID，然后获取完整追踪信息以找出根本原因

---

超出排查范围的请求

并非所有问题都能通过查询数据来解答。如果用户的意图是执行运维操作，而非进行调查，请将请求转交给相应的工作流技能：

用户意图	转交给
降低成本、检查用量、TCO 政策	cx-cost-optimization
分诊事件、谁收到寻呼、事件时间线	cx-cases
SLO 状态、错误预算、服务级别目标	cx-slos
设置监控、webhook、通知	cx-observability-setup
配置解析规则、增强处理、E2M	cx-data-pipeline
访问审计、API 密钥、用户管理	cx-platform-admin
创建或管理仪表板	cx-dashboards
查找或搜索现有仪表板	cx-search-dashboard

---

核心原则

• 查询前加载参考资料：先查看加载参考资料表
• 查询前先发现：始终运行搜索/发现，以找到正确的数据源
• 并行发现：对于含糊的问题，并行搜索指标、日志和跨度
• 使用代码验证：不确定某项指标或字段的含义时，检查代码库
• 失败时切换方向：如果某个支柱没有结果，请先尝试其他支柱再放弃