/cx-telemetry-querying

name: cx-telemetry-querying
description: |
  Use this skill for any question involving telemetry data: "investigate an issue",
  "debug a problem", "find out why something is slow", "check error rates",
  "analyze user behavior", "understand a production incident",
  "query telemetry data", "look at logs", "search logs", "find errors",
  "find stack traces", "filter by severity",
  "check traces", "examine spans", "investigate request latency",
  "debug service-to-service calls", "look up a trace ID",
  "analyze RUM data", "query rum.events", "check frontend performance", "frontend errors",
  "Core Web Vitals", "JavaScript exceptions",
  "query metrics", "check CPU usage", "run a PromQL query",
  "check error rate", "look up a metric", "check memory usage",
  "how do I write a DataPrime query", "DataPrime syntax",
  or wants to answer questions using observability data from logs, metrics, traces, RUM, or APM.
metadata:
  version: "0.2.1"

Telemetry Querying Skill

Use this skill as the entry point for any investigation, debugging, or data question that may be answered from telemetry data. It helps you decide **where** the relevant signal lives (metrics, logs, traces, RUM) and tells you **which reference files to load** before querying.

Loading References

Before querying, load the reference files for the chosen pillar:

| Pillar | Load these files | |---|---| | Logs | `references/dataprime-reference.md` + `references/logs-querying.md` | | Spans / Traces | `references/dataprime-reference.md` + `references/spans-querying.md` | | Metrics | `references/promql-guidelines.md` + `references/metrics-querying.md` | | RUM (frontend) | `references/dataprime-reference.md` + `references/rum-querying.md` + `references/rum-fields.md` | | DataPrime syntax only | `references/dataprime-reference.md` |

---

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`.

---

Quick Routing Guide

Use this table for obvious cases where one pillar is the clear first choice:

| Question Type | First Choice | Fallback | |---|---|---| | UI behavior, page load, frontend errors | RUM | Traces (if backend-related) | | Endpoint latency, throughput, error rates | Metrics | Traces (for per-request detail) | | Service-to-service dependencies, request flow | Traces | Logs (for debug output) | | Specific error messages, stack traces | Logs | Traces (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.

---

Discovery Workflow

When the answer could reside in multiple pillars, run discovery in parallel to find the best source.

Step 1: Search Metrics

Check if a relevant metric exists:

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, load `references/promql-guidelines.md` + `references/metrics-querying.md` and continue.

Step 2: Search Log and Span Fields

Use semantic field search to find relevant DataPrime paths:

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

If you know a concrete value that should appear in the data but don't know which field holds it, use value search instead. It returns the matching field keys alongside sample values, which also lets you infer the field's type (string, numeric, enum, etc.):

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

**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 <name>`.

If matching fields are found:

• For **logs**: load `references/dataprime-reference.md` + `references/logs-querying.md`
• For **spans**: load `references/dataprime-reference.md` + `references/spans-querying.md`

Step 3: Search the Codebase

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.

Step 4: Choose and Query

Based on discovery results, pick the pillar with the clearest signal, load its reference files (see [Loading References](#loading-references)), then query.

---

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.

---

CLI Commands Reference

| Command | Purpose | When to Use | |---|---|---| | `cx schema` | Output the full command tree as JSON | Discover all available commands and their flags | | `cx metrics search --name <pattern>` | Find metrics by name | First step for metrics discovery | | `cx metrics search --description <text>` | Semantic metric search | When you know what you want but not the name | | `cx search-fields "<text>"