@ultrathink-solutions/openclaw-logfire

Pydantic Logfire observability plugin for OpenClaw.

Full agent lifecycle tracing aligned with OTEL GenAI semantic conventions — tool calls, token metrics, error stack traces, and optional distributed tracing across services.

Real-world context: We built this plugin as part of deploying OpenClaw into production on the Ultrathink Axon platform. The architecture and design decisions are detailed in that post.

Quickstart

npm install @ultrathink-solutions/openclaw-logfire

Set your Logfire write token:

export LOGFIRE_TOKEN="your-token"

Add to openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw-logfire": {
        "enabled": true,
        "config": {}
      }
    }
  }
}

Restart OpenClaw. That's it — traces appear in your Logfire dashboard.

What You Get

Span Hierarchy

Every agent invocation produces a trace tree:

invoke_agent my-agent                (root span, cumulative tokens)
  |-- gen_ai.chat anthropic          (LLM call: model, input/output tokens)
  |-- execute_tool Read              (file read)
  |-- execute_tool exec              (shell command)
  |-- gen_ai.chat anthropic          (LLM call: model, input/output tokens)
  |-- execute_tool Write             (file write)
  |-- gen_ai.chat anthropic          (LLM call: model, input/output tokens)

Attributes (OTEL GenAI Semantic Conventions)

| Attribute | Span | Example | Description | |-----------|------|---------|-------------| | gen_ai.operation.name | All | invoke_agent | Operation type | | gen_ai.agent.name | Agent | my-agent | Agent identifier | | gen_ai.conversation.id | Agent | session_abc123 | Session key | | gen_ai.request.model | Agent, LLM | claude-sonnet-4-5-20250929 | Model name | | gen_ai.response.model | Agent, LLM | claude-sonnet-4-5-20250929 | Response model | | gen_ai.provider.name | Agent, LLM | anthropic | LLM provider | | gen_ai.usage.input_tokens | Agent, LLM | 1024 | Input tokens (cumulative on agent) | | gen_ai.usage.output_tokens | Agent, LLM | 512 | Output tokens (cumulative on agent) | | openclaw.usage.cache_read_tokens | Agent, LLM | 8192 | Cached prompt tokens read | | openclaw.usage.cache_write_tokens | Agent, LLM | 4096 | Cached prompt tokens written | | gen_ai.tool.name | Tool | Read | Tool being called | | gen_ai.tool.call.id | Tool | call_abc123 | Unique tool call identifier | | gen_ai.tool.call.arguments | Tool | {"path": "/..."} | Tool input (opt-in) | | error.type | Agent | AgentError | Error classification | | openclaw.workspace | Agent | my-agent | Workspace name | | openclaw.channel | Agent | slack | Message source |

Metrics

| Metric | Type | Description | |--------|------|-------------| | gen_ai.client.token.usage | Histogram | Token counts by type (input/output) | | gen_ai.client.operation.duration | Histogram | Agent invocation latency (seconds) |

Error Tracing

Agent-level errors are captured on the root invoke_agent span with error.type and error status. Errors from tool failures propagate up so the agent span is marked as errored.

Configuration

All settings are optional. Sensible defaults work out of the box.

{
  "plugins": {
    "entries": {
      "openclaw-logfire": {
        "enabled": true,
        "config": {
          // Logfire project (enables clickable trace links in logs)
          "projectUrl": "https://logfire.pydantic.dev/myorg/myproject",
          "region": "us",           // "us" or "eu"
          "environment": "production",
          "serviceName": "openclaw-agent",

          // GenAI provider name for OTEL compliance
          "providerName": "anthropic",

          // Trace depth controls
          "captureToolInput": true,       // Record tool arguments
          "captureToolOutput": false,     // Record tool results (verbose)
          "toolInputMaxLength": 2048,     // Truncation limit
          "captureStackTraces": true,     // Stack traces on errors
          "captureMessageContent": false, // Record message text (privacy)
          "redactSecrets": true,          // Strip API keys from tool args

          // Distributed tracing (opt-in)
          "distributedTracing": {
            "enabled": false,
            "urlPatterns": ["https://api.mycompany.com/*"]
          },

          // Metrics
          "enableMetrics": true,

          // Trace links
          "enableTraceLinks": true
        }
      }
    }
  }
}

