SigNoz MCP
Query a live SigNoz instance over MCP (server already configured). ~41
signoz_* tools across telemetry (metrics/traces/logs), alerts, dashboards,
saved views, notification channels, and docs -- plus 4 built-in workflow prompts.
This skill is for reading and operating a running SigNoz. For designing SLOs,
alert thresholds, or dashboards from first principles use observability-designer.
For reading/acking incidents use the regen agent -- SigNoz is where you land
after extracting an incident's correlation keys.
Two rules that make queries fast (and correct)
1. Filter by resource attributes first. Resource attributes (service.name,
k8s.namespace.name, host.name) are indexed and dramatically speed up backend
queries. If you don't already have one:
signoz_get_field_keys(signal="logs", fieldContext="resource") # discover keys
signoz_get_field_values(signal="logs", name="service.name") # discover values
Then always scope queries with a service (or filter: service.name = '...').
Do not run broad, unfiltered log/trace scans.
2. Pick the operator to match intent AND data type.
| Intent |
Operator |
Example |
| Field exists |
EXISTS |
trace_id EXISTS |
| Field absent |
NOT EXISTS |
k8s.pod.name NOT EXISTS |
| Exact match |
= |
service.name = 'frontend' |
| Exclude (field must exist) |
EXISTS AND != |
service.name EXISTS AND service.name != 'redis' |
| One of several |
IN |
severity_text IN ('ERROR','WARN','FATAL') |
| Substring |
LIKE / ILIKE |
body ILIKE '%timeout%' |
| Containment |
CONTAINS |
body CONTAINS 'timeout' |
| Regex |
REGEXP |
name REGEXP '^grpc\.' |
Safe operators by type: bool = != EXISTS; int64 = != > >= < <= IN EXISTS;
string all of the above plus LIKE ILIKE CONTAINS REGEXP IN NOT IN.
Caveat: negative operators (!=, NOT LIKE, NOT IN) only match rows where
the field is present -- rows missing the field are silently dropped. To include
them, OR in a NOT EXISTS, or gate with EXISTS AND != when you mean "present
but not X".
Signal ambiguity: if it isn't clear whether the answer lives in metrics,
traces, or logs, ask before querying.
The mini-axol / Riddler deployment
The configured signoz MCP points at a self-hosted SigNoz on the tailnet:
signoz_url = http://mini-axol.tail9b2ce8.ts.net:3301 -- Tailscale must be up
(a connection failure is almost always a down tailnet, not a SigNoz outage).- Telemetry source is Riddler OTel; custom metrics are named
riddler_*.
- Primary filter is always
service.name. Start any investigation with
signoz_list_services to confirm reachability and the live service names.
Tool map (~41 tools)
Full argument detail in tools-reference.md; workflows in
usage-patterns.md.
| Group |
Tools |
| Discovery |
signoz_list_services, signoz_get_service_top_operations, signoz_list_metrics, signoz_get_top_metrics, signoz_get_field_keys, signoz_get_field_values |
| Metrics |
signoz_query_metrics, signoz_execute_builder_query, signoz_check_metric_cardinality, signoz_check_metric_usage |
| Logs |
signoz_search_logs, signoz_aggregate_logs |
| Traces |
signoz_search_traces, signoz_aggregate_traces, signoz_get_trace_details |
| Alerts |
signoz_list_alerts, signoz_list_alert_rules, signoz_get_alert, signoz_get_alert_history, signoz_create_alert, signoz_update_alert, signoz_delete_alert |
| Dashboards |
signoz_list_dashboards, signoz_get_dashboard, signoz_create_dashboard, signoz_update_dashboard, signoz_delete_dashboard, signoz_import_dashboard, signoz_list_dashboard_templates |
| Saved views |
signoz_list_views, signoz_get_view, signoz_create_view, signoz_update_view, signoz_delete_view |
| Notification channels |
signoz_list_notification_channels, signoz_get_notification_channel, signoz_create_notification_channel, signoz_update_notification_channel, signoz_delete_notification_channel |
| Docs |
signoz_search_docs, signoz_fetch_doc |
Built-in MCP prompts
The server ships 4 slash-command prompts (they surface as /signoz:<name>).
They are ready-made workflows, not clutter -- reach for them first when they fit:
| Prompt |
Args |
Runs |
/signoz:debug_service_errors |
service, timeRange |
error logs + error-trace aggregate + top operations |
/signoz:latency_analysis |
service, timeRange |
p99 latency metrics + trace-duration aggregate + slow ops |
/signoz:compare_metrics |
metricName, period1, period2 |
one metric across two windows to spot regressions |
/signoz:incident_triage |
alertId |
alert details + history + related logs & traces |
These prompts cannot be individually hidden in Claude Code (no supported toggle);
see usage-patterns.md for the
optional build-time opt-out and why keeping them is recommended.
What You Get
- Reference documentation for all ~41 SigNoz MCP tools grouped by signal and function.
- The resource-attribute-first rule and a filter-operator cheat sheet that prevent
slow scans and silently-dropped rows.
- Concrete workflows including the regen incident -> OTel correlation loop against
the mini-axol/Riddler deployment.
See also
regen -- reads Fluidify Regen incidents and emits the service.name + labels +
time window to feed into these tools (the incident side of the loop; see
usage-patterns.md)observability-designer -- design SLOs, alert rules, and dashboards conceptuallyethskills -- Ethereum tooling context for the Riddler stack being observed
1---2name: signoz3description: SigNoz MCP tool reference for querying a live observability backend (OTel metrics, traces, logs) plus alerts, dashboards, saved views, and notification channels. Covers all ~41 signoz_* tools, the 4 built-in MCP prompts, the resource-attribute-first filtering rule, and the regen incident -> SigNoz correlation loop on the mini-axol/Riddler deployment. TRIGGER when: user asks to query SigNoz, inspect a service's errors/latency, search OTel logs or traces, read/aggregate metrics, triage an alert, or uses signoz_* MCP tools; or pivots from a regen incident into telemetry. DO NOT TRIGGER when: user wants to DESIGN SLOs/alerts/dashboards conceptually (use observability-designer skill), or READ/ack/resolve incidents in Regen itself (use the regen agent/skill -- signoz is the telemetry side of that loop).4---56# SigNoz MCP78Query a **live** SigNoz instance over MCP (server already configured). ~419`signoz_*` tools across telemetry (metrics/traces/logs), alerts, dashboards,10saved views, notification channels, and docs -- plus 4 built-in workflow prompts.1112This skill is for **reading and operating a running SigNoz**. For designing SLOs,13alert thresholds, or dashboards from first principles use `observability-designer`.14For reading/acking incidents use the `regen` agent -- SigNoz is where you land15*after* extracting an incident's correlation keys.1617## Two rules that make queries fast (and correct)1819**1. Filter by resource attributes first.** Resource attributes (`service.name`,20`k8s.namespace.name`, `host.name`) are indexed and dramatically speed up backend21queries. If you don't already have one:2223```24signoz_get_field_keys(signal="logs", fieldContext="resource") # discover keys25signoz_get_field_values(signal="logs", name="service.name") # discover values26```2728Then always scope queries with a `service` (or `filter: service.name = '...'`).29Do not run broad, unfiltered log/trace scans.3031**2. Pick the operator to match intent AND data type.**3233| Intent | Operator | Example |34| --- | --- | --- |35| Field exists | `EXISTS` | `trace_id EXISTS` |36| Field absent | `NOT EXISTS` | `k8s.pod.name NOT EXISTS` |37| Exact match | `=` | `service.name = 'frontend'` |38| Exclude (field must exist) | `EXISTS AND !=` | `service.name EXISTS AND service.name != 'redis'` |39| One of several | `IN` | `severity_text IN ('ERROR','WARN','FATAL')` |40| Substring | `LIKE` / `ILIKE` | `body ILIKE '%timeout%'` |41| Containment | `CONTAINS` | `body CONTAINS 'timeout'` |42| Regex | `REGEXP` | `name REGEXP '^grpc\.'` |4344Safe operators by type: **bool** `= != EXISTS`; **int64** `= != > >= < <= IN EXISTS`;45**string** all of the above plus `LIKE ILIKE CONTAINS REGEXP IN NOT IN`.4647**Caveat:** negative operators (`!=`, `NOT LIKE`, `NOT IN`) only match rows where48the field is present -- rows missing the field are silently dropped. To include49them, OR in a `NOT EXISTS`, or gate with `EXISTS AND !=` when you mean "present50but not X".5152**Signal ambiguity:** if it isn't clear whether the answer lives in metrics,53traces, or logs, ask before querying.5455## The mini-axol / Riddler deployment5657The configured `signoz` MCP points at a self-hosted SigNoz on the tailnet:5859- `signoz_url` = `http://mini-axol.tail9b2ce8.ts.net:3301` -- **Tailscale must be up**60 (a connection failure is almost always a down tailnet, not a SigNoz outage).61- Telemetry source is **Riddler** OTel; custom metrics are named `riddler_*`.62- Primary filter is always `service.name`. Start any investigation with63 `signoz_list_services` to confirm reachability and the live service names.6465## Tool map (~41 tools)6667Full argument detail in [tools-reference.md](tools-reference.md); workflows in68[usage-patterns.md](usage-patterns.md).6970| Group | Tools |71| --- | --- |72| Discovery | `signoz_list_services`, `signoz_get_service_top_operations`, `signoz_list_metrics`, `signoz_get_top_metrics`, `signoz_get_field_keys`, `signoz_get_field_values` |73| Metrics | `signoz_query_metrics`, `signoz_execute_builder_query`, `signoz_check_metric_cardinality`, `signoz_check_metric_usage` |74| Logs | `signoz_search_logs`, `signoz_aggregate_logs` |75| Traces | `signoz_search_traces`, `signoz_aggregate_traces`, `signoz_get_trace_details` |76| Alerts | `signoz_list_alerts`, `signoz_list_alert_rules`, `signoz_get_alert`, `signoz_get_alert_history`, `signoz_create_alert`, `signoz_update_alert`, `signoz_delete_alert` |77| Dashboards | `signoz_list_dashboards`, `signoz_get_dashboard`, `signoz_create_dashboard`, `signoz_update_dashboard`, `signoz_delete_dashboard`, `signoz_import_dashboard`, `signoz_list_dashboard_templates` |78| Saved views | `signoz_list_views`, `signoz_get_view`, `signoz_create_view`, `signoz_update_view`, `signoz_delete_view` |79| Notification channels | `signoz_list_notification_channels`, `signoz_get_notification_channel`, `signoz_create_notification_channel`, `signoz_update_notification_channel`, `signoz_delete_notification_channel` |80| Docs | `signoz_search_docs`, `signoz_fetch_doc` |8182## Built-in MCP prompts8384The server ships 4 slash-command prompts (they surface as `/signoz:<name>`).85They are ready-made workflows, not clutter -- reach for them first when they fit:8687| Prompt | Args | Runs |88| --- | --- | --- |89| `/signoz:debug_service_errors` | `service`, `timeRange` | error logs + error-trace aggregate + top operations |90| `/signoz:latency_analysis` | `service`, `timeRange` | p99 latency metrics + trace-duration aggregate + slow ops |91| `/signoz:compare_metrics` | `metricName`, `period1`, `period2` | one metric across two windows to spot regressions |92| `/signoz:incident_triage` | `alertId` | alert details + history + related logs & traces |9394These prompts cannot be individually hidden in Claude Code (no supported toggle);95see [usage-patterns.md](usage-patterns.md#opt-out-hiding-the-prompts) for the96optional build-time opt-out and why keeping them is recommended.9798## What You Get99100- Reference documentation for all ~41 SigNoz MCP tools grouped by signal and function.101- The resource-attribute-first rule and a filter-operator cheat sheet that prevent102 slow scans and silently-dropped rows.103- Concrete workflows including the regen incident -> OTel correlation loop against104 the mini-axol/Riddler deployment.105106## See also107108- `regen` -- reads Fluidify Regen incidents and emits the `service.name` + labels +109 time window to feed into these tools (the incident side of the loop; see110 [usage-patterns.md](usage-patterns.md#regen-incident---signoz-correlation-loop))111- `observability-designer` -- design SLOs, alert rules, and dashboards conceptually112- `ethskills` -- Ethereum tooling context for the Riddler stack being observed
DROOdotFOO