Back to Details

cx-telemetry-querying

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Telemetry Querying Skill

Telemetry Querying Skill

Use this skill as the entry point for any investigation, debugging, or data question that may be answered from telemetry data. This skill helps you decide where the relevant signal lives (metrics, logs, traces, RUM, APM) before diving into queries, then delegates to specialized skills for deep exploration.
将此Skill用作任何可通过遥测数据解答的调查、调试或数据问题的入口。该Skill可帮助你在深入查询前确定相关信号所在的位置（指标、日志、追踪、RUM、APM），然后将任务委托给专业Skill进行深度探索。

Core Principle

核心原则

Decide where to look before querying. Telemetry data is spread across multiple pillars. Choosing the right source first saves time and yields better answers.
查询前先确定数据源。遥测数据分布在多个支柱中。优先选择正确的数据源可节省时间并获得更准确的答案。

Safety

安全性

All query commands (
cx logs
, 
cx spans
, 
cx metrics
, 
cx dataprime
, 
cx search-fields
) are read-only and work in 
--read-only
mode. They never modify data and can be run freely without 
--yes
.
When running inside an AI agent, read commands are unaffected by agent mode detection - no confirmation is needed for queries.
所有查询命令（
cx logs
、
cx spans
、
cx metrics
、
cx dataprime
、
cx search-fields
）均为只读模式，运行在
--read-only
模式下。它们绝不会修改数据，无需添加
--yes
即可自由运行。
在AI Agent中运行时，读取命令不受Agent模式检测影响——查询无需确认。

Quick Routing Guide

快速路由指南

Use this table for obvious cases where one pillar is the clear first choice:
Question TypeFirst ChoiceFallback
UI behavior, page load, frontend errorsRUMTraces (if backend-related)
Endpoint latency, throughput, error ratesMetricsTraces (for per-request detail)
Service-to-service dependencies, request flowTracesLogs (for debug output)
Specific error messages, stack tracesLogsTraces (for request context)
Infrastructure health (CPU, memory, disk)Metrics-
Business events (purchases, signups)Depends - see Discovery Workflow-
For ambiguous questions (e.g., "How much money did users spend last week?"), the signal could live in any pillar. Follow the Discovery Workflow below.
对于明显可确定首选数据源的场景，可使用下表：
问题类型首选数据源备选方案
UI行为、页面加载、前端错误RUMTraces（若与后端相关）
端点延迟、吞吐量、错误率指标Traces（用于单请求细节）
服务间依赖、请求流Traces日志（用于调试输出）
特定错误信息、堆栈追踪日志Traces（用于请求上下文）
基础设施健康（CPU、内存、磁盘）指标-
业务事件（购买、注册）视情况而定——参见发现流程-
对于模糊问题（例如：“上周用户在平台上花费了多少钱？”），信号可能存在于任意支柱中，请遵循以下发现流程。

Discovery Workflow

发现流程

When the answer could reside in multiple pillars, run discovery in parallel to find the best source.
当答案可能存在于多个支柱中时，并行执行发现操作以找到最佳数据源。

Step 1: Search Metrics

步骤1：搜索指标

Check if a relevant metric exists:
bash
cx metrics search --name '*transaction*'
cx metrics search --name '*payment*'
cx metrics search --name '*revenue*'
cx metrics search --description "total purchase amount"
If a matching metric is found, continue with the 
cx-metrics-query
skill.
检查是否存在相关指标：
bash
cx metrics search --name '*transaction*'
cx metrics search --name '*payment*'
cx metrics search --name '*revenue*'
cx metrics search --description "total purchase amount"
如果找到匹配指标，请继续使用
cx-metrics-query
Skill。

Step 2: Search Log and Span Fields

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

