Skip to content

feat: Add OpenTelemetry integration design proposal #597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 11, 2025

Conversation

JAORMX
Copy link
Collaborator

@JAORMX JAORMX commented Jun 3, 2025

This proposal outlines a comprehensive approach to add OpenTelemetry observability to ToolHive's MCP server proxies through middleware-based instrumentation.

Key Features

  • Leverages existing middleware system for clean integration
  • Supports both SSE and stdio transport modes
  • Provides traces, metrics, and structured logging
  • Includes MCP-specific instrumentation beyond HTTP metrics
  • Supports multiple OTEL backends and Prometheus integration
  • Maintains backward compatibility with zero performance regression

What's Included

  • Detailed technical design with implementation phases
  • Configuration options and CLI integration
  • Data model examples for traces and metrics
  • Concrete example of tools/call instrumentation
  • Prometheus integration pathways
  • Security considerations and production readiness

The design follows KISS and DRY principles by leveraging existing patterns and infrastructure, making it maintainable and extensible for future observability needs.

Related-to: #474

@JAORMX JAORMX force-pushed the feat/otel-integration-proposal branch from 6fabc17 to 2ef2ba2 Compare June 3, 2025 13:27
@JAORMX JAORMX requested review from yrobla, dmjb, lujunsan and amirejaz June 4, 2025 03:09
@JAORMX JAORMX force-pushed the feat/otel-integration-proposal branch from 2ef2ba2 to 19f3ec4 Compare June 10, 2025 08:12
JAORMX added a commit that referenced this pull request Jun 10, 2025
- Add complete OpenTelemetry instrumentation with OTLP and Prometheus exporters
- Implement HTTP middleware with MCP protocol-aware tracing and metrics
- Add CLI flags for telemetry configuration (--otel-endpoint, --otel-metrics-port, etc.)
- Expose /metrics endpoints on both HTTPSSEProxy and TransparentProxy
- Include comprehensive observability documentation
- Support dual export architecture (OTLP push + Prometheus pull)
- Add tool-specific metrics and argument sanitization for security
- Integrate seamlessly with existing middleware chain

Implements: #597
Fixes: #474
JAORMX added a commit that referenced this pull request Jun 11, 2025
- Add complete OpenTelemetry instrumentation with OTLP and Prometheus exporters
- Implement HTTP middleware with MCP protocol-aware tracing and metrics
- Add CLI flags for telemetry configuration (--otel-endpoint, --otel-metrics-port, etc.)
- Expose /metrics endpoints on both HTTPSSEProxy and TransparentProxy
- Include comprehensive observability documentation
- Support dual export architecture (OTLP push + Prometheus pull)
- Add tool-specific metrics and argument sanitization for security
- Integrate seamlessly with existing middleware chain

Implements: #597
Fixes: #474
Signed-off-by: Juan Antonio Osorio <[email protected]>
JAORMX added a commit that referenced this pull request Jun 11, 2025
- Add complete OpenTelemetry instrumentation with OTLP and Prometheus exporters
- Implement HTTP middleware with MCP protocol-aware tracing and metrics
- Add CLI flags for telemetry configuration (--otel-endpoint, --otel-metrics-port, etc.)
- Expose /metrics endpoints on both HTTPSSEProxy and TransparentProxy
- Include comprehensive observability documentation
- Support dual export architecture (OTLP push + Prometheus pull)
- Add tool-specific metrics and argument sanitization for security
- Integrate seamlessly with existing middleware chain

Implements: #597
Fixes: #474
Signed-off-by: Juan Antonio Osorio <[email protected]>
JAORMX added a commit that referenced this pull request Jun 11, 2025
- Add complete OpenTelemetry instrumentation with OTLP and Prometheus exporters
- Implement HTTP middleware with MCP protocol-aware tracing and metrics
- Add CLI flags for telemetry configuration (--otel-endpoint, --otel-metrics-port, etc.)
- Expose /metrics endpoints on both HTTPSSEProxy and TransparentProxy
- Include comprehensive observability documentation
- Support dual export architecture (OTLP push + Prometheus pull)
- Add tool-specific metrics and argument sanitization for security
- Integrate seamlessly with existing middleware chain

Implements: #597
Fixes: #474
Signed-off-by: Juan Antonio Osorio <[email protected]>
JAORMX added a commit that referenced this pull request Jun 11, 2025
- Add complete OpenTelemetry instrumentation with OTLP and Prometheus exporters
- Implement HTTP middleware with MCP protocol-aware tracing and metrics
- Add CLI flags for telemetry configuration (--otel-endpoint, --otel-metrics-port, etc.)
- Expose /metrics endpoints on both HTTPSSEProxy and TransparentProxy
- Include comprehensive observability documentation
- Support dual export architecture (OTLP push + Prometheus pull)
- Add tool-specific metrics and argument sanitization for security
- Integrate seamlessly with existing middleware chain

Implements: #597
Fixes: #474
Signed-off-by: Juan Antonio Osorio <[email protected]>
JAORMX added a commit that referenced this pull request Jun 11, 2025
- Add complete OpenTelemetry instrumentation with OTLP and Prometheus exporters
- Implement HTTP middleware with MCP protocol-aware tracing and metrics
- Add CLI flags for telemetry configuration (--otel-endpoint, --otel-metrics-port, etc.)
- Expose /metrics endpoints on both HTTPSSEProxy and TransparentProxy
- Include comprehensive observability documentation
- Support dual export architecture (OTLP push + Prometheus pull)
- Add tool-specific metrics and argument sanitization for security
- Integrate seamlessly with existing middleware chain

Implements: #597
Fixes: #474
Signed-off-by: Juan Antonio Osorio <[email protected]>
This proposal outlines a comprehensive approach to add OpenTelemetry
observability to ToolHive's MCP server proxies through middleware-based
instrumentation.

Key features:
- Leverages existing middleware system for clean integration
- Supports both SSE and stdio transport modes
- Provides traces, metrics, and structured logging
- Includes MCP-specific instrumentation beyond HTTP metrics
- Supports multiple OTEL backends and Prometheus integration
- Maintains backward compatibility with zero performance regression

The design includes detailed examples of traces and metrics for
tools/call operations, showing rich observability into MCP protocol
interactions.

Related-to: #474
Signed-off-by: Juan Antonio Osorio <[email protected]>
@JAORMX JAORMX force-pushed the feat/otel-integration-proposal branch from 19f3ec4 to 880adcd Compare June 11, 2025 08:29
@JAORMX JAORMX merged commit d57f50d into main Jun 11, 2025
13 checks passed
@JAORMX JAORMX deleted the feat/otel-integration-proposal branch June 11, 2025 08:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants