trace

PromptLayer Claude Code Plugin

See every Claude Code session as structured traces in PromptLayer — user messages, assistant responses, tool calls, and token usage, all captured automatically.

Quick Start

1. Install

claude plugin marketplace add MagnivOrg/promptlayer-claude-plugins
claude plugin install trace@promptlayer-claude-plugins

2. Configure

Run the setup script from the project where you want tracing enabled:

$HOME/.claude/plugins/marketplaces/promptlayer-claude-plugins/plugins/trace/setup.sh

You will be prompted for your PromptLayer API key. You can find or create one at dashboard.promptlayer.com.

3. Verify

1. Start Claude Code: claude
2. Send a prompt
3. Check your traces at dashboard.promptlayer.com

What Gets Traced

The plugin hooks into Claude Code's lifecycle and emits OTLP/HTTP JSON spans for:

• Sessions — one root span per Claude Code session
• LLM calls — model, token counts, prompts, and completions
• Tool calls — tool name, input, and output

Prerequisites

• Claude Code CLI installed
• A PromptLayer account and API key (dashboard.promptlayer.com)
• python3 available in your shell
• macOS or Linux (tested on Ubuntu)

Configuration

The setup script writes ~/.claude/settings.json with:

Variable	Purpose	Default
TRACE_TO_PROMPTLAYER	Enable/disable tracing	true
PROMPTLAYER_API_KEY	Your API key	(required)
PROMPTLAYER_OTLP_ENDPOINT	OTLP ingestion endpoint	https://api.promptlayer.com/v1/traces
PROMPTLAYER_CC_DEBUG	Enable debug logging	false

Because this file lives in your home directory, your API key stays out of version control and tracing is enabled across all projects.

OTLP-Native Tracing

This plugin is OpenTelemetry (OTLP/HTTP JSON) compatible:

• Open standard — traces follow the OTLP specification, not a vendor-specific format
• Portable — swap or fan-out to any OTLP-compatible backend (Datadog, Honeycomb, Grafana Tempo, etc.) by changing one endpoint URL
• No SDK lock-in — the plugin sends ExportTraceServiceRequest payloads directly over OTLP/HTTP JSON using the Python standard library; no proprietary client libraries required

Troubleshooting

See docs/troubleshooting.md.

Local Development

Install Python dev tooling with:

uv sync --extra dev

make dev        # Symlink repo as marketplace source, install plugin, run setup
make uninstall  # Remove local install and cleanup artifacts
make test       # Validate manifests + lint + pytest unit tests + fixture replay
make smoke      # E2E smoke test (requires ANTHROPIC_API_KEY)