From 33933ca1956a681f5137be27ca8e95544658969c Mon Sep 17 00:00:00 2001
From: diego-ferrand <diego.ferrand@abstracta.com.uy>
Date: Mon, 13 Jul 2026 12:57:39 -0300
Subject: [PATCH] Added OTEL documentation

---
 README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/README.md b/README.md
index 5279aed..e5dff28 100644
--- a/README.md
+++ b/README.md
@@ -157,7 +157,74 @@ When using custom CA certificate bundles, you must configure both:
 
 ---
 
+## OpenTelemetry
 
+Perfecto MCP reports traces and metrics for MCP tool calls using [OpenTelemetry](https://opentelemetry.io/). This gives you visibility into which tools are used, how long they take, and when errors occur.
+
+Telemetry is enabled by default. You do not need to configure anything unless you want to change where data is sent or turn it off.
+
+### Default behavior
+
+By default, telemetry is exported over gRPC to:
+
+`https://grpc.public.prd.shared.perforce.com`
+
+The service is identified as `perfecto-mcp` with the current release version. If telemetry fails to start or export, the MCP server continues to work as usual.
+
+### Turn off telemetry
+
+Add `OTEL_SDK_DISABLED=true` to your MCP client environment:
+
+```json
+"env": {
+  "OTEL_SDK_DISABLED": "true"
+}
+```
+
+For Docker, pass it with `-e`:
+
+```json
+"-e",
+"OTEL_SDK_DISABLED=true"
+```
+
+### Send data to your own collector
+
+Use these environment variables to point at a different OpenTelemetry collector (for example, a local one during development):
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector URL | `https://grpc.public.prd.shared.perforce.com` |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`, `http/protobuf`, or `http/json` | `grpc` |
+
+gRPC example (typical local collector on port 4317):
+
+```json
+"env": {
+  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
+  "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc"
+}
+```
+
+HTTP example (typical local collector on port 4318):
+
+```json
+"env": {
+  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318",
+  "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf"
+}
+```
+
+### What gets reported
+
+Each MCP tool call creates:
+
+- **Traces** — one span per call with the tool name, action, MCP client name and version, session ID, and error type when applicable.
+- **Metrics** — `mcp.tool.calls` (count) and `mcp.tool.duration` (seconds), broken down by tool and action.
+
+Security tokens and other credentials are not included in telemetry data.
+
+If your MCP client sends `traceparent` or `tracestate` in the request metadata, Perfecto MCP links its spans to that parent trace.
 
 ---