Merge pull request #39 from mapbox/otel_refresh

[otel] Update DevKit Server with OTEL implementation

Author: mattpodwysocki

.env.example

@@ -0,0 +1,157 @@
+# Mapbox MCP DevKit Server Configuration
+# Copy this file to .env and configure as needed
+
+# =============================================================================
+# Required Configuration
+# =============================================================================
+
+# Mapbox API Access Token (required)
+# Get your token at: https://account.mapbox.com/access-tokens
+MAPBOX_ACCESS_TOKEN=your-mapbox-token-here
+
+# =============================================================================
+# Optional MCP Configuration
+# =============================================================================
+
+# Disable console logging (recommended when using stdio transport)
+# Uncomment to enable:
+# MCP_DISABLE_LOGGING=true
+
+# =============================================================================
+# OpenTelemetry Tracing (Optional)
+# =============================================================================
+
+# Enable tracing by setting an OTLP endpoint
+# For local development with Jaeger:
+#   1. Start Jaeger: npm run tracing:jaeger:start
+#   2. Uncomment the line below
+#   3. View traces at: http://localhost:16686
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+
+# Service identification
+OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
+# OTEL_SERVICE_VERSION=0.4.5
+
+# Resource attributes (customize as needed)
+OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-devkit-server,service.version=0.4.5
+
+# Optional: Console tracing for development (SSE transport only)
+# ⚠️  Do NOT enable with stdio transport - it breaks JSON-RPC communication
+# OTEL_EXPORTER_CONSOLE_ENABLED=true
+
+# Optional: OTLP authentication headers (for production backends)
+# OTEL_EXPORTER_OTLP_HEADERS={"Authorization": "Bearer your-token"}
+
+# Optional: Sampling (useful for high-volume production environments)
+# OTEL_TRACES_SAMPLER=traceidratio
+# OTEL_TRACES_SAMPLER_ARG=0.1
+
+# =============================================================================
+# AWS X-Ray Configuration (Optional)
+# =============================================================================
+# Uncomment these settings if using AWS X-Ray instead of Jaeger
+
+# AWS region (required for X-Ray)
+# AWS_REGION=us-east-1
+
+# X-Ray specific resource attributes
+# OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-devkit-server,service.version=0.4.5,aws.region=us-east-1
+
+# X-Ray trace headers (example format)
+# OTEL_EXPORTER_OTLP_HEADERS={"x-amzn-trace-id": "Root=1-5e2b3c4d-5f6a7b8c9d0e1f2a3b4c5d6e;Parent=7f8a9b0c1d2e3f4a;Sampled=1"}
+
+# Note: AWS credentials should be configured separately via:
+#   - IAM role (recommended for EC2/ECS/Lambda)
+#   - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables
+#   - AWS CLI profile (~/.aws/credentials)
+
+# =============================================================================
+# Azure Monitor Configuration (Optional)
+# =============================================================================
+# Uncomment these settings if using Azure Monitor Application Insights
+
+# Azure Monitor OTLP endpoint (replace with your ingestion endpoint)
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-region>.livediagnostics.monitor.azure.com/v1/traces
+
+# Azure Monitor authentication (use your connection string or AAD token)
+# OTEL_EXPORTER_OTLP_HEADERS={"x-ms-client-principal-id": "your-connection-string"}
+
+# Azure-specific resource attributes
+# OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-devkit-server,service.version=0.4.5,cloud.provider=azure,cloud.region=eastus
+
+# Note: Set up Azure Application Insights first
+# See: https://learn.microsoft.com/en-us/azure/azure-monitor/app/opentelemetry-enable
+
+# =============================================================================
+# Google Cloud Trace Configuration (Optional)
+# =============================================================================
+# Uncomment these settings if using Google Cloud Trace
+
+# GCP Trace OTLP endpoint
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://cloudtrace.googleapis.com/v2/projects/<project-id>/traces
+
+# GCP-specific resource attributes
+# OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-devkit-server,service.version=0.4.5,cloud.provider=gcp,gcp.project.id=your-project-id
+
+# Note: Ensure you have Application Default Credentials configured
+# gcloud auth application-default login
+# Or use a service account with Cloud Trace Agent role
+
+# =============================================================================
+# Datadog Configuration (Optional)
+# =============================================================================
+# Uncomment these settings if using Datadog APM
+
+# Datadog OTLP endpoint (use your Datadog site)
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://api.datadoghq.com/api/v2/traces
+
+# Datadog API key authentication
+# OTEL_EXPORTER_OTLP_HEADERS={"dd-api-key": "your-datadog-api-key"}
+
+# Datadog-specific resource attributes
+# OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-devkit-server,service.version=0.4.5,deployment.environment=production
+
+# Note: Datadog also supports agent-based collection via localhost:4318
+# See: https://docs.datadoghq.com/tracing/trace_collection/opentelemetry/
+
+# =============================================================================
+# New Relic Configuration (Optional)
+# =============================================================================
+# Uncomment these settings if using New Relic
+
+# New Relic OTLP endpoint
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net:4318
+
+# New Relic license key authentication
+# OTEL_EXPORTER_OTLP_HEADERS={"api-key": "your-new-relic-license-key"}
+
+# New Relic-specific resource attributes
+# OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-devkit-server,service.version=0.4.5
+
+# Note: Use your specific New Relic data center endpoint:
+#   US: https://otlp.nr-data.net:4318
+#   EU: https://otlp.eu01.nr-data.net:4318
+# See: https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/opentelemetry-setup/
+
+# =============================================================================
+# Honeycomb Configuration (Optional)
+# =============================================================================
+# Uncomment these settings if using Honeycomb
+
+# Honeycomb OTLP endpoint
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io:443
+
+# Honeycomb API key and dataset
+# OTEL_EXPORTER_OTLP_HEADERS={"x-honeycomb-team": "your-api-key", "x-honeycomb-dataset": "mapbox-mcp-devkit-server"}
+
+# Honeycomb-specific resource attributes
+# OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-devkit-server,service.version=0.4.5
+
+# Note: Get your API key from: https://ui.honeycomb.io/account
+# See: https://docs.honeycomb.io/getting-data-in/opentelemetry-overview/
+
+# =============================================================================
+# Custom API Endpoint (Optional)
+# =============================================================================
+# Override the default Mapbox API endpoint if needed
+# MAPBOX_API_ENDPOINT=https://api.mapbox.com/

