Skip to content
Back to search

opentelemetry-mcp-server

Unified MCP server for querying OpenTelemetry traces across multiple backends (Jaeger, Tempo, Traceloop, etc.), enabling AI agents to analyze distributed traces for automated debugging and observability.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/traceloop--opentelemetry-mcp-server/badge.svg)](/listings/traceloop--opentelemetry-mcp-server)

HTML

<a href="/listings/traceloop--opentelemetry-mcp-server"><img src="/api/listings/traceloop--opentelemetry-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**No installation required!** Configure your client to run the server directly from PyPI:

// Add to claude_desktop_config.json:
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "pipx",
      "args": ["run", "opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

Or use `uvx` (alternative):

{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "uvx",
      "args": ["opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

**That's it!** Ask Claude: _"Show me traces with errors from the last hour"_

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,053 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OpenTelemetry MCP Server
  2. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  3. [![PyPI](https://img.shields.io/pypi/v/opentelemetry-mcp)](https://pypi.org/project/opentelemetry-mcp/)
  4. [![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
  5. **Query and analyze LLM traces with AI assistance.** Ask Claude to find expensive API calls, debug errors, compare model performance, or track token usage—all from your IDE.
  6. An MCP (Model Context Protocol) server that connects AI assistants to OpenTelemetry trace backends (Jaeger, Tempo, Traceloop), with specialized support for LLM observability through OpenLLMetry semantic conventions.
  7. **See it in action:**
  8. https://github.com/user-attachments/assets/e2106ef9-0a58-4ba0-8b2b-e114c0b8b4b9
  9. ---
  10. ## Table of Contents
  11. - [Quick Start](#quick-start)
  12. - [Installation](#installation)
  13. - [Features](#features)
  14. - [Configuration](#configuration)
  15. - [Tools Reference](#tools-reference)
  16. - [Example Queries](#example-queries)
  17. - [Common Workflows](#common-workflows)
  18. - [Troubleshooting](#troubleshooting)
  19. - [Development](#development)
  20. - [Support](#support)
  21. ---
  22. ## Quick Start
  23. **No installation required!** Configure your client to run the server directly from PyPI:
  24. ```json
  25. // Add to claude_desktop_config.json:
  26. {
  27. "mcpServers": {
  28. "opentelemetry-mcp": {
  29. "command": "pipx",
  30. "args": ["run", "opentelemetry-mcp"],
  31. "env": {
  32. "BACKEND_TYPE": "jaeger",
  33. "BACKEND_URL": "http://localhost:16686"
  34. }
  35. }
  36. }
  37. }
  38. ```
  39. Or use `uvx` (alternative):
  40. ```json
  41. {
  42. "mcpServers": {
  43. "opentelemetry-mcp": {
  44. "command": "uvx",
  45. "args": ["opentelemetry-mcp"],
  46. "env": {
  47. "BACKEND_TYPE": "jaeger",
  48. "BACKEND_URL": "http://localhost:16686"
  49. }
  50. }
  51. }
  52. }
  53. ```
  54. **That's it!** Ask Claude: _"Show me traces with errors from the last hour"_
  55. ---
  56. ## Installation
  57. ### For End Users (Recommended)
  58. ```bash
  59. # Run without installing (recommended)
  60. pipx run opentelemetry-mcp --backend jaeger --url http://localhost:16686
  61. # Or with uvx
  62. uvx opentelemetry-mcp --backend jaeger --url http://localhost:16686
  63. ```
  64. This approach:
  65. - ✅ Always uses the latest version
  66. - ✅ No global installation needed
  67. - ✅ Isolated environment automatically
  68. - ✅ Works on all platforms
  69. ### Per Client Integration
  70. <details>
  71. <summary><b>Claude Desktop</b></summary>
  72. Configure the MCP server in your Claude Desktop config file:
  73. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  74. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  75. **Using pipx (recommended):**
  76. ```json
  77. {
  78. "mcpServers": {
  79. "opentelemetry-mcp": {
  80. "command": "pipx",
  81. "args": ["run", "opentelemetry-mcp"],
  82. "env": {
  83. "BACKEND_TYPE": "jaeger",
  84. "BACKEND_URL": "http://localhost:16686"
  85. }
  86. }
  87. }
  88. }
  89. ```
  90. **Using uvx (alternative):**
  91. ```json
  92. {
  93. "mcpServers": {
  94. "opentelemetry-mcp": {
  95. "command": "uvx",
  96. "args": ["opentelemetry-mcp"],
  97. "env": {
  98. "BACKEND_TYPE": "jaeger",
  99. "BACKEND_URL": "http://localhost:16686"
  100. }
  101. }
  102. }
  103. }
  104. ```
  105. **For Traceloop backend:**
  106. ```json
  107. {
  108. "mcpServers": {
  109. "opentelemetry-mcp": {
  110. "command": "pipx",
  111. "args": ["run", "opentelemetry-mcp"],
  112. "env": {
  113. "BACKEND_TYPE": "traceloop",
  114. "BACKEND_URL": "https://api.traceloop.com",
  115. "BACKEND_API_KEY": "your_traceloop_api_key_here"
  116. }
  117. }
  118. }
  119. }
  120. ```
  121. <details>
  122. <summary>Using the repository instead of pipx?</summary>
  123. If you're developing locally with the cloned repository, use one of these configurations:
  124. **Option 1: Wrapper script (easy backend switching)**
  125. ```json
  126. {
  127. "mcpServers": {
  128. "opentelemetry-mcp": {
  129. "command": "/absolute/path/to/opentelemetry-mcp-server/start_locally.sh"
  130. }
  131. }
  132. }
  133. ```
  134. **Option 2: UV directly (for multiple backends)**
  135. ```json
  136. {
  137. "mcpServers": {
  138. "opentelemetry-mcp-jaeger": {
  139. "command": "uv",
  140. "args": [
  141. "--directory",
  142. "/absolute/path/to/opentelemetry-mcp-server",
  143. "run",
  144. "opentelemetry-mcp"
  145. ],
  146. "env": {
  147. "BACKEND_TYPE": "jaeger",
  148. "BACKEND_URL": "http://localhost:16686"
  149. }
  150. }
  151. }
  152. }
  153. ```
  154. </details>
  155. </details>
  156. <details>
  157. <summary><b>Claude Code</b></summary>
  158. Claude Code works with MCP servers configured in your Claude Desktop config. Once configured above, you can use the server with Claude Code CLI:
  159. ```bash
  160. # Verify the server is available
  161. claude-code mcp list
  162. # Use Claude Code with access to your OpenTelemetry traces
  163. claude-code "Show me traces with errors from the last hour"
  164. ```
  165. </details>
  166. <details>
  167. <summary><b>Codeium (Windsurf)</b></summary>
  168. 1. Open Windsurf
  169. 2. Navigate to **Settings → MCP Servers**
  170. 3. Click **Add New MCP Server**
  171. 4. Add this configuration:
  172. **Using pipx (recommended):**
  173. ```json
  174. {
  175. "opentelemetry-mcp": {
  176. "command": "pipx",
  177. "args": ["run", "opentelemetry-mcp"],
  178. "env": {
  179. "BACKEND_TYPE": "jaeger",
  180. "BACKEND_URL": "http://localhost:16686"
  181. }
  182. }
  183. }
  184. ```
  185. **Using uvx (alternative):**
  186. ```json
  187. {
  188. "opentelemetry-mcp": {
  189. "command": "uvx",
  190. "args": ["opentelemetry-mcp"],
  191. "env": {
  192. "BACKEND_TYPE": "jaeger",
  193. "BACKEND_URL": "http://localhost:16686"
  194. }
  195. }
  196. }
  197. ```
  198. <details>
  199. <summary>Using the repository instead?</summary>
  200. ```json
  201. {
  202. "opentelemetry-mcp": {
  203. "command": "uv",
  204. "args": [
  205. "--directory",
  206. "/absolute/path/to/opentelemetry-mcp-server",
  207. "run",
  208. "opentelemetry-mcp"
  209. ],
  210. "env": {
  211. "BACKEND_TYPE": "jaeger",
  212. "BACKEND_URL": "http://localhost:16686"
  213. }
  214. }
  215. }
  216. ```
  217. </details>
  218. </details>
  219. <details>
  220. <summary><b>Cursor</b></summary>
  221. 1. Open Cursor
  222. 2. Navigate to **Settings → MCP**
  223. 3. Click **Add new MCP Server**
  224. 4. Add this configuration:
  225. **Using pipx (recommended):**
  226. ```json
  227. {
  228. "opentelemetry-mcp": {
  229. "command": "pipx",
  230. "args": ["run", "opentelemetry-mcp"],
  231. "env": {
  232. "BACKEND_TYPE": "jaeger",
  233. "BACKEND_URL": "http://localhost:16686"
  234. }
  235. }
  236. }
  237. ```
  238. **Using uvx (alternative):**
  239. ```json
  240. {
  241. "opentelemetry-mcp": {
  242. "command": "uvx",
  243. "args": ["opentelemetry-mcp"],
  244. "env": {
  245. "BACKEND_TYPE": "jaeger",
  246. "BACKEND_URL": "http://localhost:16686"
  247. }
  248. }
  249. }
  250. ```
  251. <details>
  252. <summary>Using the repository instead of pipx?</summary>
  253. ```json
  254. {
  255. "opentelemetry-mcp": {
  256. "command": "uv",
  257. "args": [
  258. "--directory",
  259. "/absolute/path/to/opentelemetry-mcp-server",
  260. "run",
  261. "opentelemetry-mcp"
  262. ],
  263. "env": {
  264. "BACKEND_TYPE": "jaeger",
  265. "BACKEND_URL": "http://localhost:16686"
  266. }
  267. }
  268. }
  269. ```
  270. </details>
  271. </details>
  272. <details>
  273. <summary><b>Gemini CLI</b></summary>
  274. Configure the MCP server in your Gemini CLI config file (`~/.gemini/config.json`):
  275. **Using pipx (recommended):**
  276. ```json
  277. {
  278. "mcpServers": {
  279. "opentelemetry-mcp": {
  280. "command": "pipx",
  281. "args": ["run", "opentelemetry-mcp"],
  282. "env": {
  283. "BACKEND_TYPE": "jaeger",
  284. "BACKEND_URL": "http://localhost:16686"
  285. }
  286. }
  287. }
  288. }
  289. ```
  290. **Using uvx (alternative):**
  291. ```json
  292. {
  293. "mcpServers": {
  294. "opentelemetry-mcp": {
  295. "command": "uvx",
  296. "args": ["opentelemetry-mcp"],
  297. "env": {
  298. "BACKEND_TYPE": "jaeger",
  299. "BACKEND_URL": "http://localhost:16686"
  300. }
  301. }
  302. }
  303. }
  304. ```
  305. Then use Gemini CLI with your traces:
  306. ```bash
  307. gemini "Analyze token usage for gpt-4 requests today"
  308. ```
  309. <details>
  310. <parameter name="name">Using the repository instead?</summary>
  311. ```json
  312. {
  313. "mcpServers": {
  314. "opentelemetry-mcp": {
  315. "command": "uv",
  316. "args": [
  317. "--directory",
  318. "/absolute/path/to/opentelemetry-mcp-server",
  319. "run",
  320. "opentelemetry-mcp"
  321. ],
  322. "env": {
  323. "BACKEND_TYPE": "jaeger",
  324. "BACKEND_URL": "http://localhost:16686"
  325. }
  326. }
  327. }
  328. }
  329. ```
  330. </details>
  331. </details>
  332. **_Prerequisites:_**
  333. - Python 3.11 or higher
  334. - [pipx](https://pipx.pypa.io/) or [uv](https://github.com/astral-sh/uv) installed
  335. <details>
  336. <summary><b>Optional: Install globally</b></summary>
  337. If you prefer to install the command globally:
  338. ```bash
  339. # Install with pipx
  340. pipx install opentelemetry-mcp
  341. # Verify
  342. opentelemetry-mcp --help
  343. # Upgrade
  344. pipx upgrade opentelemetry-mcp
  345. ```
  346. Or with pip:
  347. ```bash
  348. pip install opentelemetry-mcp
  349. ```
  350. </details>
  351. ## Features
  352. ### Core Capabilities
  353. - **🔌 Multiple Backend Support** - Connect to Jaeger, Grafana Tempo, or Traceloop
  354. - **🤖 LLM-First Design** - Specialized tools for analyzing AI application traces
  355. - **🔍 Advanced Filtering** - Generic filter system with powerful operators
  356. - **📊 Token Analytics** - Track and aggregate LLM token usage across models and services
  357. - **⚡ Fast & Type-Safe** - Built with async Python and Pydantic validation
  358. ### Tools
  359. | Tool | Description | Use Case |
  360. | -------------------------- | ----------------------------------- | ---------------------------------- |
  361. | `search_traces` | Search traces with advanced filters | Find specific requests or patterns |
  362. | `search_spans` | Search individual spans | Analyze specific operations |
  363. | `get_trace` | Get complete trace details | Deep-dive into a single trace |
  364. | `get_llm_usage` | Aggregate token usage metrics | Track costs and usage trends |
  365. | `list_services` | List available services | Discover what's instrumented |
  366. | `find_errors` | Find traces with errors | Debug failures quickly |
  367. | `list_llm_models` | Discover models in use | Track model adoption |
  368. | `get_llm_model_stats` | Get model performance stats | Compare model efficiency |
  369. | `get_llm_expensive_traces` | Find highest token usage | Optimize costs |
  370. | `get_llm_slow_traces` | Find slowest operations | Improve performance |
  371. ### Backend Support Matrix
  372. | Feature | Jaeger | Tempo | Traceloop |
  373. | ---------------- | :----: | :---: | :-------: |
  374. | Search traces | ✓ | ✓ | ✓ |
  375. | Advanced filters | ✓ | ✓ | ✓ |
  376. | Span search | ✓\* | ✓ | ✓ |
  377. | Token tracking | ✓ | ✓ | ✓ |
  378. | Error traces | ✓ | ✓ | ✓ |
  379. | LLM tools | ✓ | ✓ | ✓ |
  380. <sub>\* Jaeger requires `service_name` parameter for span search</sub>
  381. ### For Developers
  382. If you're contributing to the project or want to make local modifications:
  383. ```bash
  384. # Clone the repository
  385. git clone https://github.com/traceloop/opentelemetry-mcp-server.git
  386. cd opentelemetry-mcp-server
  387. # Install dependencies with UV
  388. uv sync
  389. # Or install in development mode with editable install
  390. uv pip install -e ".[dev]"
  391. ```
  392. ---
  393. ## Configuration
  394. ### Supported Backends
  395. | Backend | Type | URL Example | Notes |
  396. | ------------- | ----------- | --------------------------- | -------------------------- |
  397. | **Jaeger** | Local | `http://localhost:16686` | Popular open-source option |
  398. | **Tempo** | Local/Cloud | `http://localhost:3200` | Grafana's trace backend |
  399. | **Traceloop** | Cloud | `https://api.traceloop.com` | Requires API key |
  400. ### Quick Configuration
  401. **Option 1: Environment Variables** (Create `.env` file - see [.env.example](.env.example))
  402. ```bash
  403. BACKEND_TYPE=jaeger
  404. BACKEND_URL=http://localhost:16686
  405. ```
  406. **Option 2: CLI Arguments** (Override environment)
  407. ```bash
  408. opentelemetry-mcp --backend jaeger --url http://localhost:16686
  409. opentelemetry-mcp --backend traceloop --url https://api.traceloop.com --api-key YOUR_KEY
  410. ```
  411. > **Configuration Precedence:** CLI arguments > Environment variables > Defaults
  412. <details>
  413. <summary><b>All Configuration Options</b></summary>
  414. | Variable | Type | Default | Description |
  415. | ---------------------- | ------- | -------- | -------------------------------------------------- |
  416. | `BACKEND_TYPE` | string | `jaeger` | Backend type: `jaeger`, `tempo`, or `traceloop` |
  417. | `BACKEND_URL` | URL | - | Backend API endpoint (required) |
  418. | `BACKEND_API_KEY` | string | - | API key (required for Traceloop) |
  419. | `BACKEND_TIMEOUT` | integer | `30` | Request timeout in seconds |
  420. | `LOG_LEVEL` | string | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
  421. | `MAX_TRACES_PER_QUERY` | integer | `100` | Maximum traces to return per query (1-1000) |
  422. **Complete `.env` example:**
  423. ```bash
  424. # Backend configuration
  425. BACKEND_TYPE=jaeger
  426. BACKEND_URL=http://localhost:16686
  427. # Optional: API key (mainly for Traceloop)
  428. BACKEND_API_KEY=
  429. # Optional: Request timeout (default: 30s)
  430. BACKEND_TIMEOUT=30
  431. # Optional: Logging level
  432. LOG_LEVEL=INFO
  433. # Optional: Max traces per query (default: 100)
  434. MAX_TRACES_PER_QUERY=100
  435. ```
  436. </details>
  437. <details>
  438. <summary><b>Backend-Specific Setup</b></summary>
  439. ### Jaeger
  440. ```bash
  441. BACKEND_TYPE=jaeger
  442. BACKEND_URL=http://localhost:16686
  443. ```
  444. ### Grafana Tempo
  445. ```bash
  446. BACKEND_TYPE=tempo
  447. BACKEND_URL=http://localhost:3200
  448. ```
  449. ### Traceloop
  450. ```bash
  451. BACKEND_TYPE=traceloop
  452. BACKEND_URL=https://api.traceloop.com
  453. BACKEND_API_KEY=your_api_key_here
  454. ```
  455. > **Note:** The API key contains project information. The backend uses a project slug of `"default"` and Traceloop resolves the actual project/environment from the API key.
  456. </details>
  457. ---
  458. ## Usage
  459. ### Quick Start with start_locally.sh (Recommended)
  460. The easiest way to run the server:
  461. ```bash
  462. ./start_locally.sh
  463. ```
  464. This script handles all configuration and starts the server in stdio mode (perfect for Claude Desktop integration). To switch backends, simply edit the script and uncomment your preferred backend.
  465. ### Manual Running
  466. For advanced use cases or custom configurations, you can run the server manually.
  467. #### stdio Transport (for Claude Desktop)
  468. Start the MCP server with stdio transport for local/Claude Desktop integration:
  469. ```bash
  470. # If installed with pipx/pip
  471. opentelemetry-mcp
  472. # If running from cloned repository with UV
  473. uv run opentelemetry-mcp
  474. # With backend override (pipx/pip)
  475. opentelemetry-mcp --backend jaeger --url http://localhost:16686
  476. # With backend override (UV)
  477. uv run opentelemetry-mcp --backend jaeger --url http://localhost:16686
  478. ```
  479. #### HTTP Transport (for Network Access)
  480. Start the MCP server with HTTP/SSE transport for remote access:
  481. ```bash
  482. # If installed with pipx/pip
  483. opentelemetry-mcp --transport http
  484. # If running from cloned repository with UV
  485. uv run opentelemetry-mcp --transport http
  486. # Specify custom host and port (pipx/pip)
  487. opentelemetry-mcp --transport http --host 127.0.0.1 --port 9000
  488. # With UV
  489. uv run opentelemetry-mcp --transport http --host 127.0.0.1 --port 9000
  490. ```
  491. The HTTP server will be accessible at `http://localhost:8000/sse` by default.
  492. **Transport Use Cases:**
  493. - **stdio transport**: Local use, Claude Desktop integration, single process
  494. - **HTTP transport**: Remote access, multiple clients, network deployment, sample applications
  495. ## Tools Reference
  496. ### 1. search_traces
  497. Search for traces with flexible filtering:
  498. ```python
  499. {
  500. "service_name": "my-app",
  501. "start_time": "2024-01-01T00:00:00Z",
  502. "end_time": "2024-01-01T23:59:59Z",
  503. "gen_ai_system": "openai",
  504. "gen_ai_model": "gpt-4",
  505. "min_duration_ms": 1000,
  506. "has_error": false,
  507. "limit": 50
  508. }
  509. ```
  510. **Parameters:**
  511. - `service_name` - Filter by service
  512. - `operation_name` - Filter by operation
  513. - `start_time` / `end_time` - ISO 8601 timestamps
  514. - `min_duration_ms` / `max_duration_ms` - Duration filters
  515. - `gen_ai_system` - LLM provider (openai, anthropic, etc.)
  516. - `gen_ai_model` - Model name (gpt-4, claude-3-opus, etc.)
  517. - `has_error` - Filter by error status
  518. - `tags` - Custom tag filters
  519. - `limit` - Max results (1-1000, default: 100)
  520. **Returns:** List of trace summaries with token counts
  521. ### 2. get_trace
  522. Get complete trace details including all spans and OpenLLMetry attributes:
  523. ```python
  524. {
  525. "trace_id": "abc123def456"
  526. }
  527. ```
  528. **Returns:** Full trace tree with:
  529. - All spans with attributes
  530. - Parsed OpenLLMetry data for LLM spans
  531. - Token usage per span
  532. - Error information
  533. ### 3. get_llm_usage
  534. Get aggregated token usage metrics:
  535. ```python
  536. {
  537. "start_time": "2024-01-01T00:00:00Z",
  538. "end_time": "2024-01-01T23:59:59Z",
  539. "service_name": "my-app",
  540. "gen_ai_system": "openai",
  541. "limit": 1000
  542. }
  543. ```
  544. **Returns:** Aggregated metrics with:
  545. - Total prompt/completion/total tokens
  546. - Breakdown by model
  547. - Breakdown by service
  548. - Request counts
  549. ### 4. list_services
  550. List all available services:
  551. ```python
  552. {}
  553. ```
  554. **Returns:** List of service names
  555. ### 5. find_errors
  556. Find traces with errors:
  557. ```python
  558. {
  559. "start_time": "2024-01-01T00:00:00Z",
  560. "service_name": "my-app",
  561. "limit": 50
  562. }
  563. ```
  564. **Returns:** Error traces with:
  565. - Error messages and types
  566. - Stack traces (truncated)
  567. - LLM-specific error info
  568. - Error span details
  569. ## Example Queries
  570. ### Find Expensive OpenAI Operations
  571. **Natural Language:** _"Show me OpenAI traces from the last hour that took longer than 5 seconds"_
  572. **Tool Call:** `search_traces`
  573. ```json
  574. {
  575. "service_name": "my-app",
  576. "gen_ai_system": "openai",
  577. "min_duration_ms": 5000,
  578. "start_time": "2024-01-15T10:00:00Z",
  579. "limit": 20
  580. }
  581. ```
  582. **Response:**
  583. ```json
  584. {
  585. "traces": [
  586. {
  587. "trace_id": "abc123...",
  588. "service_name": "my-app",
  589. "duration_ms": 8250,
  590. "total_tokens": 4523,
  591. "gen_ai_system": "openai",
  592. "gen_ai_model": "gpt-4"
  593. }
  594. ],
  595. "count": 1
  596. }
  597. ```
  598. ---
  599. ### Analyze Token Usage by Model
  600. **Natural Language:** _"How many tokens did we use for each model today?"_
  601. **Tool Call:** `get_llm_usage`
  602. ```json
  603. {
  604. "start_time": "2024-01-15T00:00:00Z",
  605. "end_time": "2024-01-15T23:59:59Z",
  606. "service_name": "my-app"
  607. }
  608. ```
  609. **Response:**
  610. ```json
  611. {
  612. "summary": {
  613. "total_tokens": 125430,
  614. "prompt_tokens": 82140,
  615. "completion_tokens": 43290,
  616. "request_count": 487
  617. },
  618. "by_model": {
  619. "gpt-4": {
  620. "total_tokens": 85200,
  621. "request_count": 156
  622. },
  623. "gpt-3.5-turbo": {
  624. "total_tokens": 40230,
  625. "request_count": 331
  626. }
  627. }
  628. }
  629. ```
  630. ---
  631. ### Find Traces with Errors
  632. **Natural Language:** _"Show me all errors from the last hour"_
  633. **Tool Call:** `find_errors`
  634. ```json
  635. {
  636. "start_time": "2024-01-15T14:00:00Z",
  637. "service_name": "my-app",
  638. "limit": 10
  639. }
  640. ```
  641. **Response:**
  642. ```json
  643. {
  644. "errors": [
  645. {
  646. "trace_id": "def456...",
  647. "service_name": "my-app",
  648. "error_message": "RateLimitError: Too many requests",
  649. "error_type": "openai.error.RateLimitError",
  650. "timestamp": "2024-01-15T14:23:15Z"
  651. }
  652. ],
  653. "count": 1
  654. }
  655. ```
  656. ---
  657. ### Compare Model Performance
  658. **Natural Language:** _"What's the performance difference between GPT-4 and Claude?"_
  659. **Tool Call 1:** `get_llm_model_stats` for gpt-4
  660. ```json
  661. {
  662. "model_name": "gpt-4",
  663. "start_time": "2024-01-15T00:00:00Z"
  664. }
  665. ```
  666. **Tool Call 2:** `get_llm_model_stats` for claude-3-opus
  667. ```json
  668. {
  669. "model_name": "claude-3-opus-20240229",
  670. "start_time": "2024-01-15T00:00:00Z"
  671. }
  672. ```
  673. ---
  674. ### Investigate High Token Usage
  675. **Natural Language:** _"Which requests used the most tokens today?"_
  676. **Tool Call:** `get_llm_expensive_traces`
  677. ```json
  678. {
  679. "limit": 10,
  680. "start_time": "2024-01-15T00:00:00Z",
  681. "min_tokens": 5000
  682. }
  683. ```
  684. ---
  685. ## Common Workflows
  686. ### Cost Optimization
  687. 1. **Identify expensive operations:**
  688. ```
  689. Use get_llm_expensive_traces to find high-token requests
  690. ```
  691. 2. **Analyze by model:**
  692. ```
  693. Use get_llm_usage to see which models are costing the most
  694. ```
  695. 3. **Investigate specific traces:**
  696. ```
  697. Use get_trace with the trace_id to see exact prompts/responses
  698. ```
  699. ### Performance Debugging
  700. 1. **Find slow operations:**
  701. ```
  702. Use get_llm_slow_traces to identify latency issues
  703. ```
  704. 2. **Check for errors:**
  705. ```
  706. Use find_errors to see failure patterns
  707. ```
  708. 3. **Analyze finish reasons:**
  709. ```
  710. Use get_llm_model_stats to see if responses are being truncated
  711. ```
  712. ### Model Adoption Tracking
  713. 1. **Discover models in use:**
  714. ```
  715. Use list_llm_models to see all models being called
  716. ```
  717. 2. **Compare model statistics:**
  718. ```
  719. Use get_llm_model_stats for each model to compare performance
  720. ```
  721. 3. **Identify shadow AI:**
  722. ```
  723. Look for unexpected models or services in list_llm_models results
  724. ```
  725. ---
  726. ## Development
  727. ### Running Tests
  728. ```bash
  729. # With UV
  730. uv run pytest
  731. # With coverage
  732. uv run pytest --cov=openllmetry_mcp --cov-report=html
  733. # With pip
  734. pytest
  735. ```
  736. ### Code Quality
  737. ```bash
  738. # Format code
  739. uv run ruff format .
  740. # Lint
  741. uv run ruff check .
  742. # Type checking
  743. uv run mypy src/
  744. ```
  745. ## Troubleshooting
  746. ### Backend Connection Issues
  747. ```bash
  748. # Test backend connectivity
  749. curl http://localhost:16686/api/services # Jaeger
  750. curl http://localhost:3200/api/search/tags # Tempo
  751. ```
  752. ### Authentication Errors
  753. Make sure your API key is set correctly:
  754. ```bash
  755. export BACKEND_API_KEY=your_key_here
  756. # Or use --api-key CLI flag
  757. opentelemetry-mcp --api-key your_key_here
  758. ```
  759. ### No Traces Found
  760. - Check time range (use recent timestamps)
  761. - Verify service names with `list_services`
  762. - Check backend has traces: `curl http://localhost:16686/api/services`
  763. - Try searching without filters first
  764. ### Token Usage Shows Zero
  765. - Ensure your traces have OpenLLMetry instrumentation
  766. - Check that `gen_ai.usage.*` attributes exist in spans
  767. - Verify with `get_trace` to see raw span attributes
  768. ## Future Enhancements
  769. - [ ] Cost calculation with built-in pricing tables
  770. - [ ] Model performance comparison tools
  771. - [ ] Prompt pattern analysis
  772. - [ ] MCP resources for common queries
  773. - [ ] Caching layer for frequent queries
  774. - [ ] Support for additional backends (SigNoz, ClickHouse)
  775. ## Contributing
  776. Contributions are welcome! Please ensure:
  777. 1. All tests pass: `pytest`
  778. 2. Code is formatted: `ruff format .`
  779. 3. No linting errors: `ruff check .`
  780. 4. Type checking passes: `mypy src/`
  781. ## License
  782. Apache 2.0 License - see LICENSE file for details
  783. ## Related Projects
  784. - [OpenLLMetry](https://github.com/traceloop/openllmetry) - OpenTelemetry instrumentation for LLMs
  785. - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
  786. - [Claude Desktop](https://claude.ai/download) - AI assistant with MCP support
  787. ## Support
  788. For issues and questions:
  789. - GitHub Issues: https://github.com/traceloop/opentelemetry-mcp-server/issues
  790. - PyPI Package: https://pypi.org/project/opentelemetry-mcp/
  791. - Traceloop Community: https://traceloop.com/slack

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.