Use semantic field search to find relevant DataPrime paths:
bash
cx search-fields "transaction amount" --dataset logs
cx search-fields "payment total" --dataset spans
cx search-fields "purchase value" --dataset logs --limit 10
Requirements: 
cx search-fields
needs a Coralogix API key or OAuth on the active profile. If credentials are missing, prompt the user to run 
cx profiles add
.
If matching fields are found:
  • For logs: continue with the 
    cx-query-logs
    skill using DataPrime
  • For spans: continue with the 
    cx-query-spans
    skill
使用语义字段搜索查找相关DataPrime路径：
bash
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
需要Coralogix API密钥或活动配置文件中的OAuth。如果缺少凭据，请提示用户运行
cx profiles add
。
如果找到匹配字段：
  • 对于日志：使用DataPrime继续执行
    cx-query-logs
    Skill
  • 对于Spans：继续执行
    cx-query-spans
    Skill

Step 3: Search the Codebase

步骤3：搜索代码库

When discovery results are ambiguous or you need to validate what a metric/field actually represents, search the codebase:
  • Look for metric registration code (e.g., 
    prometheus.NewCounter
    , 
    metrics.record
    )
  • Look for log statements that emit the field (e.g., 
    logger.info("transaction", ...)
    )
  • Look for span attributes (e.g., 
    span.setAttribute("purchase.amount", ...)
    )
This confirms the semantic meaning and helps you choose the right pillar.
当发现结果模糊或需要验证指标/字段的实际含义时，搜索代码库：
  • 查找指标注册代码（例如：
    prometheus.NewCounter
    、
    metrics.record
    ）
  • 查找输出该字段的日志语句（例如：
    logger.info("transaction", ...)
    ）
  • 查找Span属性（例如：
    span.setAttribute("purchase.amount", ...)
    ）
这可以确认语义含义，并帮助你选择正确的支柱。

Step 4: Choose and Query

步骤4：选择并查询

Based on discovery results, pick the pillar with the clearest signal and delegate to the appropriate skill:
PillarSkill to Use
Metrics
cx-metrics-query
Logs
cx-query-logs
Traces/Spans
cx-query-spans
RUM
cx-rum
APMAPM-specific guidance
根据发现结果，选择信号最清晰的支柱，并委托给相应的Skill：
支柱使用的Skill
指标
cx-metrics-query
日志
cx-query-logs
追踪/Span
cx-query-spans
RUM
cx-rum
APMAPM专属指南

Fallback and Pivoting

备选方案与转向

If your initial route yields no results, pivot to another pillar.
Example pivot paths:
  • Metrics empty → try traces (per-request data) or logs (event records)
  • Logs empty → try traces (structured span attributes) or metrics (aggregated counters)
  • Traces empty → try logs (text-based debug output)
Do not stop after one failed attempt. Try at least two pillars before concluding the data does not exist.
如果初始路由没有结果，请转向其他支柱。
示例转向路径：
  • 指标无数据 → 尝试Traces（单请求数据）或日志（事件记录）
  • 日志无数据 → 尝试Traces（结构化Span属性）或指标（聚合计数器）
  • Traces无数据 → 尝试日志（文本型调试输出）
不要在一次尝试失败后就停止。在得出数据不存在的结论前，至少尝试两个支柱。

CLI Commands Reference

CLI命令参考

CommandPurposeWhen to Use
cx schema
Output the full command tree as JSONDiscover all available commands and their flags
cx metrics search --name <pattern>
Find metrics by nameFirst step for metrics discovery
cx metrics search --description <text>
Semantic metric searchWhen you know what you want but not the name
cx search-fields "<text>" --dataset logs
Find log fields by descriptionDiscovery for log-based questions
cx search-fields "<text>" --dataset spans
Find span fields by descriptionDiscovery for trace-based questions
cx spans "filter $l.serviceName == '<service>'" --limit 10
Search spans by serviceWhen investigating a specific service
cx dataprime list
List DataPrime commands/functionsWhen building log queries
命令用途使用场景
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字段基于追踪的问题发现
cx spans "filter $l.serviceName == '<service>'" --limit 10
按服务搜索Span调查特定服务时
cx dataprime list
列出DataPrime命令/函数构建日志查询时

