Observability

This document covers the observability system in MCP Adapter, which tracks events, metrics, and performance data for MCP requests and component operations. The system uses a metadata-driven architecture where observability data flows from handlers through the transport layer for centralized recording.

For error handling and logging, see Error Handling. For details on specific handlers that generate observability metadata, see Request Router.

System Overview

The observability system provides:

• Event tracking: Records MCP requests, component registrations, and execution lifecycle events
• Performance monitoring: Captures request duration and timing data
• Status tracking: Differentiates success and error cases using status tags
• Context enrichment: Automatically includes server ID, transport type, component details, and error categorization

The system was refactored in v0.3.0 to use a metadata-driven architecture. Handlers return _metadata in their responses, which the RequestRouter extracts and records centrally. This eliminates duplicate observability calls throughout the codebase.

Sources: docs/migration/v0.3.0.md1-435 includes/Transport/Infrastructure/RequestRouter.php1-245

Architecture

Metadata-Driven Flow

Diagram: Metadata-Driven Observability Flow

The RequestRouter acts as the central observability orchestrator:

1. Handler returns metadata: Handlers append _metadata to their response containing component-specific context
2. Router extracts metadata: The router extracts _metadata from the response at includes/Transport/Infrastructure/RequestRouter.php86-88
3. Router merges tags: Common request context (method, transport, server_id) is merged with handler metadata at includes/Transport/Infrastructure/RequestRouter.php96
4. Router records event: A single record_event() call captures the complete picture at includes/Transport/Infrastructure/RequestRouter.php102 or includes/Transport/Infrastructure/RequestRouter.php109
5. Metadata stripped: The _metadata key is removed before returning to the client at includes/Transport/Infrastructure/RequestRouter.php88

Sources: includes/Transport/Infrastructure/RequestRouter.php51-130 docs/migration/v0.3.0.md67-109

Interface and Implementation

Diagram: Observability Interface and Implementations

The observability system uses:

• McpObservabilityHandlerInterface: Defines the contract with a single record_event() method
• NullMcpObservabilityHandler: No-op implementation that discards all events (default for testing)
• ErrorLogMcpObservabilityHandler: Writes events to PHP error log with formatted output
• Custom implementations: Can send to external monitoring systems (Datadog, New Relic, etc.)

Handlers are instantiated as instance objects (not static classes as in v0.2.x) and passed through the McpTransportContext.

Sources: docs/migration/v0.3.0.md188-233 includes/Transport/Infrastructure/RequestRouter.php20-38

Event Structure

Unified Event Names with Status Tags

All events use consistent base names with a status tag to differentiate success and error cases:

Event Name	Status Values	Description
mcp.request	success, error	MCP method invocation (tools/call, resources/read, etc.)
mcp.component.registration	success, failed	Component registration (tools, resources, prompts)

This pattern replaced the separate event names used in v0.2.x (mcp.request.success vs mcp.request.error).

Sources: docs/migration/v0.3.0.md13-66

Request Event Tags

When mcp.request events are recorded, the following tags are included:

Common tags (added by RequestRouter at includes/Transport/Infrastructure/RequestRouter.php56-63):

Handler metadata (returned by handlers in _metadata):

Status-specific tags:

For status: success:

For status: error:

Sources: includes/Transport/Infrastructure/RequestRouter.php56-109 docs/migration/v0.3.0.md135-161

Duration Tracking

Request duration is automatically calculated and included:

The duration appears in logs as:

[MCP Observability] EVENT mcp.request 45.23ms [status=success,method=tools/call,...]

Sources: includes/Transport/Infrastructure/RequestRouter.php53 includes/Transport/Infrastructure/RequestRouter.php84 includes/Transport/Infrastructure/RequestRouter.php102

Request Flow

Success Path

Diagram: Successful Request Observability Flow

The success path at includes/Transport/Infrastructure/RequestRouter.php80-111:

1. Request arrives, start time recorded (line 53)
2. Common tags prepared with method, transport, server_id (lines 56-63)
3. Handler executes and returns result with _metadata
4. RequestRouter extracts _metadata (line 86-88)
5. Tags merged and status set to success (lines 96, 108)
6. Event recorded with duration (line 109)
7. _metadata stripped from response (line 88)

Sources: includes/Transport/Infrastructure/RequestRouter.php51-111

Error Path

Diagram: Error Request Observability Flow

The error path at includes/Transport/Infrastructure/RequestRouter.php99-105:

1. Handler returns error response with _metadata
2. RequestRouter checks for error field (line 99)
3. Status set to error, error_code extracted (lines 100-101)
4. Event recorded with error context (line 102)
5. Error response returned to client

For exceptions, a similar flow occurs at includes/Transport/Infrastructure/RequestRouter.php112-129 with additional exception categorization.

Sources: includes/Transport/Infrastructure/RequestRouter.php99-129

Exception Categorization

The RequestRouter categorizes exceptions to provide better error tracking:

Categories are included in the event tags at includes/Transport/Infrastructure/RequestRouter.php122:

This allows monitoring systems to aggregate errors by category (e.g., "all validation errors" vs "all execution errors").

Sources: includes/Transport/Infrastructure/RequestRouter.php193-203 includes/Transport/Infrastructure/RequestRouter.php117-124

Parameter Sanitization

To prevent logging sensitive data, request parameters are sanitized before inclusion in events:

This approach logs metadata about arguments (count, keys) without logging actual values that may contain sensitive data.

Sources: includes/Transport/Infrastructure/RequestRouter.php213-244

Configuration

Handler Selection

Observability handlers are specified when creating an MCP server:

The server instantiates the handler and passes it through the McpTransportContext to all components.

Sources: docs/guides/transport-permissions.md10-24 tests/Unit/Transport/Infrastructure/RequestRouterTest.php44-56

Custom Observability Handlers

Creating a Custom Handler

Implement the McpObservabilityHandlerInterface:

Using Custom Handlers

Pass the custom handler class name to create_server():

Sources: docs/migration/v0.3.0.md229-234

Testing

Test Fixtures

The test suite uses DummyObservabilityHandler to capture events for assertions:

Test Assertions

Tests verify observability events are recorded:

Sources: tests/Unit/Transport/Infrastructure/RequestRouterTest.php260-291 tests/Unit/Transport/Infrastructure/HttpRequestHandlerTest.php19-20

Migration from v0.2.x

Key Changes

The v0.3.0 release introduced breaking changes to the observability system:

Aspect	v0.2.x	v0.3.0
Method type	Static methods	Instance methods
Event names	Separate success/error names	Unified name + status tag
Recording location	Handler-level calls	Centralized in RequestRouter
Timing method	record_timing() separate	record_event() with duration parameter
Data flow	Direct calls	Metadata returned from handlers

Migration Steps

1. Update event name queries

If using external monitoring systems:

2. Update custom handlers to instance methods

3. Return metadata instead of direct calls

The RequestRouter automatically extracts, records, and strips the _metadata field.

Sources: docs/migration/v0.3.0.md7-134 docs/migration/v0.3.0.md272-297

Event Reference

mcp.request

Recorded for all MCP method invocations.

Tags:

Tag	Type	Description	Added By
status	string	success or error	RequestRouter
method	string	MCP method name (e.g., tools/call)	RequestRouter
transport	string	Transport type (e.g., HTTP, STDIO)	RequestRouter
server_id	string	Server identifier	RequestRouter
request_id	mixed	JSON-RPC request ID	RequestRouter
session_id	string|null	MCP session ID	RequestRouter
params	array	Sanitized parameters	RequestRouter
component_type	string	tool, resource, or prompt	Handler metadata
tool_name	string	Tool name (for tool calls)	Handler metadata
ability_name	string	Underlying ability name	Handler metadata
failure_reason	string	Specific failure type	Handler metadata
error_code	int	JSON-RPC error code	RequestRouter (errors)
error_type	string	Exception class name	RequestRouter (exceptions)
error_category	string	Error category	RequestRouter (exceptions)

Duration: Request duration in milliseconds

mcp.component.registration

Recorded when tools, resources, or prompts are registered during server initialization.

Tags:

Tag	Type	Description
status	string	success or failed
component_type	string	tool, resource, or prompt
component_name	string	Component identifier
server_id	string	Server identifier
error_type	string	Exception type (for failures)

Sources: docs/migration/v0.3.0.md135-161 includes/Transport/Infrastructure/RequestRouter.php56-109