CLAUDE.md

@@ -17,6 +17,72 @@ This file provides Claude and developers with essential context, commands, and s
 - `npm run sync-manifest` — Sync version from package.json to manifest.json
 - `docker build -t mapbox-mcp-devkit .` — Build Docker image
 - `docker run mapbox/mcp-devkit-server ...` — Run server in Docker
+- `npm run tracing:jaeger:start` — Start Jaeger tracing backend (requires Docker)
+- `npm run tracing:jaeger:stop` — Stop Jaeger tracing backend
+- `npm run tracing:verify` — Show instructions for verifying tracing setup
+
+## Observability & Tracing
+
+This server includes OpenTelemetry (OTEL) instrumentation for distributed tracing. Tracing is **opt-in** and disabled by default.
+
+### Quick Start with Jaeger
+
+1. Start Jaeger backend (requires Docker):
+
+   ```bash
+   npm run tracing:jaeger:start
+   ```
+
+2. Configure environment variables in `.env`:
+
+   ```bash
+   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+   OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
+   ```
+
+3. Run the server:
+
+   ```bash
+   npm run inspect:build
+   ```
+
+4. View traces at http://localhost:16686
+
+5. Stop Jaeger when done:
+   ```bash
+   npm run tracing:jaeger:stop
+   ```
+
+### Environment Variables
+
+- `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP endpoint URL (e.g., `http://localhost:4318`). If not set, tracing is disabled.
+- `OTEL_EXPORTER_CONSOLE_ENABLED` — Set to `true` to log traces to console (avoid with stdio transport)
+- `OTEL_TRACING_ENABLED` — Set to `false` to explicitly disable tracing even if endpoint is configured
+- `OTEL_SERVICE_NAME` — Override service name (default: `mapbox-mcp-devkit-server`)
+- `OTEL_EXPORTER_OTLP_HEADERS` — JSON string of additional headers for OTLP exporter
+
+### What Gets Traced
+
+- Tool execution spans with timing and status
+- HTTP requests to Mapbox APIs (automatic instrumentation)
+- Configuration loading and initialization
+- Error details and stack traces
+
+### Trace Attributes
+
+Each tool execution span includes:
+
+- `tool.name` — Tool identifier
+- `tool.input.size` — Input payload size
+- `operation.type` — Type of operation (e.g., `tool_execution`)
+- `session.id`, `user.id`, `account.id` — Context from MCP extra fields (if provided)
+
+### Production Considerations
+
+- Tracing has minimal overhead when enabled
+- Recommended for debugging complex tool chains and performance issues
+- Can be used with any OTLP-compatible backend (Jaeger, Honeycomb, DataDog, etc.)
+- For hosted endpoints, configure appropriate sampling rates
 
 ## Core Files & Structure
 