Examples

示例

Example 1: Business Question (Ambiguous Source)

示例1：业务问题（数据源模糊）

Question: "How much money did people spend on the platform last week?"
Approach:
  1. Search metrics: 
    cx metrics search --name '*revenue*'
    and 
    cx metrics search --name '*transaction*'
  2. Search log fields: 
    cx search-fields "transaction amount" --dataset logs
  3. Search span fields: 
    cx search-fields "payment total" --dataset spans
  4. If a metric like 
    payment_total_usd
    exists, use 
    cx-metrics-query
    skill with a range query
  5. If only logs have the data, use 
    cx-query-logs
    skill with DataPrime aggregation
  6. If traces have 
    purchase.amount
    attribute, use 
    cx-query-spans
    skill
问题：“上周用户在平台上花费了多少钱？”
方法：
  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
    之类的指标，使用
    cx-metrics-query
    Skill执行范围查询
  5. 如果只有日志包含数据，使用
    cx-query-logs
    Skill结合DataPrime聚合
  6. 如果Traces包含
    purchase.amount
    属性，使用
    cx-query-spans
    Skill

Example 2: Latency Question (Clear First Choice)

示例2：延迟问题（明确首选数据源）

Question: "What's the average latency of the checkout route?"
Approach:
  1. First try metrics: 
    cx metrics search --name '*checkout*latency*'
    or 
    cx metrics search --name '*http*duration*'
  2. If a histogram metric exists, use 
    cx-metrics-query
    skill with 
    histogram_quantile
  3. If no metric, fall back to traces: 
    cx spans "filter $l.serviceName == 'checkout-service'" --limit 10
    and aggregate span durations
问题：“结账路由的平均延迟是多少？”
方法：
  1. 首先尝试指标：
    cx metrics search --name '*checkout*latency*'
    或 
    cx metrics search --name '*http*duration*'
  2. 如果存在直方图指标，使用
    cx-metrics-query
    Skill结合
    histogram_quantile
  3. 如果没有指标，转向Traces：
    cx spans "filter $l.serviceName == 'checkout-service'" --limit 10
    并聚合Span时长

Example 3: Frontend Performance (RUM)

示例3：前端性能（RUM）

Question: "Why is the dashboard page loading slowly for users?"
Approach:
  1. This is clearly a RUM question - frontend page load data
  2. Use 
    cx-rum
    skill directly
  3. If RUM shows backend calls are slow, pivot to 
    cx-query-spans
    for the API calls
问题：“为什么用户的仪表板页面加载缓慢？”
方法：
  1. 这显然是RUM问题——前端页面加载数据
  2. 直接使用
    cx-rum
    Skill
  3. 如果RUM显示后端调用缓慢，转向
    cx-query-spans
    Skill分析API调用

Example 4: Error Investigation (Logs + Traces)

示例4：错误调查（日志+Traces）

Question: "Why are users getting 500 errors on the payment endpoint?"
Approach:
  1. Check error rate metrics: 
    cx metrics search --name '*error*'
    → 
    cx-metrics-query
    skill
  2. Search for error logs: 
    cx search-fields "error message" --dataset logs
    → 
    cx-query-logs
    skill
  3. Get traces for failed requests: 
    cx spans "filter $l.serviceName == 'payment-service'" --limit 10
    → 
    cx-query-spans
    skill
  4. Cross-reference: find trace IDs in logs, then fetch full traces for root cause
问题：“为什么用户在支付端点收到500错误？”
方法：
  1. 检查错误率指标：
    cx metrics search --name '*error*'
    → 使用
    cx-metrics-query
    Skill
  2. 搜索错误日志：
    cx search-fields "error message" --dataset logs
    → 使用
    cx-query-logs
    Skill
  3. 获取失败请求的Traces：
    cx spans "filter $l.serviceName == 'payment-service'" --limit 10
    → 使用
    cx-query-spans
    Skill
  4. 交叉引用：在日志中查找Trace ID，然后获取完整Traces以排查根本原因

