Skip to main content
Glama

otel-pocket

ci npm JSR JSR Score Go license

One command local OpenTelemetry collector: npx otel-pocket (or bunx otel-pocket) listens on :4318 for OTLP/JSON traces, renders a live terminal flamegraph, flags SQL N+1 loops, and surfaces gen_ai.* LLM spans (Ollama, OpenAI, Anthropic).

Install

Bun / npm:

bunx otel-pocket
npx otel-pocket

# or install in your project / globally
bun add -d otel-pocket
npm i -D otel-pocket

JSR:

bunx jsr add @kanchingyg/otel-pocket
npx jsr add @kanchingyg/otel-pocket

Go (native binary):

go install github.com/kanchingyg/otel-pocket@latest

The core collector runs in Go (main.go, internal/). TypeScript under src/*.ts is included for npx / bunx / JSR usage and MCP bridge helpers.

Related MCP server: tracehub-mcp

Quick start

npx otel-pocket
bunx otel-pocket
# point your SDK exporter to http://127.0.0.1:4318/v1/traces
npx otel-pocket --mcp

Add to Cursor or Claude Code MCP config:

{
  "mcpServers": {
    "otel-pocket": {
      "command": "npx",
      "args": ["-y", "otel-pocket", "--mcp"]
    }
  }
}

MCP tools

Tool

Purpose

list_recent_traces

Recent traces with duration and error status

inspect_trace_tree

Span tree, critical path, N+1 SQL, and gen_ai metrics (SQL redacted unless verbose or OTEL_POCKET_VERBOSE_MCP=1)

diagnose_slow_trace

Ask a local OpenAI-compatible model (Ollama/LM Studio); loopback-only unless OTEL_POCKET_ALLOW_REMOTE_LLM=1

Set OTEL_POCKET_LLM_URL / OTEL_POCKET_LLM_MODEL for local LLM diagnosis.

Why otel-pocket

Jaeger and desktop viewers require a browser, lack a terminal TUI, and do not ship MCP tools for coding agents. Phoenix and Langfuse are heavy Python/Docker stacks. otel-pocket correlates HTTP, SQL N+1, and gen_ai.* spans in a single zero-config npx, bunx, or go install binary.

MCP Tools Reference

Tool

Mutates

Description

list_recent_traces

false

List recent OTLP traces stored in memory with total duration, span count, and error status.

inspect_trace_tree

false

Render the hierarchical span tree, critical path, collapsed SQL N+1 loops, and gen_ai.* token metrics (SQL/URLs redacted unless verbose: true).

diagnose_slow_trace

false

Send a sanitized trace summary to a loopback Ollama or OpenAI-compatible model for bottleneck analysis.

Editor and Agent Integration

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "otel-pocket": {
      "command": "npx",
      "args": ["-y", "otel-pocket", "--mcp"]
    }
  }
}

Claude Code CLI

claude mcp add otel-pocket -- npx -y otel-pocket --mcp

Programmatic Usage (JSR / TypeScript)

import * as bridge from "jsr:@kanchingyg/otel-pocket/bridge";

Runtime Safety and Guardrails

  • Stdio frame isolation: When --mcp is active, hijackStdoutForMcp() redirects accidental console.log calls to stderr so JSON-RPC 2.0 frames on stdout never corrupt.

  • Read-only by default: Mutating tools (mutates: true) are blocked in --dry-run mode and require explicit --allow-write authorization.

  • Loop breaker: Repeated identical (toolName, args) invocations are hashed with SHA-256 and halted after 3 consecutive repeats to prevent runaway agent loops.

  • Context budget truncation: Tool outputs are middle-truncated (60% head / 40% tail) scaled to the probed local model n_ctx (Ollama /api/show, llama.cpp /props, vLLM /v1/models).

  • Secret redaction and path normalization: AWS keys (AKIA*, ASIA*), bearer tokens, and sk-* keys are scrubbed before returning tool output, and Windows drive paths (C:\...) translate cleanly to /mnt/c/... when WSL mode is enabled.

License

MIT

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables natural language querying and analysis of OpenTelemetry traces, metrics, and logs stored in Elasticsearch/OpenSearch, allowing AI assistants to investigate performance issues, find root causes, and explore system behavior.
    3 npm
    14
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    Connects AI assistants to OpenTelemetry trace backends (Jaeger, Grafana Tempo, Traceloop, Datadog, Sentry, AWS X-Ray, New Relic and Honeycomb) for natural-language trace and span search, error triage, cross-backend correlation, and LLM analytics such as token usage, model performance and the most expensive or slowest traces.
    19
    162 PyPI
    Apache 2.0
  • A
    license
    A
    quality
    B
    maintenance
    Enables local-first observability for MCP agent workflows by recording tool calls, prompts, latency, and token usage in a local SQLite database, and provides tools for inspecting, comparing, exporting, and generating dashboards from traces.
    13
    36 npm
    MIT
  • F
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents and developers to query traces, sessions, exceptions, prompts, datasets, annotation queues, scores, and metrics for local debugging and observability. Runs locally over stdio or HTTP with selective tool-group loading, read-only mode, and compact or file-dump output to control token usage.
    -