Skip to content

Query telemetry and manage dashboards from the MCP server and management API - #347

Merged
arseniycodes merged 2 commits into
mainfrom
ash/telemetry-mcp-tools
Oct 16, 2026
Merged

arseniycodes merged 2 commits into
mainfrom
ash/telemetry-mcp-tools

Conversation

@arseniycodes

@arseniycodes arseniycodes commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

The Superlog MCP server covered automations, runs, tag mode, models, and secrets. It could not read telemetry or touch dashboards. The old Superlog MCP had telemetry and dashboard tools, and people used them. This brings them back on the current server.

Every new operation is an MCP tool and a REST endpoint under /api/v1.

Telemetry (telemetry-operations.ts)

Tool REST Reads
query_logs POST /telemetry/logs/search Logs by service, level, body text, trace ID, resource and log attributes
query_traces POST /telemetry/traces/search Spans by service, name, OTel status, minimum duration, resource and span attributes
get_trace GET /telemetry/traces/{traceId} One trace's spans and logs
query_metrics POST /telemetry/metrics/search Recent points across gauge, sum, histogram, exponential histogram, summary
list_services GET /telemetry/services Services that sent any signal
  • They reuse the existing query functions in packages/core/src/telemetry/query.ts, which scope every read to the caller's workspace.
  • Each needs the telemetry capability and a telemetry store. Otherwise it returns 404 telemetry_unavailable.
  • Window: range (15m to 7d, default 1h) or since/until, at most 30 days.
  • Rows come back in camelCase like the rest of the API. The exception is flattened into exception, timestamps are UTC ISO, ClickHouse 64-bit integers become numbers, and the internal superlog.project_id tag is removed.
  • A ClickHouse timeout returns 503 telemetry_query_timeout with advice to narrow the query.

Dashboards (dashboard-operations.ts)

Tool REST Effect
list_dashboards GET /dashboards read
get_dashboard GET /dashboards/{dashboardId} read
create_dashboard POST /dashboards write
update_dashboard PATCH /dashboards/{dashboardId} destructive (replaces variables)
delete_dashboard DELETE /dashboards/{dashboardId} destructive
add_dashboard_widget POST /dashboards/{dashboardId}/widgets write
update_dashboard_widget PATCH /dashboards/{dashboardId}/widgets/{widgetId} destructive (replaces config)
update_dashboard_layout PATCH /dashboards/{dashboardId}/layout write
delete_dashboard_widget DELETE /dashboards/{dashboardId}/widgets/{widgetId} destructive
  • They use the same store functions (db/telemetry-dashboards.ts) and schemas (telemetry/dashboards.ts) as the Dashboards page, so the page shows MCP-made dashboards unchanged.
  • Like the page, they need the telemetry and dashboards capabilities and a telemetry store.
  • New and changed widget configs go through widgetConfigProblem for the widget's type, for example a metric chart without a metric. The page's own widget PATCH route skips this check.
  • A widget without a layout gets the standard size for its type.
  • Responses include the dashboard's url.

Other changes

The MCP server instructions, the OpenAPI document, the README, and the copy on the API keys, MCP, and OAuth consent pages mention telemetry and dashboards.

Testing

  • pnpm typecheck, pnpm lint, pnpm test pass.
  • telemetry-operations.test.ts and dashboard-operations.test.ts cover annotations, input mapping, row shaping, config checks, missing capabilities or store, not-found cases, timeouts, and window validation.
  • I ran every telemetry tool through the MCP route against a local ClickHouse 26.8.21.10 built from infra/telemetry/clickhouse-schema.sql, seeded with data for two workspaces. All tools returned the expected rows, and the other workspace's data did not appear.
  • I ran the dashboard tools through the MCP route against a migrated Postgres with real capability rows. Create, add three widget types, retitle, reject a bad config, change the layout, rename, remove a widget, list, get, and delete all worked. A second workspace got dashboard_not_found for get, delete, and add widget, and listed no dashboards.

Adds read-only telemetry operations to the shared management operations,
so each one is an MCP tool and a REST endpoint:

- query_logs: search logs by service, level, body text, trace, and
  resource or log attributes
- query_traces: search spans by service, name, status, duration, and
  resource or span attributes
- get_trace: one trace's spans and logs
- query_metrics: recent metric points across all metric kinds
- list_services: services that sent telemetry in a window

Each needs the telemetry capability and a telemetry store, and reads only
the caller's workspace. Windows default to the last hour and are at most
30 days. A ClickHouse timeout returns telemetry_query_timeout with advice
to narrow the query.
@arseniycodes

Copy link
Copy Markdown
Contributor Author

Hosted gitlink bump: superloglabs/responder#498

Adds dashboard operations over the existing dashboard store:
list_dashboards, get_dashboard, create_dashboard, update_dashboard,
delete_dashboard, add_dashboard_widget, update_dashboard_widget,
update_dashboard_layout, and delete_dashboard_widget.

They need the telemetry and dashboards capabilities and a telemetry
store, like the Dashboards page. Widget configs are checked against the
widget type as the editor checks them, and responses link to the
dashboard in Superlog.
@arseniycodes arseniycodes changed the title Query logs, traces, and metrics from the MCP server and management API Query telemetry and manage dashboards from the MCP server and management API Oct 16, 2026
@arseniycodes
arseniycodes merged commit 8d57ce2 into main Oct 16, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant