McpServer.Telemetry (HTTP MCP Server v0.8.0)

View Source

Telemetry events for MCP Server.

This module provides telemetry instrumentation for monitoring and observability of your MCP server. All events follow the pattern [:mcp_server, :category, :event].

Available Events

HTTP Request Lifecycle

  • [:mcp_server, :request, :start] - Emitted when an HTTP request is received
  • [:mcp_server, :request, :stop] - Emitted when an HTTP request completes successfully
  • [:mcp_server, :request, :exception] - Emitted when an HTTP request fails with an exception

Tool Operations

  • [:mcp_server, :tool, :call_start] - Emitted when a tool execution starts
  • [:mcp_server, :tool, :call_stop] - Emitted when a tool execution completes
  • [:mcp_server, :tool, :call_exception] - Emitted when a tool execution fails
  • [:mcp_server, :tool, :list] - Emitted when tools are listed

Prompt Operations

  • [:mcp_server, :prompt, :get_start] - Emitted when a prompt retrieval starts
  • [:mcp_server, :prompt, :get_stop] - Emitted when a prompt retrieval completes
  • [:mcp_server, :prompt, :get_exception] - Emitted when a prompt retrieval fails
  • [:mcp_server, :prompt, :list] - Emitted when prompts are listed

Resource Operations

  • [:mcp_server, :resource, :read_start] - Emitted when a resource read starts
  • [:mcp_server, :resource, :read_stop] - Emitted when a resource read completes
  • [:mcp_server, :resource, :read_exception] - Emitted when a resource read fails
  • [:mcp_server, :resource, :list] - Emitted when static resources are listed
  • [:mcp_server, :resource, :templates_list] - Emitted when resource templates are listed

Completion Operations

  • [:mcp_server, :completion, :start] - Emitted when a completion request starts
  • [:mcp_server, :completion, :stop] - Emitted when a completion request completes
  • [:mcp_server, :completion, :exception] - Emitted when a completion request fails

Session Lifecycle

  • [:mcp_server, :session, :init] - Emitted when a new session is initialized
  • [:mcp_server, :session, :initialized] - Emitted when a client sends initialized notification

Logging Configuration

  • [:mcp_server, :logging, :set_level] - Emitted when log level is changed

Validation & Errors

  • [:mcp_server, :validation, :error] - Emitted when argument validation fails
  • [:mcp_server, :json_rpc, :decode_error] - Emitted when JSON-RPC parsing fails

Usage Example

# Attach to telemetry events in your application
:telemetry.attach_many(
  "mcp-server-metrics",
  [
    [:mcp_server, :tool, :call_stop],
    [:mcp_server, :request, :stop]
  ],
  &MyApp.Metrics.handle_event/4,
  nil
)

# Handler function
defmodule MyApp.Metrics do
  def handle_event([:mcp_server, :tool, :call_stop], measurements, metadata, _config) do
    duration_ms = System.convert_time_unit(measurements.duration, :native, :millisecond)
    MyApp.StatsD.timing("mcp.tool.duration", duration_ms, tags: [tool: metadata.tool_name])
  end

  def handle_event([:mcp_server, :request, :stop], measurements, metadata, _config) do
    duration_ms = System.convert_time_unit(measurements.duration, :native, :millisecond)
    MyApp.StatsD.timing("mcp.request.duration", duration_ms, tags: [method: metadata.method])
  end
end

Measurements

Most :stop and :exception events include:

List events include:

  • :count - Number of items returned

Metadata

All events include relevant context such as:

  • :session_id - The session identifier
  • :method - The JSON-RPC method (for request events)
  • :tool_name / :prompt_name / :resource_name - The name of the item being operated on
  • :error - Error details (for exception events)

Summary

Functions

execute(event, measurements, metadata)

Emits a single telemetry event.

span(event_prefix, start_metadata, span_function)

Executes a function and emits telemetry events for start, stop, and exception.

Functions

execute(event, measurements, metadata)

@spec execute(event :: [atom()], measurements :: map(), metadata :: map()) :: :ok

Emits a single telemetry event.

Example

Telemetry.execute(
  [:mcp_server, :session, :init],
  %{system_time: System.system_time()},
  %{session_id: session_id, client_info: client_info}
)

span(event_prefix, start_metadata, span_function)

@spec span(
  event_prefix :: [atom()],
  start_metadata :: map(),
  span_function :: (-> {result, stop_metadata :: map()})
) :: result
when result: any()

Executes a function and emits telemetry events for start, stop, and exception.

This is the recommended way to instrument operations that can fail.

Example

Telemetry.span(
  [:mcp_server, :tool, :call],
  %{session_id: session_id, tool_name: tool_name},
  fn ->
    result = router.call_tool(mcp_conn, tool_name, arguments)
    {result, %{result_count: count_results(result)}}
  end
)