Beyond Investigation

除调查外的场景

Not every question is answered by querying data. If the user's intent is operational rather than investigative, route to the appropriate workflow skill:
User IntentRoute To
Reducing costs, checking usage, TCO policies
cx-cost-optimization
Incident triage, SLO breaching, who got paged
cx-incident-management
Setting up monitoring, webhooks, notifications
cx-observability-setup
Configuring parsing rules, enrichments, E2M
cx-data-pipeline
Access audit, API keys, user management
cx-platform-admin
Creating or managing dashboards
cx-create-dashboard
并非所有问题都能通过查询数据解决。如果用户的意图是操作而非调查，请路由到相应的工作流Skill：
用户意图路由至
成本优化、使用量检查、TCO策略
cx-cost-optimization
事件分诊、SLO违规、通知对象确认
cx-incident-management
监控设置、Webhook、通知配置
cx-observability-setup
解析规则、数据增强、E2M配置
cx-data-pipeline
访问审计、API密钥、用户管理
cx-platform-admin
仪表板创建与管理
cx-create-dashboard

Key Principles

关键原则

  • Discover before querying: always run search/discovery to find the right source
  • Parallel discovery: for ambiguous questions, search metrics, logs, and spans concurrently
  • Validate with code: when unsure what a metric or field represents, check the codebase
  • Pivot on failure: if one pillar is empty, try another before giving up
  • Delegate to specialists: once you know the pillar, hand off to the dedicated skill
  • 先发现再查询：始终先执行搜索/发现以找到正确的数据源
  • 并行发现：对于模糊问题，同时搜索指标、日志和Span
  • 通过代码验证：不确定指标或字段含义时，检查代码库
  • 失败时转向：如果一个支柱无数据，尝试其他支柱后再放弃
  • 委托给专业Skill：确定支柱后，转交给专用Skill处理

Related Skills

相关Skill

Investigation Skills

调查类Skill

  • cx-dataprime
     - DataPrime query language reference (syntax, operators, aggregations, functions)
  • cx-metrics-query
     - PromQL queries, metric discovery, instant and range queries
  • cx-query-logs
     - DataPrime log queries, log field exploration
  • cx-query-spans
     - Trace search, span analysis, distributed tracing
  • cx-rum
     - Frontend performance, user sessions, page loads
  • cx-alerts
     - Creating and managing alert definitions
  • cx-create-dashboard
     - Dashboard creation and management
  • cx-dataprime
     - DataPrime查询语言参考（语法、运算符、聚合、函数）
  • cx-metrics-query
     - PromQL查询、指标发现、即时查询与范围查询
  • cx-query-logs
     - DataPrime日志查询、日志字段探索
  • cx-query-spans
     - 追踪搜索、Span分析、分布式追踪
  • cx-rum
     - 前端性能、用户会话、页面加载
  • cx-alerts
     - 告警规则的创建与管理
  • cx-create-dashboard
     - 仪表板的创建与管理

Workflow Skills

工作流类Skill

  • cx-cost-optimization
     - Analyze and reduce Coralogix data costs
  • cx-incident-management
     - Incident triage, SLO monitoring, notification verification
  • cx-data-pipeline
     - Parsing rules, enrichments, E2M, recording rules
  • cx-platform-admin
     - Access audit, API keys, user and role management
  • cx-observability-setup
     - Views, webhooks, notifications, integrations setup
  • cx-cost-optimization
     - 分析并降低Coralogix数据成本
  • cx-incident-management
     - 事件分诊、SLO监控、通知验证
  • cx-data-pipeline
     - 解析规则、数据增强、E2M、记录规则
  • cx-platform-admin
     - 访问审计、API密钥、用户与角色管理
  • cx-observability-setup
     - 视图、Webhook、通知、集成设置