shinzo-py

Shinzo provides OpenTelemetry-compatible instrumentation for Python MCP servers. By integrating Shinzo into your MCP server, you gain visibility into tool calls, request flows, and performance metrics across your MCP deployments. The library supports both the FastMCP and Traditional MCP SDKs, automatically instrumenting server operations with minimal or zero code changes. To use Shinzo, install the shinzo package in your server environment and initialize instrumentation at startup. You can then define and expose tools as part of your MCP server, while Shinzo collects traces, metrics, and PII-sanitized telemetry according to your configuration. The instrumentation is designed to be lightweight, with options to enable or disable tracing, metrics, and argument collection as needed. Additionally, you can configure exporters (OTLP, console, etc.), sampling rates, and data processors to tailor telemetry to your observability goals.

Prerequisites:

• Python 3.8+ installed on your MCP server
• Internet access to install packages from PyPI

Step 1: Create and activate a Python environment (recommended)

• For Windows: python -m venv env .\env\Scripts\activate
• For macOS/Linux: python3 -m venv env source env/bin/activate

Step 2: Install Shinzo package

pip install shinzo

Step 3: Instrument your MCP server

• Import and instrument your server using Shinzo’s instrument_server helper as shown in the Quick Start examples for FastMCP or Traditional MCP.
• Configure exporter details and authentication as needed (e.g., bearer token, API key, or basic auth).

Step 4: Run your MCP server with Shinzo instrumentation enabled

• Ensure your startup command includes the Shinzo instrumentation setup
• Example startup pattern (adapt to your server):

python -m shinzo_server

Step 5: Verify telemetry

• Check that traces and metrics are being exported to your configured endpoint (OTLP or console) and validate that tool calls are being captured.

Tips and common considerations:

• Exporter configuration: You can enable various exporters (e.g., otlp-http, console). Adjust exporter_endpoint and exporter_auth in your config.
• Privacy and PII: If your tools pass sensitive data, enable pii_sanitizer or pii sanitization features and adjust enable_pii_sanitization accordingly.
• Instrumentation scope: You can control what gets included in telemetry, such as argument collection and server metadata, via configuration options like enable_argument_collection and server_version.
• Performance: Start with default sampling rate (1.0) and enable_metrics to monitor impact. If overhead is seen, adjust sampling_rate or batch_timeout_ms.
• SDK compatibility: Shinzo supports both FastMCP and Traditional MCP; instrumentation should work with either, but verify that the decorator or tool-calling patterns align with your chosen SDK.
• Troubleshooting: If no telemetry shows up, check environment variables, exporter endpoint reachability, and that the instrumented server startup path is correctly invoked.