{"id":32023565,"url":"https://github.com/technickai/claude_telemetry","last_synced_at":"2026-01-20T17:35:43.126Z","repository":{"id":318759460,"uuid":"1076378311","full_name":"TechNickAI/claude_telemetry","owner":"TechNickAI","description":"Run claude code with tracing via open telemetry for observability","archived":false,"fork":false,"pushed_at":"2025-10-15T02:45:24.000Z","size":188,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-15T02:52:36.806Z","etag":null,"topics":["claude","claude-agent-sdk","claude-code","claude-telemetry"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TechNickAI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-14T19:19:50.000Z","updated_at":"2025-10-15T02:00:01.000Z","dependencies_parsed_at":"2025-10-15T06:48:22.691Z","dependency_job_id":"a7e41186-0731-4e67-89cc-59f644d6c708","html_url":"https://github.com/TechNickAI/claude_telemetry","commit_stats":null,"previous_names":["technickai/claude-telemetry"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/TechNickAI/claude_telemetry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechNickAI%2Fclaude_telemetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechNickAI%2Fclaude_telemetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechNickAI%2Fclaude_telemetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechNickAI%2Fclaude_telemetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TechNickAI","download_url":"https://codeload.github.com/TechNickAI/claude_telemetry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechNickAI%2Fclaude_telemetry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280706800,"owners_count":26376971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-23T02:00:06.710Z","response_time":142,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-agent-sdk","claude-code","claude-telemetry"],"created_at":"2025-10-16T09:52:24.730Z","updated_at":"2026-01-20T17:35:43.118Z","avatar_url":"https://github.com/TechNickAI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Observability for Claude Code\n\n[![CI](https://github.com/TechNickAI/claude_telemetry/actions/workflows/ci.yml/badge.svg)](https://github.com/TechNickAI/claude_telemetry/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n\n`claude_telemetry` wraps the Claude Code CLI with full observability. Every tool call,\ntoken count, and cost flows to your OTEL backend as structured traces.\n\n## The Problem\n\nClaude Code works beautifully in your terminal. But when you run agents headless—in\nCI/CD, cron jobs, production, or remote servers—you lose visibility into what's\nhappening. You can't see which tools were called, don't know token usage or costs, have\nno context when debugging failures, and can't optimize without re-running locally.\n\nHeadless environments lack the rich console output you get during development.\n\n## The Solution\n\n`claude_telemetry` is a thin wrapper around the Claude Code CLI that adds observability.\nIt passes through all Claude Code flags unchanged while capturing execution traces.\nWorks with any OTEL backend—Logfire, Datadog, Honeycomb, Grafana. See exactly what\nhappened in production, debug remote failures without local reproduction, and track\ncosts to optimize expensive workflows.\n\nYour agents become observable whether local or headless.\n\n## Quick Start\n\nThe simplest way to add observability: swap `claude` for `claudia` on the command line.\n\n```bash\n# Before\nclaude code \"Analyze my project and suggest improvements\"\n\n# After - same command, now with observability\nclaudia \"Analyze my project and suggest improvements\"\n```\n\nThat's it. Every flag you use with `claude code` works with `claudia`. The behavior is\nidentical, but now you get full traces in your observability platform.\n\n## For Developers\n\nIf you're already using `claude code` in your workflow, switching to `claudia` gives you\ninstant observability with zero behavior changes.\n\n**Command-line usage:**\n\n```bash\n# Your existing workflow\nclaude code --model opus \"Refactor this module\"\n\n# Same command, now observable\nclaudia --model opus \"Refactor this module\"\n```\n\n**In scripts and automation:**\n\n```bash\n#!/bin/bash\n# CI/CD, cron jobs, or automation scripts\n\n# Before - no visibility into what happened\nclaude code \"Run tests and fix any failures\"\n\n# After - full traces in your observability platform\nclaudia \"Run tests and fix any failures\"\n```\n\n**The result:**\n\nWhen you use `claudia`, you get the exact same output in your terminal as `claude code`.\nBut now your observability platform shows every tool call, token count, cost, and\ntiming. Debug headless failures, track production costs, and optimize expensive\nworkflows—all without changing how you work.\n\n### Installation\n\n```bash\n# Basic installation - works with any OTEL backend\npip install claude_telemetry\n\n# Or with Logfire support for enhanced LLM telemetry\npip install \"claude_telemetry[logfire]\"\n\n# Or with Sentry for LLM monitoring with error tracking\npip install claude_telemetry sentry-sdk\n```\n\n### For Python Scripts\n\nAdd one line to your code:\n\n```python\nfrom claude_telemetry import run_agent_with_telemetry\n\n# Instead of using Claude SDK directly, use this wrapper:\nawait run_agent_with_telemetry(\n    prompt=\"Analyze my project and suggest improvements\",\n)\n```\n\n### Configure Your Backend\n\nSame configuration for CLI and Python:\n\n```bash\n# For Logfire (get token from logfire.pydantic.dev)\nexport LOGFIRE_TOKEN=\"your-token\"\n\n# For Sentry (get DSN from sentry.io)\nexport SENTRY_DSN=\"https://your-key@sentry.io/project-id\"\n\n# Or for any OTEL backend\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"https://your-otel-endpoint.com\"\nexport OTEL_EXPORTER_OTLP_HEADERS=\"authorization=Bearer your-token\"\n```\n\nThat's it. Your agent's telemetry is now flowing to your observability platform.\n\n## Usage Examples\n\n### Headless/Production Use Case\n\nThe main use case: running agents in environments where you can't see console output.\n\n```python\n# In your CI/CD, cron job, or production script:\nfrom claude_telemetry import run_agent_with_telemetry\n\nawait run_agent_with_telemetry(\n    prompt=\"Analyze the latest logs and create a report\",\n    extra_args={\"model\": \"sonnet\"},\n)\n```\n\nYour observability dashboard shows which tools were called, what errors occurred, how\nmany tokens were used, and the total cost of the operation.\n\n### Local Development with Visibility\n\nEven during local development, seeing traces helps you understand agent behavior:\n\n```python\nfrom claude_telemetry import run_agent_with_telemetry\n\n# Your normal Claude Code workflow, now with observability\nawait run_agent_with_telemetry(\n    prompt=\"Refactor the authentication module\",\n)\n```\n\n**With any OTEL backend:**\n\n```python\nfrom opentelemetry import trace\nfrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\n\nfrom claude_telemetry import run_agent_with_telemetry\n\n# Configure your OTEL backend\nprovider = TracerProvider()\nprocessor = BatchSpanProcessor(\n    OTLPSpanExporter(\n        endpoint=\"https://api.honeycomb.io/v1/traces\",\n        headers={\"x-honeycomb-team\": \"your_api_key\"},\n    )\n)\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# Run with telemetry\nawait run_agent_with_telemetry(\n    prompt=\"Your task here\",\n)\n```\n\n### CLI Usage\n\nThe `claudia` CLI passes all Claude Code flags through unchanged while adding\nobservability:\n\n```bash\n# Basic usage - just like `claude code`\nclaudia \"Analyze my recent emails and create a summary\"\n\n# Pass any Claude Code flag\nclaudia --model opus \"Refactor this module\"\nclaudia --permission-mode bypassPermissions \"Run the tests\"\nclaudia --debug \"Why is this failing?\"\n\n# Combine multiple flags - all forward to Claude Code\nclaudia --model haiku --permission-mode bypassPermissions \"Quick task\"\n```\n\nThe `claudia` command accepts the same flags as `claude code`. It wraps the CLI with\ntelemetry hooks that capture execution without changing behavior. Configure your\nobservability backend via environment variables (same as library usage).\n\n## What Gets Captured\n\nEvery agent run creates a full trace showing exactly what happened:\n\n**Per execution:**\n\n- 📝 Prompt and system instructions\n- 🤖 Model used\n- 🔢 Token counts (input/output/total)\n- 💰 Cost in USD\n- 🔧 Number of tool calls\n- ⏱️ Execution time\n- ❌ Any errors or failures\n\n**Per tool call:**\n\n- Tool name (Read, Write, Bash, etc.)\n- Tool inputs\n- Tool outputs\n- Individual execution time\n- Success/failure status\n\nThis gives you complete visibility into what your agent did, why it failed, and how much\nit cost.\n\n## Span Hierarchy\n\n```\nclaude.agent.run (parent span)\n  ├─ user.prompt (event)\n  ├─ tool.read (child span)\n  │   ├─ tool.input (attribute)\n  │   └─ tool.output (attribute)\n  ├─ tool.write (child span)\n  │   ├─ tool.input (attribute)\n  │   └─ tool.output (attribute)\n  └─ agent.completed (event)\n```\n\n## Backend-Specific Features\n\n### Logfire\n\nWhen using Logfire, the package enables LLM-specific UI features. Spans tagged with\n`LLM` show in Logfire's LLM UI with request/response formatted for token visualization\nand tool calls displayed as structured data. Enhanced formatting includes emoji\nindicators (🤖 for agents, 🔧 for tools, ✅ for completion), proper nesting in console\noutput, and readable span titles showing task descriptions instead of generic \"Message\nwith model X\" text.\n\nThis happens automatically when `LOGFIRE_TOKEN` is set.\n\n### Sentry\n\nWhen using Sentry, the package integrates with Sentry's AI Monitoring features. Spans\ninclude `gen_ai.*` attributes that appear in Sentry's AI Performance dashboard. You get\nfull LLM trace visualization showing token usage, costs, model performance, and tool\nexecution alongside Sentry's error tracking and performance monitoring.\n\nKey features:\n\n- **AI Performance Dashboard**: View LLM metrics by model, operation, and pipeline\n- **Token Usage Tracking**: Monitor input/output tokens with cost analysis\n- **Error Context**: LLM errors include full trace context (prompt, model, tokens)\n- **Tool Execution Visibility**: See which tools were called and their results\n\nSet `SENTRY_DSN` and optionally configure:\n\n```bash\nexport SENTRY_ENVIRONMENT=\"production\"        # Environment name\nexport SENTRY_TRACES_SAMPLE_RATE=\"1.0\"        # Trace sampling (0.0-1.0)\n```\n\nView traces at: Sentry Dashboard → Performance → AI Monitoring\n\nWith other backends, you get standard OTEL spans.\n\n## Configuration\n\n### Environment Variables\n\n**Logfire:**\n\n```bash\nexport LOGFIRE_TOKEN=\"your_token\"  # Get from logfire.pydantic.dev\n```\n\n**Sentry:**\n\n```bash\nexport SENTRY_DSN=\"https://your-key@sentry.io/project-id\"\nexport SENTRY_ENVIRONMENT=\"production\"           # Optional\nexport SENTRY_TRACES_SAMPLE_RATE=\"1.0\"          # Optional (0.0-1.0)\n```\n\n**Any OTEL backend:**\n\n```bash\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"https://your-endpoint.com/v1/traces\"\nexport OTEL_EXPORTER_OTLP_HEADERS=\"authorization=Bearer your-token\"\nexport OTEL_SERVICE_NAME=\"my-claude-agents\"  # Optional, defaults to \"claude-agents\"\n```\n\n**Debug mode:**\n\n```bash\nexport OTEL_DEBUG=1  # Verbose telemetry logging\n```\n\n### Programmatic Configuration\n\nFor more control, configure the tracer provider yourself:\n\n```python\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom claude_telemetry import run_agent_with_telemetry\n\nprovider = TracerProvider()\n# ... add your processors ...\ntrace.set_tracer_provider(provider)\n\n# Pass it to the runner\nawait run_agent_with_telemetry(\n    prompt=\"Your task\",\n    tracer_provider=provider,\n)\n```\n\n### MCP Servers\n\nMCP servers work the same way as with `claude code`. Configure them using\n`claude mcp add`:\n\n```bash\n# Add an MCP server using Claude's config system\nclaude mcp add mcp-hubby --url https://connect.mcphubby.ai/mcp\n\n# Or use project-local .mcp.json (same format as Claude Code)\n# The wrapper loads user, project, and local settings automatically\n```\n\nThe wrapper passes `setting_sources=[\"user\", \"project\", \"local\"]` to the SDK, which\nmeans it loads MCP servers from the same places `claude code` does. No special\nconfiguration needed—if it works with `claude code`, it works with `claudia`.\n\n**Need help with MCP servers?** Check out [MCP Hubby](https://mcphubby.ai)—a single\ngateway to all your services (Gmail, Notion, Slack, etc.) that reduces context usage by\n95%. One MCP connection instead of dozens.\n\n## API\n\n```python\nasync def run_agent_with_telemetry(\n    prompt: str,\n    extra_args: dict[str, str | None] | None = None,\n    tracer_provider: TracerProvider | None = None,\n    debug: bool = False,\n)\n```\n\n**Parameters:**\n\n- `prompt` - Task for Claude Code\n- `extra_args` - Claude Code CLI flags as a dictionary. Any flag you can pass to\n  `claude code` works here (e.g.,\n  `{\"model\": \"opus\", \"permission-mode\": \"bypassPermissions\"}`)\n- `tracer_provider` - Custom OTEL tracer provider (optional, auto-detected if not\n  provided)\n- `debug` - Enable Claude CLI debug mode\n\n**Returns:**\n\n- Nothing directly. Prints Claude's responses to console and sends all telemetry via\n  OTEL.\n\n**How it works:**\n\nThe function wraps the Claude Code SDK with observability hooks. It converts\n`extra_args` to CLI flags and passes them through unchanged. The SDK runs exactly as if\nyou called `claude code` directly, but telemetry hooks capture every event.\n\n**Example:**\n\n```python\nimport asyncio\nfrom claude_telemetry import run_agent_with_telemetry\n\nasync def main():\n    # Any flag from `claude code --help` works in extra_args\n    await run_agent_with_telemetry(\n        prompt=\"List Python files and create a summary\",\n        extra_args={\"model\": \"sonnet\", \"permission-mode\": \"bypassPermissions\"},\n    )\n\nasyncio.run(main())\n```\n\n## How It Works\n\n`claude_telemetry` is a thin observability layer around the Claude Code SDK. It uses the\nSDK's hook system to capture execution without modifying behavior.\n\n**Pass-through architecture:**\n\nThe `extra_args` dictionary passes directly to the Claude Code SDK as CLI flags. When\nyou call `run_agent_with_telemetry(prompt=\"...\", extra_args={\"model\": \"opus\"})`, the SDK\nreceives exactly what `claude code --model opus` would pass. The library doesn't\ninterpret or validate flags—it forwards them unchanged. This means any flag that works\nwith `claude code` works here, including future flags not yet released.\n\n**Observability hooks:**\n\n- `UserPromptSubmit` - Opens parent span, logs prompt\n- `PreToolUse` - Opens child span for tool, captures input\n- `PostToolUse` - Captures output, closes tool span\n- Session completion - Adds final metrics, closes parent span\n\nHooks are async callbacks that run during SDK execution. They capture telemetry data\nwithout blocking or modifying the agent's behavior.\n\n**OTEL export:**\n\n- Spans sent via configured OTEL exporter\n- Attributes follow semantic conventions where applicable\n- Events add context without creating spans\n- Works with any OTEL-compatible backend\n\n**Logfire detection:**\n\n- Checks for `LOGFIRE_TOKEN` environment variable\n- If present, uses Logfire's Python SDK for auto-config\n- Adds LLM-specific formatting and tags\n- Falls back to standard OTEL if token not found\n\n## Architecture Decisions\n\n### Why Pass-Through Instead of Parameters?\n\nEarlier versions exposed individual parameters like `model`, `allowed_tools`, etc. This\ncreated maintenance burden—every new Claude Code flag required updating the wrapper's\nsignature. The pass-through architecture using `extra_args` eliminates this problem.\n\nWhen you pass `extra_args={\"model\": \"opus\"}`, the library converts it to `--model opus`\nand forwards it to the SDK unchanged. The library doesn't know what flags are valid—it\ntrusts the SDK to handle them. This means new Claude Code features work immediately\nwithout updating `claude_telemetry`.\n\nThe CLI uses plain argument parsing to separate observability flags (`--logfire-token`,\n`--otel-endpoint`) from Claude Code flags. Everything else passes through. This keeps\nthe wrapper thin and maintainable.\n\n### Why OpenTelemetry?\n\nOpenTelemetry is the industry standard for observability. Using it means the package\nworks with any observability backend, doesn't lock users into specific vendors,\nintegrates with existing infrastructure, and is future-proof as a CNCF project with wide\nadoption.\n\n### Why Special-Case Logfire and Sentry?\n\nBoth Logfire and Sentry have LLM-specific UI features that benefit from specific span\nformatting. When detected:\n\n- **Logfire**: Uses Logfire's SDK for auto-configuration and LLM UI formatting\n- **Sentry**: Adds `gen_ai.*` attributes for AI Performance dashboard integration\n\nBoth use OpenTelemetry under the hood, so the hook code stays backend-agnostic. The\nadapters just configure the provider and ensure proper attribute formatting for each\nplatform's LLM UI features.\n\n### Why Hooks Instead of Wrappers?\n\nThe Claude SDK provides hooks specifically for observability. Using them captures all\nevents without modifying SDK code, works across SDK updates, maintains clean separation\nof concerns, and requires no monkey-patching.\n\n## Supported Backends\n\n**Tested and working:**\n\n- Logfire (enhanced LLM features)\n- Sentry (AI monitoring with error tracking)\n- Honeycomb\n- Datadog\n- Grafana Cloud\n- Self-hosted OTEL collector\n\n**Should work (standard OTEL):**\n\n- New Relic\n- Elastic APM\n- AWS X-Ray\n- Azure Monitor\n- Any OTLP-compatible endpoint\n\n## Console Output\n\nRegardless of backend, console shows execution:\n\n```\n🤖 Analyze my recent emails and summarize them\n  👤 User prompt submitted\n  🔧 Calling tool: Read\n  ✅ Tool completed: Read\n  🔧 Calling tool: Write\n  ✅ Tool completed: Write\n  🎉 Agent completed\n\nSession completed - Tokens: 145 in, 423 out, Tools called: 2\n```\n\n## Requirements\n\n- Python 3.10 or later\n- `claude-agent-sdk` - Claude Code integration\n- `opentelemetry-api` - OTEL core\n- `opentelemetry-sdk` - OTEL implementation\n- `opentelemetry-exporter-otlp` - OTLP export\n- `logfire` (optional) - Enhanced Logfire features\n\n## Development\n\n```bash\ngit clone https://github.com/TechNickAI/claude_telemetry.git\ncd claude_telemetry\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run example with Logfire\nexport LOGFIRE_TOKEN=\"your_token\"\npython examples/logfire_example.py\n\n# Run example with Honeycomb\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"https://api.honeycomb.io\"\nexport OTEL_EXPORTER_OTLP_HEADERS=\"x-honeycomb-team=your_key\"\npython examples/otel_example.py\n```\n\n## Project Structure\n\n```\nclaude_telemetry/\n  claude_telemetry/\n    __init__.py           # Package exports\n    runner.py             # Async agent runner with observability hooks\n    sync.py               # Sync wrapper for runner\n    hooks.py              # Telemetry hook implementations\n    telemetry.py          # OTEL configuration and setup\n    logfire_adapter.py    # Logfire-specific enhancements\n    sentry_adapter.py     # Sentry-specific configuration\n    cli.py                # CLI entry point with pass-through arg parsing\n    helpers/              # Logger and utilities\n  examples/\n    logfire_example.py    # Logfire usage\n    sentry_example.py     # Sentry LLM monitoring\n    otel_example.py       # Generic OTEL usage\n    honeycomb_example.py  # Honeycomb setup\n  tests/\n    test_telemetry.py     # Core telemetry tests\n    test_cli_parsing.py   # CLI argument pass-through tests\n    test_hooks.py         # Hook behavior tests\n  pyproject.toml          # Package config\n  README.md\n  LICENSE\n```\n\n## Implementation Notes\n\n### Logfire LLM Formatting\n\nWhen Logfire is detected, spans need specific attributes for LLM UI:\n\n```python\n# Standard OTEL span\nspan.set_attribute(\"prompt\", \"...\")\nspan.set_attribute(\"model\", \"...\")\n\n# Logfire LLM enhancement\nspan.set_attribute(\"request_data\", {\n    \"model\": \"sonnet\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"...\"}]\n})\nspan.set_attribute(\"response_data\", {\n    \"message\": {\"role\": \"assistant\", \"content\": \"...\"},\n    \"usage\": {\"input_tokens\": 123, \"output_tokens\": 456}\n})\n```\n\nLogfire's UI parses these attributes to show token flow and LLM-specific visualizations.\n\n### Hook Implementation\n\nHooks must be async and match the signature:\n\n```python\nasync def on_user_prompt_submit(\n    input_data: HookInput,\n    tool_use_id: str | None,\n    context: HookContext\n) -\u003e HookJSONOutput:\n    # Open parent span\n    # Log user prompt\n    return {}  # Can return data to modify flow\n```\n\nRegister hooks in SDK options:\n\n```python\noptions = ClaudeAgentOptions(\n    hooks={\n        \"UserPromptSubmit\": [HookMatcher(matcher=None, hooks=[on_prompt])],\n        \"PreToolUse\": [HookMatcher(matcher=None, hooks=[on_pre_tool])],\n        \"PostToolUse\": [HookMatcher(matcher=None, hooks=[on_post_tool])],\n    }\n)\n```\n\n## FAQ \u0026 Troubleshooting\n\n### Does `claudia` support all Claude Code flags?\n\nYes. The pass-through architecture means any flag that works with `claude code` works\nwith `claudia`. We don't maintain a list of supported flags—we just forward everything\nto the SDK unchanged. This includes flags that don't exist yet. When Anthropic releases\nnew Claude Code features, they work immediately without updating `claude_telemetry`.\n\n### Why not just use Logfire directly?\n\nYou can! But `claude_telemetry` works with any OTEL backend (not just Logfire), provides\npre-configured hooks for Claude agents specifically, captures LLM-specific metrics like\ntokens, costs, and tool calls, and saves you setup time—no need to instrument everything\nmanually.\n\nUse this if you want observability with minimal code changes.\n\n### Does this add latency?\n\nNegligible. Telemetry is async and doesn't block agent execution. Typical overhead:\n\u003c10ms per operation.\n\n### What about streaming responses?\n\nFully supported! Streaming responses are captured and sent to telemetry after\ncompletion.\n\n### Common Issues\n\n**No traces appearing:**\n\n- Check your OTEL endpoint is reachable\n- Verify environment variables are set\n- Check console for error messages about telemetry connection\n\n**Logfire LLM UI not showing:**\n\n- Ensure `LOGFIRE_TOKEN` is set\n- Install the `logfire` extra: `pip install \"claude_telemetry[logfire]\"`\n- Check console for \"Logfire project URL\" to confirm connection\n\n**Agent runs but no telemetry:**\n\n- Make sure you're using `run_agent_with_telemetry()` wrapper\n- Check that backend environment variables are set\n- Try setting `OTEL_DEBUG=1` for verbose logging\n\n**High costs showing in traces:**\n\n- This is valuable data! Use it to optimize your prompts\n- Consider using `haiku` model for cheaper operations\n- Review which tools are being called unnecessarily\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Credits\n\nBuilt for the 100x community.\n\nPackage name: `claude_telemetry` CLI name: `claudia`\n\nBased on OpenTelemetry standards. Enhanced Logfire integration when available.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnickai%2Fclaude_telemetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechnickai%2Fclaude_telemetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnickai%2Fclaude_telemetry/lists"}