[otel] Update MCP server with OTEL

.env.example

@@ -0,0 +1,157 @@
+# Mapbox MCP 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-server
+# OTEL_SERVICE_VERSION=0.6.1
+
+# Resource attributes (customize as needed)
+OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-server,service.version=0.6.1
+
+# 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-server,service.version=0.6.1,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-server,service.version=0.6.1,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-server,service.version=0.6.1,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-server,service.version=0.6.1,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-server,service.version=0.6.1
+
+# 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-server"}
+
+# Honeycomb-specific resource attributes
+# OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-server,service.version=0.6.1
+
+# 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/

README.md

@@ -199,31 +199,57 @@ This MCP server includes comprehensive OpenTelemetry tracing for production obse
 ### Quick Demo
 
 ```sh
-# Run tracing demo with console output
-npm run demo:tracing
-```
+# 1. Copy the example configuration
+cp .env.example .env
 
-### Testing with Tracing
+# 2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing
 
-```sh
-# Run tests with tracing enabled
-npm run test:tracing
+# 3. Start Jaeger for local development
+npm run tracing:jaeger:start
+
+# 4. Run the server (it will automatically use .env configuration)
+npm run inspect:build
+
+# 5. View traces at http://localhost:16686
+
+# 6. Stop Jaeger when done
+npm run tracing:jaeger:stop
 ```
 
+**Note:** The server automatically loads configuration from your `.env` file at startup. The `.env.example` file includes configuration examples for multiple observability platforms.
+
+### Supported Observability Platforms
+
+Configuration examples included in `.env.example` for:
+
+**Cloud Providers:**
+
+- ☁️ AWS X-Ray
+- ☁️ Azure Monitor (Application Insights)
+- ☁️ Google Cloud Trace
+
+**SaaS Platforms:**
+
+- 📊 Datadog
+- 📊 New Relic
+- 📊 Honeycomb
+- 📊 Any OTLP-compatible backend
+
 ### Production Configuration
 
 See [docs/tracing.md](./docs/tracing.md) for complete setup instructions including:
 
-- 🔧 Environment variable configuration
-- 📊 Supported backends (Jaeger, AWS X-Ray, Google Cloud, etc.)
+- 🔧 Platform-specific configuration guides
+- 📊 Authentication and endpoint setup
 - 🎯 Custom trace attributes and context
 - 🚀 Performance optimization (minimal overhead)
 - 🔍 Troubleshooting and debugging
 
 **Tracing Features:**
 
+- ✅ Configuration loading tracing (.env file loading)
 - ✅ Automatic tool execution tracing
-- ✅ HTTP request instrumentation
+- ✅ HTTP request instrumentation with CloudFront correlation IDs
 - ✅ Configurable exporters (console, OTLP)
 - ✅ Security-conscious (data protection, JWT validation)
 - ✅ Production-ready (<1% CPU overhead)

docs/complete-observability.md

@@ -4,27 +4,42 @@ This MCP server now has **comprehensive end-to-end tracing** for all major opera
 
 ## 🏗️ **Complete Tracing Architecture**
 
-### **1. Tool Execution Tracing**
+### **1. Configuration Loading Tracing**
+
+- .env file loading and parsing (using Node.js built-in parseEnv)
+- Number of environment variables loaded
+- Configuration errors and warnings
+- Startup configuration validation
+
+### **2. Tool Execution Tracing**
 
 - Tool lifecycle (start, execute, complete)
 - Input validation and processing
 - Error handling and propagation
 - Business logic performance
 
-### **2. HTTP Request Tracing**
+### **3. HTTP Request Tracing**
 
 - All outbound HTTP calls (Mapbox APIs, external services)
 - Request/response metadata (headers, status codes, timing)
+- CloudFront correlation IDs for Mapbox API requests
+- Cache hit/miss tracking via CloudFront headers
 - Retry logic and failure handling
 - Network-level performance metrics
 
 ## 🔗 **Connected Trace Hierarchy**
 
 ```
+⚙️  Configuration Loading (Startup)
+└── config.load_env
+    ├── File existence check
+    ├── Environment variable parsing
+    └── Configuration validation
+
 🔄 MCP Tool Execution (Root)
 ├── 🌐 HTTP API Calls
 │   ├── Request Preparation
-│   ├── Network Transfer
+│   ├── Network Transfer (with CloudFront correlation)
 │   └── Response Processing
 └── 📊 Business Logic
     ├── Data Transformation
@@ -41,6 +56,18 @@ This MCP server now has **comprehensive end-to-end tracing** for all major opera
 
 ## 📊 **Trace Attributes Captured**
 
+### Configuration Context
+
+```json
+{
+  "config.file.path": "/app/.env",
+  "config.file.exists": true,
+  "config.vars.loaded": 5,
+  "operation.type": "config_load",
+  "config.load.success": true
+}
+```
+
 ### Tool Context
 
 ```json
@@ -52,15 +79,19 @@ This MCP server now has **comprehensive end-to-end tracing** for all major opera
 }
 ```
 
-### HTTP Context
+### HTTP Context (with CloudFront Correlation)
 
 ```json
 {
   "http.method": "POST",
   "http.url": "https://api.mapbox.com/search/v1",
   "http.status_code": 200,
   "http.response.content_length": 2048,
-  "http.duration_ms": 125
+  "http.duration_ms": 125,
+  "http.response.header.x_amz_cf_id": "HsL_E2ZgW72g4tg...",
+  "http.response.header.x_amz_cf_pop": "IAD55-P3",
+  "http.response.header.x_cache": "Miss from cloudfront",
+  "http.response.header.etag": "W/\"21fe5-88gH...\""
 }
 ```