README.md

@@ -27,6 +27,7 @@ https://github.com/user-attachments/assets/8b1b8ef2-9fba-4951-bc9a-beaed4f6aff6
       - [Coordinate Conversion tool](#coordinate-conversion-tool)
       - [Bounding Box tool](#bounding-box-tool)
   - [Resources](#resources)
+  - [Observability & Tracing](#observability--tracing)
   - [Development](#development)
     - [Testing](#testing)
       - [Tool Snapshot Tests](#tool-snapshot-tests)
@@ -481,6 +482,66 @@ This server exposes static reference documentation as MCP Resources. While these
 
 **Note:** Resources provide static reference data that doesn't change frequently, while tools provide dynamic, user-specific data (like listing your styles or tokens) and perform actions (like creating styles or tokens).
 
+## Observability & Tracing
+
+This server includes comprehensive distributed tracing using OpenTelemetry (OTEL) for production-ready observability.
+
+### Features
+
+- **Opt-in Configuration**: Tracing is disabled by default, enabling it requires only setting an OTLP endpoint
+- **Tool Execution Tracing**: Automatic instrumentation of all tool executions with timing, success/failure status, and error details
+- **HTTP Request Instrumentation**: Complete request/response tracing for Mapbox API calls with CloudFront correlation IDs
+- **Configuration Tracing**: Startup configuration loading with error tracking
+- **Security**: Input/output sizes logged but content is protected
+- **Low Overhead**: <1% CPU impact, ~10MB memory for trace buffers
+
+### Quick Start with Jaeger
+
+```bash
+# 1. Start Jaeger (Docker required)
+npm run tracing:jaeger:start
+
+# 2. Configure environment
+cp .env.example .env
+# Edit .env to add MAPBOX_ACCESS_TOKEN
+# OTEL_EXPORTER_OTLP_ENDPOINT is already set to http://localhost:4318
+
+# 3. Run the server
+npm run inspect:build
+
+# 4. View traces at http://localhost:16686
+
+# 5. Stop Jaeger when done
+npm run tracing:jaeger:stop
+```
+
+### Supported Backends
+
+The server supports **any OTLP-compatible backend** including:
+
+- **Development**: Jaeger (local Docker)
+- **Cloud Providers**: AWS X-Ray, Azure Monitor, Google Cloud Trace
+- **SaaS Platforms**: Datadog, New Relic, Honeycomb
+
+See `.env.example` for configuration examples for each platform.
+
+### Documentation
+
+- **[Complete Tracing Guide](./docs/tracing.md)** - Detailed configuration, features, and integration examples
+- **[Verification Guide](./docs/tracing-verification.md)** - Step-by-step verification and troubleshooting
+
+### Environment Variables
+
+```bash
+# Enable tracing (required)
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+
+# Optional configuration
+OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
+OTEL_TRACES_SAMPLER=traceidratio
+OTEL_TRACES_SAMPLER_ARG=0.1  # Sample 10% for high-volume
+```
+
 ## Development
 
 ### Testing