Add OpenTelemetry instrumentation for Model Context Protocol (MCP) #3822
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
lukeina2z
changed the title
lukeina2z
force-pushed
the
mcp-prfoo
branch
4 times, most recently
from
0775d46 to
ba43d31
Compare
lukeina2z
changed the title
lukeina2z
force-pushed
the
mcp-prfoo
branch
3 times, most recently
from
bba04fc to
36a82f4
Compare
lukeina2z
force-pushed
the
mcp-prfoo
branch
3 times, most recently
from
4bcb845 to
10f1f8f
Compare
This commit introduces a new instrumentation package for the Model Context Protocol (MCP), enabling automatic distributed tracing for MCP client-server interactions. Key Features: - Automatic instrumentation of MCP client sessions and server handlers - Support for both stdio and HTTP/SSE transports - W3C trace context propagation across MCP messages - Comprehensive span attributes following semantic conventions - Tool calls, resource reads, prompt handling, and session lifecycle tracing Package Structure: - Core instrumentation: McpInstrumentor with automatic wrapping - Semantic attributes: MCP-specific span attributes and conventions - Test coverage: Unit tests for instrumentor, server, and session wrappers - Examples: stdio (simple-client-server) and HTTP/SSE transport demos - Documentation: README, CHANGELOG, and example-specific guides Technical Implementation: - Wraps mcp.ClientSession and mcp.server.Server classes - Injects trace context into message metadata - Extracts and propagates context across transport boundaries - Records exceptions and sets span status appropriately - Requires Python >=3.10 (MCP SDK requirement) CI/CD Updates: - Added MCP instrumentation to test workflows - Updated lint configuration for new package - Disabled pypy3 tests (Python 3.10+ requirement) - Integrated into eachdist.ini and bootstrap generation Examples: - simple-client-server: stdio transport with tool calls and resources - http-transport: HTTP/SSE transport with distributed tracing - Both include Jaeger trace visualizations and setup instructions"
xrmx
reviewed
Oct 15, 2025
| "Intended Audience :: Developers", | ||
| "License :: OSI Approved :: Apache Software License", | ||
| "Programming Language :: Python", | ||
| "Programming Language :: Python :: 3", |
There was a problem hiding this comment.
We drop python version 6 months after they have been EOL'ed. So Python 3.9 should be there.
xrmx
reviewed
Oct 15, 2025
mxiamxia
reviewed
Oct 15, 2025
|
|
||
| from wrapt import register_post_import_hook # type: ignore[import-untyped] | ||
|
|
||
| from opentelemetry import trace |
There was a problem hiding this comment.
Should the name of this file be instrumentor.py to stay consistent with the naming pattern and sementically better?
mxiamxia
reviewed
Oct 15, 2025
Comment on lines
+46
to
+47
| _CLIENT_SPAN_NAME = "mcp.client" | ||
| _SERVER_SPAN_NAME = "mcp.server" |
There was a problem hiding this comment.
are these defined by MCP semconv? shoud these be moved to attributes.py as well?
mxiamxia
reviewed
Oct 15, 2025
| tracer_provider: Optional tracer provider to use | ||
| propagators: Optional propagators for context injection/extraction | ||
| """ | ||
| _LOG.info("Initializing MCP instrumentor xyxyxy") |
There was a problem hiding this comment.
is this info logging needed? if yes, need to fix logging message content
mxiamxia
reviewed
Oct 15, 2025
|
|
||
| def instrumentation_dependencies(self) -> Collection[str]: | ||
| """Return the dependencies required for this instrumentation.""" | ||
| return ("mcp >= 1.8.1",) |
There was a problem hiding this comment.
any reason why the support starts from this version
mxiamxia
reviewed
Oct 15, 2025
Comment on lines
+167
to
+169
| message_json = message.model_dump( | ||
| by_alias=True, mode="json", exclude_none=True | ||
| ) |
There was a problem hiding this comment.
is a try/catch error handling required to not interupt the original request?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
8 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This commit introduces a new instrumentation package for the Model Context
Protocol (MCP), enabling automatic distributed tracing for MCP client-server
interactions.
Key Features:
Package Structure:
Technical Implementation:
CI/CD Updates:
Examples:
Type of change
Please delete options that are not relevant.
How Has This Been Tested?
Unit tests added.
tox -e py310-test-instrumentation-mcp-oldest
tox -e py310-test-instrumentation-mcp-latest
tox -e py311-test-instrumentation-mcp-oldest
tox -e py311-test-instrumentation-mcp-latest
tox -e py312-test-instrumentation-mcp-oldest
tox -e py312-test-instrumentation-mcp-latest
tox -e py313-test-instrumentation-mcp-oldest
tox -e py313-test-instrumentation-mcp-latest
tox -e pypy3-test-instrumentation-mcp-oldest
tox -e pypy3-test-instrumentation-mcp-latest
tox -e lint-instrumentation-mcp
tox -e spellcheck
tox -e ruff
End to end testing with two applications in the examples folder.
Does This PR Require a Core Repo Change?
Checklist:
See contributing.md for styleguide, changelog guidelines, and more.