Crate rig_tap 

Emits uniform telemetry for Rig agents and companion crates.

rig-tap defines a stable, versioned ObservabilityEvent stream for prompt, tool, context, memory, and dispatch lifecycle events. Producer crates can use the same event vocabulary whether the event came from a Rig agent hook, rig-compose dispatch, rig-memvid memory behavior, or host application code.

See the crate README for the full schema and consumer recipe. The two consumer-facing types are:

• TelemetryHook — implements rig::agent::PromptHook and emits prompt.* and tool.* events.
• ObservedMemory — wraps any rig::memory::ConversationMemory and emits context.sampled on every load.

Plus ChainedHook for composing two PromptHooks on a single agent.

Wire format

All events are emitted as a single tracing::info! event on the EVENT_TARGET target ("rig_tap"). The string field event carries the JSON-encoded ObservabilityEvent, while scalar rig_tap.* fields expose kind, conversation_id, version, tick, and occurred_at_millis for OpenTelemetry collector routing and indexing without JSON parsing.

Subscriber sizing

Emission is synchronous: every event runs serde + the registered layers on the calling task. Per-request hot paths (every prompt, every tool call, every memory load) call into the tracing dispatcher directly. For production deployments — especially ones that ship events off-host — wire a non-blocking sink (e.g. tracing_appender::non_blocking or a bounded channel feeding an async exporter) so a slow consumer can’t backpressure the agent. In-process counters and the bundled doc-test layer are fine synchronous.

Example

use rig_tap::{TelemetryHook, ObservedMemory};
use rig::memory::InMemoryConversationMemory;

let memory = ObservedMemory::new(InMemoryConversationMemory::new());
let hook = TelemetryHook::<M>::with_defaults("gpt-4o", "thread-1");
// agent.memory(memory).with_hook(hook)

Re-exports

pub use emit::EVENT_TARGET;

pub use emit::build_event;

pub use emit::emit;

pub use emit::emit_kind;

pub use emit::try_emit;

pub use extract::extract_event;

Modules

emit

Tracing transport for ObservabilityEvent.

extract

Extraction helpers for decoding emitted observability events.

Structs

ChainedHook

Combine two PromptHooks into one. See module docs for combination semantics.

EventFilter

Predicate used by EventQuery to select observability events.

EventQuery

Immutable query view over a snapshot of ObservabilityEvent values.

ObservabilityEvent

A single observability event with envelope metadata.

ObservedMemory

Wraps any ConversationMemory and emits a context.sampled event on every load. append and clear pass through unchanged.

ScalarFields

Per-variant scalar correlation fields surfaced as direct tracing attributes alongside the JSON event blob. See EventKind::scalar_fields.

TelemetryHook

Per-request hook that emits structured observability events from the five PromptHook lifecycle methods.

TelemetryHookConfig

Conversation identifier to stamp on emitted events when the agent runtime does not surface one to the hook. The Rig PromptHook signature does not currently propagate the conversation ID, so the hook stamps events with a constant chosen by the caller (typically "default" for single-thread agents, or a unique value per agent instance for multi-thread setups).

Enums

Error

Errors produced when serializing or processing observability events.

EventKind

Payload variants. Tagged on the wire as "kind": "<dotted.name>".

Constants

PAYLOAD_TRUNCATE_BYTES

Maximum byte length of inline args_json / result_json payloads before they are truncated and marked with "truncated": true.

SCHEMA_VERSION

Current schema version. Bumped on breaking changes to the wire format.

Functions

truncate_utf8

Truncate a UTF-8 string to at most max_bytes, returning the (possibly truncated) string and a flag indicating whether truncation occurred.

Type Aliases

ConversationIdResolver

Caller-supplied resolver for the conversation ID stamped on emitted events. Consulted on every emission; when it returns Some(id), that value wins over TelemetryHookConfig::conversation_id.

ModelResolver

Caller-supplied resolver that pulls the actual model identifier out of a provider response. Useful for routed providers (OpenRouter, Bedrock model-routing, vendor multi-model endpoints) where the model recorded at hook construction is a logical alias and the response’s raw payload carries the concrete model that served the request.