Environment Variables

| Variable | Description | |----------|-------------| | LOGFIRE_TOKEN | Logfire write token (required) | | LOGFIRE_ENVIRONMENT | Deployment environment fallback | | LOGFIRE_PROJECT_URL | Project URL fallback | | LOGFIRE_PROVIDER_NAME | Provider name fallback |

Secret Redaction

When redactSecrets: true (default), the plugin strips values matching common patterns before recording tool arguments:

• API keys (api_key: sk_live_...)
• Platform tokens (ghp_, gho_, glpat_, xoxb-, etc.)
• JWTs (eyJ...)
• Bearer tokens, passwords, credentials

Distributed Tracing

Connect OpenClaw traces to your backend services. When enabled, the plugin injects traceparent headers into HTTP calls made by exec/Bash tools.

{
  "distributedTracing": {
    "enabled": true,
    "injectIntoCommands": true,      // Add traceparent to curl/wget/httpie
    "extractFromWebhooks": true,     // Extract traceparent from inbound webhooks
    "urlPatterns": [                 // Only inject for matching URLs
      "https://api.mycompany.com/*",
      "http://localhost:8000/*"
    ]
  }
}

This produces connected traces across services:

OpenClaw: invoke_agent my-agent
  |-- execute_tool exec (curl POST /api/data)
       |-- [Your Backend] POST /api/data
            |-- database query
            |-- downstream service call

Your backend must support W3C trace context extraction (most frameworks do: FastAPI with Logfire, Express with OTEL, etc.).

Architecture

openclaw-logfire/src/
  index.ts              Plugin entry point + hook wiring
  config.ts             Typed configuration with defaults
  otel.ts               OTEL SDK initialization (Logfire OTLP)
  hooks/
    before-agent-start  invoke_agent span creation
    llm-input           gen_ai.chat span creation (per LLM call)
    llm-output          LLM span close + token metrics + accumulation
    before-tool-call    execute_tool span + context propagation
    tool-result-persist Tool span close + result capture
    agent-end           Span close + cumulative tokens + metrics
    message-received    Channel attribution + inbound context
  context/
    span-store          Session -> active spans (LIFO tool stack, LLM spans)
    propagation         W3C traceparent inject/extract
  metrics/
    genai-metrics       Token usage + operation duration histograms
  events/
    inference-details   Opt-in inference operation event

OpenClaw Hooks Used

| Hook | Purpose | |------|---------| | before_agent_start | Create root invoke_agent span | | llm_input | Create gen_ai.chat child span per LLM call | | llm_output | Close LLM span, record token usage metrics | | before_tool_call | Create execute_tool child span | | tool_result_persist | Close tool span, record result size | | agent_end | Close spans, set cumulative tokens, emit metrics | | message_received | Enrich with channel info |

Requires OpenClaw >= 2026.2.1 (before_tool_call and llm_input/llm_output hooks).

Development

git clone https://github.com/Ultrathink-Solutions/openclaw-logfire
cd openclaw-logfire
npm install
npm run typecheck
npm test

Local testing with OpenClaw

# Symlink into OpenClaw extensions
ln -s $(pwd) ~/.openclaw/extensions/openclaw-logfire

# Or add to openclaw.json
# "plugins": { "load": { "paths": ["./path/to/openclaw-logfire"] } }

export LOGFIRE_TOKEN="your-write-token"
openclaw restart
openclaw plugins list  # Should show "openclaw-logfire" as enabled

Built By

Ultrathink Solutions — production-grade AI agent infrastructure. We help teams close the gap between AI demos and production systems.

• We Put OpenClaw Into Production in a Weekend — the architecture behind this plugin
• The AI Execution Gap — why most AI projects stall between POC and production

License

MIT