> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alpic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Metrics export

> Push your MCP server's request metrics to your own observability backend over OTLP.

Alpic can push per-tool request metrics from your MCP server to any OpenTelemetry-compatible backend over OTLP/HTTP: Datadog, Grafana Cloud, or your own collector. There is nothing to install and no change to your code or deploys. Configure a destination once and data points start arriving on the next minute.

<Note>
  Metrics export is available on **paid plans**. Destinations are configured per environment and per signal, so metrics
  can go to Prometheus while logs go elsewhere, and staging and production can point at different backends.
</Note>

## Set up a destination

<Steps>
  <Step title="Open the Telemetry settings">
    In your project **Settings**, open the **Telemetry** section, pick the environment to configure, and add a destination under **Metrics**.
  </Step>

  <Step title="Enter the destination endpoint">
    Paste the **full** metrics URL from your vendor, signal path included, for example `https://otlp.example.com/v1/metrics`.

    We push to this URL exactly as you enter it and **never append a path**. `/v1/metrics` is only the OTLP default: some vendors serve a different path, or a different host per signal, so always copy the URL your vendor documents for metrics.

    You can add more than one destination with **Add destination**, and the same metrics go to all of them. Each destination is configured, tested and stopped on its own.
  </Step>

  <Step title="Pick the protocol">
    `HTTP/protobuf` is the OTLP default. Switch to `HTTP/JSON` only if your backend asks for it.
  </Step>

  <Step title="Add the authentication header">
    Authentication is a header you copy from your vendor, such as `Authorization` or `DD-API-KEY`, with your API key as
    the value. Mark it **secret** so it is stored write-only and never shown again.
  </Step>

  <Step title="Save and send a test metric">
    Save the destination, then click **Send a test metric**. Alpic pushes one synthetic data point (`alpic.connection.check`, marked `alpic.synthetic`) through the exact same path your real metrics take and shows you the backend's answer. The verification outcomes are the same as for [logs export](/telemetry/logs-export#verify-the-destination).
  </Step>
</Steps>

## Common vendors

Always copy the endpoint from your vendor's OTLP documentation, since regions and paths vary by account. Typical shapes:

| Vendor        | Metrics endpoint shape                                      | Authentication header                          |
| ------------- | ----------------------------------------------------------- | ---------------------------------------------- |
| Datadog       | see Datadog's OTLP intake docs for your site                | `DD-API-KEY: <API key>`                        |
| Grafana Cloud | `https://otlp-gateway-<region>.grafana.net/otlp/v1/metrics` | `Authorization: Basic <base64 instance:token>` |

Datadog's OTLP metrics intake accepts **delta temporality only**, which is exactly what Alpic sends, so no temporality configuration is needed on either side.

For Grafana Cloud, the metrics land in the Prometheus data source of your stack; query them by name with the usual OTLP-to-Prometheus renaming (dots become underscores, the unit is appended — for example `alpic_mcp_server_requests_request_total`).

## What gets exported

Every settled MCP request in the environment is aggregated into five metric families, one data point per minute per dimension set:

| Metric                          | What it measures                                       | Dimensions                                                      |
| ------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------- |
| `alpic.mcp.server.requests`     | Settled requests (counter)                             | `mcp.method.name`, `gen_ai.tool.name`                           |
| `mcp.server.operation.duration` | Request duration in seconds (histogram, fixed buckets) | `mcp.method.name`, `gen_ai.tool.name`                           |
| `alpic.mcp.server.errors`       | Failed requests (counter)                              | `error.type`, `rpc.jsonrpc.error_code` (`"none"` when codeless) |
| `alpic.mcp.server.token.usage`  | Output tokens (counter)                                | `gen_ai.token.type` (`output`), `gen_ai.tool.name`              |
| `alpic.mcp.server.sessions`     | Distinct sessions within the minute (see below)        | `alpic.mcp.client.name`                                         |

`gen_ai.tool.name` is present on tool calls only. The resource's `service.name` is the environment id, so one dashboard can filter across environments. Dimensions are deliberately bounded: user, session and conversation identifiers never become metric dimensions.

The duration histogram ships explicit bucket boundaries (10 ms up to 2 minutes), so your backend can compute p50/p95/p99 directly — in Datadog through distribution queries, in Grafana with `histogram_quantile`.

`error.type` is one of `mcp_error` (the request failed with a JSON-RPC error), `tool_error` (the tool returned `isError`), or `timeout`. Only `mcp_error` carries a JSON-RPC code; tool errors and timeouts always land in the explicit `"none"` code bucket.

## Resolution and delay

Metrics are aggregated at **one-minute resolution** and pushed with **delta temporality**: each data point carries the value for its own minute, stamped with that minute's start and end.

A minute is exported roughly one minute after it closes, once its last events have settled. End to end, an event therefore reaches your backend between roughly **1 and 2 minutes** after it happened, depending on where it fell within its minute.

<Warning>
  `alpic.mcp.server.sessions` means **distinct sessions within one minute**. Two minutes can count the same session
  twice, so summing the series over an hour over-counts. Roll it up with **max or avg**, never sum. It is exported as a
  non-monotonic sum so most backends already treat it as a level rather than a rate.
</Warning>

## Plans and downgrades

Metrics export requires a paid plan. If your team downgrades, export stops but your configuration is kept, and upgrading resumes export with nothing to re-enter.

To stop exporting on any plan, delete the destination.

## When a destination stops being retried

If a destination keeps failing, whether from a revoked credential, a decommissioned endpoint, or a vendor outage that does not end, Alpic stops retrying it and says so in the Telemetry section, along with the reason it stopped. A rejected credential or a wrong path stops it immediately, since neither recovers by being retried. A temporary failure has to persist for a long run of minutes first.

Its siblings keep exporting. To start it again, fix the endpoint or the headers and save, or click **Send a test metric**: either one clears the state once it succeeds. Minutes that passed while a destination was stopped are not replayed to it.