Crate rig_tap 

Backend-agnostic observability event schema and taps for Rig.

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") with a single string field event carrying the JSON-encoded ObservabilityEvent. Consumers attach a tracing_subscriber::Layer filtered to that target.

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.

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.

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.