Telemetry

The Telemetry primitive defines how agent behavior is observed, measured, and exported for analysis. It is OPTIONAL at all conformance levels and MUST NOT affect core agent functionality — an agent without Telemetry configured MUST behave identically to one with it.

URI pattern: claw://local/telemetry/{name}

Schema

claw: "0.3.0"
kind: Telemetry
metadata:
  name: "observability"
  version: "1.0.0"
spec:
  exporters:
    - type: "otlp"
      endpoint: "https://otel-collector.internal:4318/v1/traces"
      auth:
        secret_ref: "OTEL_API_KEY"
      batch:
        max_size: 1000
        flush_interval_ms: 5000

    - type: "file"
      path: "/var/log/agent/telemetry.jsonl"

  events:
    tool_calls: true
    memory_ops: false
    world_model_ops: false
    planning_ops: false
    swarm_ops: false
    lifecycle: true
    errors: true

  metrics:
    token_usage: true
    cost_usd: false
    latency_histogram: true
    prediction_error: false
    retrieval_hit_rate: false
    plan_revision_count: false

  sampling:
    rate: 1.0                    # 0.0 = off, 1.0 = all events

  redaction:
    strip_arguments: false
    strip_results: false

Key Fields

Field	Required	Description
`exporters`	Yes	At least one exporter destination.
`events`	No	Which event categories to emit.
`metrics`	No	Which metrics to collect.
`sampling`	No	Sampling rate (0.0 to 1.0).
`redaction`	No	Data redaction settings for tool arguments and results.

Exporter Types

Type	Backend	Required Fields	Use Case
`otlp`	OpenTelemetry Collector	`endpoint`	Production — Datadog, Jaeger, Grafana Tempo
`file`	JSONL log file	`path`	Offline environments, local debugging
`sqlite`	SQLite database	`path`	Embedded devices, queryable local storage
`webhook`	HTTP POST endpoint	`endpoint`	Custom integrations, alerting systems
`console`	stdout/stderr	—	Development, CI pipelines

Event Categories

Category	Description	Default
`tool_calls`	Tool invocation details (name, duration, status, error code)	`true`
`memory_ops`	Memory store/query/compact operations	`false`
`world_model_ops`	Predictive model activity (predict, simulate, update)	`false`
`planning_ops`	Plan generation, revision, or conservative fallback decisions	`false`
`swarm_ops`	Swarm delegate/discover/report operations	`false`
`lifecycle`	State machine transitions (INIT, READY, etc.)	`true`
`errors`	All error responses	`true`

Metrics

Metric	Description	Default
`token_usage`	Input/output token counts per provider call	`true`
`cost_usd`	Estimated cost per operation in USD	`false`
`latency_histogram`	Latency histograms for tool calls and provider requests	`true`
`prediction_error`	Divergence between predicted and observed outcomes	`false`
`retrieval_hit_rate`	How often memory retrieval materially helps execution	`false`
`plan_revision_count`	Number of planning passes before final action	`false`

Validation Rules

The exporters array MUST contain at least one entry.
For otlp or webhook exporters, the endpoint field is REQUIRED.
For file or sqlite exporters, the path field is REQUIRED.
The sampling.rate field MUST be a number in the range 0.0 to 1.0 inclusive. Values outside this range MUST be rejected.
The runtime MUST NEVER emit raw prompts, Chain-of-Thought (CoT) content, or provider response bodies in telemetry events, regardless of redaction settings. This is a security invariant.
When redaction.strip_arguments is true, tool call arguments MUST be replaced with a placeholder (e.g., [REDACTED]) in emitted events.

Design Rationale

The Telemetry primitive satisfies Design Principle P7 (Auditable) by providing declarative, structured observability without code changes in the agent. It supports five exporter types covering production, offline, integration, and development scenarios. Telemetry is intentionally OPTIONAL at all conformance levels — observability should enhance, never gate, agent deployment. In CKP 0.3.0, Telemetry can also track planning and prediction quality for runtimes that implement WorldModel-driven behavior. No JSON-RPC methods are defined for Telemetry because it is emit-only: the agent produces events unidirectionally to configured exporters.