--- title: "Observability (metrics, tracing, and logs) | Grafana documentation" description: "Expose Prometheus metrics and OpenTelemetry tracing and logs from the Grafana MCP server." --- # Observability (metrics, tracing, and logs) The MCP server can expose **Prometheus metrics** and supports [**OpenTelemetry**](https://opentelemetry.io/) distributed tracing and log export, following the [OTel MCP semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/). Metrics require the **SSE** or **streamable-http** transport. Tracing and log export use standard `OTEL_*` environment variables and work with any transport, independently of `--metrics`. **Note**: mcp-grafana currently only supports the OTLP/gRPC transport for both traces and logs. `OTEL_EXPORTER_OTLP_PROTOCOL` (and its `_TRACES_PROTOCOL` / `_LOGS_PROTOCOL` variants) are not honored — gRPC is used regardless. ## What you’ll achieve You can scrape MCP operation metrics (HTTP transports only) and export traces and logs to Tempo, Loki, or Grafana Cloud under any transport, including stdio. ## Before you begin - The server running with **SSE** or **streamable-http** (metrics are not available with stdio). ## Enable Prometheus metrics When using SSE or streamable HTTP transports, enable Prometheus metrics with `--metrics`: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash # Metrics on the main server at /metrics ./mcp-grafana -t streamable-http --metrics ``` Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash # Metrics on a separate listen address ./mcp-grafana -t streamable-http --metrics --metrics-address :9090 ``` **Available metrics:** Expand table | Metric | Type | Description | |-----------------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------| | `mcp_server_operation_duration_seconds` | Histogram | MCP operation duration (labels: `mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`) | | `mcp_server_session_duration_seconds` | Histogram | MCP client session duration (labels: `network_transport`, `mcp_protocol_version`) | | `http_server_request_duration_seconds` | Histogram | HTTP server request duration (from otelhttp) | **Note**: Metrics are only available when using SSE or streamable HTTP transports. They are **not** available with stdio transport. ## Enable OpenTelemetry tracing When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, the server exports traces via OTLP/gRPC. Local example: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash # Send traces to a local Tempo instance OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \ OTEL_EXPORTER_OTLP_INSECURE=true \ ./mcp-grafana -t streamable-http ``` Grafana Cloud example: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash # Send traces to Grafana Cloud with authentication OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \ OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \ ./mcp-grafana -t streamable-http ``` Tool call spans follow naming like `tools/call ` and include attributes such as `gen_ai.tool.name`, `mcp.method.name`, and `mcp.session.id`. The server supports W3C trace context propagation from the `_meta` field of tool call requests. ## Enable OpenTelemetry logs When `OTEL_EXPORTER_OTLP_ENDPOINT` (or the signal-specific `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`) is set — the same trigger as tracing — the server also exports structured logs via OTLP/gRPC in addition to the existing plain-text stderr output. Logs carry `trace_id` and `span_id` from the active span so they correlate with exported traces. Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash # Send logs and traces to a local OTel collector OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \ OTEL_EXPORTER_OTLP_INSECURE=true \ ./mcp-grafana -t streamable-http ``` Stderr logging continues unchanged; operators can pipe stderr to `/dev/null` if they only want logs going to the OTel collector. Logs can be sent directly to any managed backend that accepts OTLP/gRPC — for example, Grafana Cloud — by pointing `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` (or the generic `OTEL_EXPORTER_OTLP_ENDPOINT`) at the remote gRPC endpoint and supplying auth via `OTEL_EXPORTER_OTLP_LOGS_HEADERS` (or `OTEL_EXPORTER_OTLP_HEADERS`), mirroring the tracing example above. A local OTel collector is optional — useful for fan-out, batching, or multi-backend routing, but not required. The signal-specific variants `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`, `OTEL_EXPORTER_OTLP_LOGS_HEADERS`, `OTEL_EXPORTER_OTLP_LOGS_INSECURE`, `OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE`, `OTEL_EXPORTER_OTLP_LOGS_TIMEOUT`, and `OTEL_EXPORTER_OTLP_LOGS_COMPRESSION` are honored and override their generic `OTEL_EXPORTER_OTLP_*` counterparts — see the [OTel exporter spec](https://opentelemetry.io/docs/specs/otel/protocol/exporter/) for the full list and precedence rules. **Note**: If the configured collector is unreachable, log records are buffered in memory (default queue: 2048) and the oldest records are dropped once the queue fills. The process continues without blocking the service. Configure a local OTel collector if you need lossless buffering during outages. Logs are also exported under the stdio transport, which makes it easy to centralize logs from local `mcp-grafana` instances invoked by IDE clients. ## Run with Docker (metrics, tracing, and logs) Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash docker run --rm -p 8000:8000 \ -e GRAFANA_URL=http://localhost:3000 \ -e GRAFANA_SERVICE_ACCOUNT_TOKEN= \ -e OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317 \ -e OTEL_EXPORTER_OTLP_INSECURE=true \ grafana/mcp-grafana \ -t streamable-http --metrics ``` ## Next steps - [Build, test, and lint](../build-and-test/) - [Transports and addresses](../../configure/transports-and-addresses/) - [Command-line flags](../../configure/command-line-flags/)