跳到正文
DEV Community· Span Observer·· 16 小時前AI 評分64

如何用 OpenTelemetry 監測 MCP 智能體的工具呼叫、延遲與錯誤

How to monitor MCP agents with OpenTelemetry: tool call spans, attributes, latency and errors

AI 導讀

文章介紹如何以 OpenTelemetry 追蹤 MCP 智能體和伺服器的工具呼叫,並監測各工具的延遲與錯誤。內容涵蓋 span 命名、GenAI 語義慣例、跨 MCP 請求傳遞 trace context,以及按工具計算 p95 延遲和錯誤率;相關慣例仍處於 development 狀態。

正文

You need to monitor MCP agents with OpenTelemetry as soon as an AI assistant calls your tools in production. An agent that answers slowly, picks the wrong tool or chains ten calls where two would do raises no classic alert: the process is running, the port responds, and yet the experience degrades and the bill climbs.

The good news is that an MCP tool call is nothing more than a distributed operation: a client sends a request, a server processes it, possibly by calling other services. Distributed traces, which SRE teams already know well, apply directly, provided you choose the right span names and the right attributes.

This article shows how to trace an MCP server and agent, which attributes to track, and how to turn them into actionable latency and error indicators.

Why monitor MCP agents with OpenTelemetry?

In an MCP architecture (described in our guide to the Model Context Protocol), a single user question can trigger a cascade: a call to the model, the choice of a tool, a request to the MCP server, then calls from the server to a database, an API or an observability platform. Without traces, each link is a black box.

OpenTelemetry brings three things: a standard, vendor-neutral format; shared semantic conventions for naming generative AI operations; and context propagation, which links the agent, the MCP server and downstream services in a single trace. It is the same logic as the one described for end-to-end OpenTelemetry, applied to a new type of call.

What a tool call span should contain

A span describes an operation: a name, a type (kind), a start and an end, a status, attributes and possibly events. For MCP, the OpenTelemetry GenAI semantic conventions, still at « development » status, offer a precise vocabulary.

A low-cardinality name

The recommended name follows the form {MCP method} {target}, for example tools/call chercher_runbooks. It contains the tool name, never its arguments or an identifier, so that calls group cleanly in analysis views.

Useful attributes

  • mcp.method.name: the JSON-RPC method (tools/call, resources/read…);
  • gen_ai.operation.name = execute_tool and gen_ai.tool.name: these let you treat an MCP call like any other agent tool call;
  • mcp.protocol.version, mcp.session.id and jsonrpc.request.id for diagnosis;
  • mcp.resource.uri for resource reads;
  • error.type on failure.

Tool arguments and results also exist as optional (opt-in) attributes. They are invaluable for debugging, but may contain personal data or secrets: only enable them knowingly.

Context that crosses the protocol

HTTP trace context is not enough: a single HTTP request can carry several MCP messages, and stdio has no headers. The conventions therefore inject traceparent (and optionally baggage) into the params._meta field of each MCP request. The server extracts it and attaches its span to the client’s span.

In practice

Step 1 — Enable server spans

Good news if your server uses the official Python SDK version 2: it already emits a SERVER span for each message received, with the attributes above. It depends only on the OpenTelemetry API; as long as no SDK is installed, these spans cost almost nothing. To collect them, simply add the SDK and an OTLP exporter:

pip install opentelemetry-sdk opentelemetry-exporter-otlp

For other SDKs and frameworks, check their documentation to see whether instrumentation exists or whether you need to create these spans yourself.

Step 2 — Configure the export

Standard configuration uses environment variables. To send directly to Dynatrace, you need the environment’s OTLP endpoint and an API token allowed to ingest traces; check the exact URL and scope in the documentation:

export OTEL_SERVICE_NAME=runbooks-mcp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://YOUR-ENV.live.dynatrace.com/api/v2/otlp
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20<TOKEN>"

In the code, initialise the tracer provider at startup, before launching the server. Be careful with the stdio transport: never use a console exporter that would write to standard output, which is reserved for the protocol.

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

Step 3 — Trace the agent on the client side

On the agent side, wrap each reasoning turn in a parent span. Tool calls made inside it attach to it, and the SDK propagates the context to the server when both sides use it:

tracer = trace.get_tracer("agent-astreinte")

async def traiter_question(client, question: str):
    with tracer.start_as_current_span("invoke_agent agent-astreinte") as span:
        span.set_attribute("gen_ai.operation.name", "invoke_agent")
        resultat = await client.call_tool(
            "chercher_runbooks", {"mots_cles": question}
        )
        span.set_attribute("agent.outils_appeles", 1)
        return resultat

The agent.outils_appeles attribute is an example of a custom attribute: prefix your custom attributes so they are not confused with the official conventions.

Step 4 — Distinguish error types

A tool call can fail in two ways: an execution error returned to the model (the result carries an error flag and the model can retry) or a JSON-RPC protocol error. In both cases, the server span must switch to error status with error.type set. Test this deliberately with an invalid argument and check what arrives in your backend.

Step 5 — Build the indicators

Once the spans are in Grail, a single DQL query is enough to track latency and errors per tool. Field names depend on ingestion; adapt them to what you see in your traces:

fetch spans, from: now() - 24h
| filter gen_ai.operation.name == "execute_tool"
| summarize appels = count(),
            erreurs = countIf(isNotNull(error.type)),
            p95 = percentile(duration, 95),
            by: { gen_ai.tool.name }
| sort appels desc

From there, set simple objectives: 95th percentile latency per tool, error rate, average number of tool calls per question. A sudden rise in the last one often signals an agent going round in circles.

Best practices

  • Name spans by method and tool, never by argument or identifier.
  • Follow the GenAI and MCP conventions, and prefix custom attributes.
  • Keep capture of tool arguments and results disabled by default.
  • Propagate the trace context from the agent through to the services called by the server.
  • Never write telemetry to the standard output of a stdio server.
  • Cross-reference these traces with the audit logs described in securing an MCP server.

Frequently asked questions

Are the OpenTelemetry MCP conventions stable?

No, they are at « development » status and have been moved to a repository dedicated to the GenAI conventions. Attribute names may still change.

Should you instrument the client, the server, or both?

Ideally both: the client shows the agent’s path, the server shows the real cost of each tool. Context propagation links them.

Is my Python server traced without doing anything?

With the official SDK version 2, spans are created automatically; you still need to install an OpenTelemetry SDK and an exporter. See also our tutorial on building an MCP server in Python.

Conclusion

An MCP agent does not escape the rules of observability: every tool call deserves a span, with a stable name, standard attributes and a reliable status. By relying on the OpenTelemetry conventions and on the telemetry built into the Python SDK, you quickly get latency, errors and agent behaviour in the same views as the rest of production.

Further reading: OpenTelemetry series: Anatomy of an OTel span (Dynatrace blog).

span.observer is an independent community blog, not affiliated with Dynatrace LLC or the projects mentioned. Trademarks belong to their respective owners. Tools change quickly: check commands and options in their official documentation.


Originally published on span.observer. French version: https://span.observer/fr/observer-agents-mcp-opentelemetry/.

來源:DEV Community · dev.to