Struct TelemetryHook 

pub struct TelemetryHook<M: CompletionModel> { /* private fields */ }

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

M is the CompletionModel used by the agent. The hook is generic so a single rig-tap build can attach to OpenAI, Anthropic, Ollama, etc.

Example

use rig_tap::{TelemetryHook, TelemetryHookConfig};

TelemetryHook::new(TelemetryHookConfig::new("gpt-4o", "thread-1"))

Implementations

impl<M: CompletionModel> TelemetryHook<M>

pub fn new(config: TelemetryHookConfig) -> Self

Build a hook from config.

pub fn with_defaults( model: impl Into<String>, conversation_id: impl Into<String>, ) -> Self

Convenience: build a hook stamping events with model and conversation_id and default truncation.

pub fn with_conversation_id_resolver<F>(self, resolver: F) -> Self

where F: Fn() -> Option<String> + Send + Sync + 'static,

Register a per-request resolver for the conversation ID. The resolver is consulted on every emission; if it returns Some(id), that value is stamped on the event instead of TelemetryHookConfig::conversation_id.

Typical wiring: a tokio::task_local! (or equivalent) set by the host on every request, read by the closure.

pub fn with_model_resolver<F>(self, resolver: F) -> Self

where F: Fn(&CompletionResponse<M::Response>) -> Option<String> + Send + Sync + 'static,

Register a resolver that extracts the concrete model identifier from each CompletionResponse. When the resolver returns Some(model), that value is stamped on prompt.completed instead of TelemetryHookConfig::model.

Use this with routed providers (OpenRouter, Bedrock routing, vendor multi-model endpoints) where the configured model name is a logical alias and the response payload carries the actual model that served the request.

pub fn with_previous_response_id_resolver<F>(self, resolver: F) -> Self

where F: Fn(&CompletionResponse<M::Response>) -> Option<String> + Send + Sync + 'static,

Register a resolver that returns the chain ancestor (previous_response_id) sent to the provider for the current turn. When the resolver returns Some(id), that value is stamped on prompt.completed’s previous_response_id field.

Use this with stateful endpoints — OpenAI Responses, future Anthropic/Google equivalents — where the host runtime tracks the chain (typically in a task-local or session object) and the provider response payload does not echo the value back.

pub fn with_sampling_policy(self, policy: Arc<dyn SamplingPolicy>) -> Self

Install a SamplingPolicy that gates every prompt.* and tool.* emission from this hook. The default policy is AlwaysSample.

Pairing: the hook passes the resolved conversation id as the correlator for prompt.* events and the internal call id for tool.* events. Policies that hash the correlator (such as RatePolicy) therefore keep tool.invoked / tool.completed pairs coherent automatically.

Example

use std::sync::Arc;
use rig_tap::{RatePolicy, TelemetryHook, TelemetryHookConfig};

TelemetryHook::new(TelemetryHookConfig::new("gpt-4o", "thread-1"))
    .with_sampling_policy(Arc::new(
        RatePolicy::new()
            .with_rate("tool.invoked", 0.1)
            .with_rate("tool.completed", 0.1),
    ))

pub fn observe_prompt_error(&self, error: &PromptError)

Observe a failure in the prompt loop. Call this when the agent’s prompt execution returns an error.

pub fn observe_tool_error( &self, tool_name: &str, call_id: &str, error: &dyn Error, )

Observe a failure in a tool invocation. Call this when a tool returns a failure.

Trait Implementations

impl<M: CompletionModel> Clone for TelemetryHook<M>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M: CompletionModel> Debug for TelemetryHook<M>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<M> PromptHook<M> for TelemetryHook<M>

where M: CompletionModel,

async fn on_completion_call( &self, _prompt: &Message, history: &[Message], ) -> HookAction

Called before the prompt is sent to the model

async fn on_completion_response( &self, _prompt: &Message, response: &CompletionResponse<M::Response>, ) -> HookAction

Called after the prompt is sent to the model and a response is received.

async fn on_tool_call( &self, tool_name: &str, tool_call_id: Option<String>, internal_call_id: &str, args: &str, ) -> ToolCallHookAction

Called before a tool is invoked.

async fn on_tool_result( &self, tool_name: &str, tool_call_id: Option<String>, internal_call_id: &str, _args: &str, result: &str, ) -> HookAction

Called after a tool is invoked (and a result has been returned).

fn on_text_delta( &self, _text_delta: &str, _aggregated_text: &str, ) -> impl Future<Output = HookAction> + Send

Called when receiving a text delta (streaming responses only)

fn on_tool_call_delta( &self, _tool_call_id: &str, _internal_call_id: &str, _tool_name: Option<&str>, _tool_call_delta: &str, ) -> impl Future<Output = HookAction> + Send

Called when receiving a tool call delta (streaming_responses_only). tool_name is Some on the first delta for a tool call, None on subsequent deltas.

fn on_stream_completion_response_finish( &self, _prompt: &Message, _response: &<M as CompletionModel>::StreamingResponse, ) -> impl Future<Output = HookAction> + Send

Called after the model provider has finished streaming a text response from their completion API to the client.