use std::future::Future;
use tracing::field::Empty;
use tracing::{Instrument as _, Span};
use crate::error::Result;
#[must_use]
pub fn is_tracing_enabled() -> bool {
tracing::dispatcher::has_been_set()
}
pub fn agent_run_span(agent_name: &str, prompt: &str, model: &str, session_id: &str) -> Span {
let span = tracing::info_span!(
"agent.run",
agent.name = agent_name,
agent.model = model,
agent.prompt_length = prompt.len(),
agent.session_id = Empty,
);
if !session_id.is_empty() {
span.record("agent.session_id", session_id);
}
span
}
pub async fn traced_agent_run<F, Fut, T>(
agent_name: &str,
prompt: &str,
model: &str,
session_id: &str,
f: F,
) -> Result<T>
where
F: FnOnce() -> Fut,
Fut: Future<Output = Result<T>>,
{
let span = agent_run_span(agent_name, prompt, model, session_id);
async move {
let result = f().await;
if let Err(e) = &result {
tracing::error!(error = %e, "agent.run failed");
}
result
}
.instrument(span)
.await
}
pub fn compile_span(agent_name: &str, strategy: &str) -> Span {
let span = tracing::info_span!(
"agent.compile",
agent.name = agent_name,
agent.strategy = Empty,
);
if !strategy.is_empty() {
span.record("agent.strategy", strategy);
}
span
}
pub fn llm_call_span(agent_name: &str, model: &str) -> Span {
tracing::info_span!(
"agent.llm_call",
agent.name = agent_name,
llm.model = model,
llm.prompt_tokens = Empty,
llm.completion_tokens = Empty,
llm.total_tokens = Empty,
)
}
pub fn tool_call_span(agent_name: &str, tool_name: &str, args: Option<&str>) -> Span {
let span = tracing::info_span!(
"agent.tool_call",
agent.name = agent_name,
tool.name = tool_name,
tool.args = Empty,
);
if let Some(args) = args {
let truncated: String = args.chars().take(1000).collect();
span.record("tool.args", truncated.as_str());
}
span
}
pub async fn traced_tool_call<F, Fut, T>(
agent_name: &str,
tool_name: &str,
args: Option<&str>,
f: F,
) -> Result<T>
where
F: FnOnce() -> Fut,
Fut: Future<Output = Result<T>>,
{
let span = tool_call_span(agent_name, tool_name, args);
async move {
let result = f().await;
if let Err(e) = &result {
tracing::error!(error = %e, "agent.tool_call failed");
}
result
}
.instrument(span)
.await
}
pub fn handoff_span(source_agent: &str, target_agent: &str) -> Span {
tracing::info_span!(
"agent.handoff",
handoff.source = source_agent,
handoff.target = target_agent,
)
}
pub fn record_token_usage(
span: &Span,
prompt_tokens: u64,
completion_tokens: u64,
total_tokens: u64,
) {
if prompt_tokens > 0 {
span.record("llm.prompt_tokens", prompt_tokens);
}
if completion_tokens > 0 {
span.record("llm.completion_tokens", completion_tokens);
}
if total_tokens > 0 {
span.record("llm.total_tokens", total_tokens);
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::error::ConductorError;
use std::sync::{Arc, Mutex};
use tracing::field::{Field, Visit};
use tracing::span::{Attributes, Id, Record};
use tracing::subscriber::Subscriber;
#[derive(Default)]
struct RecordingSubscriber {
fields: Arc<Mutex<std::collections::HashMap<String, String>>>,
span_names: Arc<Mutex<Vec<&'static str>>>,
}
struct FieldVisitor<'a>(&'a mut std::collections::HashMap<String, String>);
impl Visit for FieldVisitor<'_> {
fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) {
self.0.insert(field.name().to_owned(), format!("{value:?}"));
}
}
impl Subscriber for RecordingSubscriber {
fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
true
}
fn new_span(&self, span: &Attributes<'_>) -> Id {
self.span_names.lock().unwrap().push(span.metadata().name());
let mut fields = self.fields.lock().unwrap();
span.record(&mut FieldVisitor(&mut fields));
Id::from_u64(1)
}
fn record(&self, _span: &Id, values: &Record<'_>) {
let mut fields = self.fields.lock().unwrap();
values.record(&mut FieldVisitor(&mut fields));
}
fn record_follows_from(&self, _span: &Id, _follows: &Id) {}
fn event(&self, _event: &tracing::Event<'_>) {}
fn enter(&self, _span: &Id) {}
fn exit(&self, _span: &Id) {}
}
#[test]
fn test_agent_run_span_records_expected_fields() {
let fields = Arc::new(Mutex::new(std::collections::HashMap::new()));
let span_names = Arc::new(Mutex::new(Vec::new()));
let subscriber = RecordingSubscriber {
fields: Arc::clone(&fields),
span_names: Arc::clone(&span_names),
};
tracing::subscriber::with_default(subscriber, || {
let _span = agent_run_span("my_agent", "Hello!", "openai/gpt-4o", "sess-1");
});
assert_eq!(span_names.lock().unwrap().as_slice(), ["agent.run"]);
let fields = fields.lock().unwrap();
assert_eq!(fields.get("agent.name").unwrap(), "\"my_agent\"");
assert_eq!(fields.get("agent.model").unwrap(), "\"openai/gpt-4o\"");
assert_eq!(fields.get("agent.session_id").unwrap(), "\"sess-1\"");
}
#[test]
fn test_agent_run_span_omits_session_id_when_empty() {
let fields = Arc::new(Mutex::new(std::collections::HashMap::new()));
let subscriber = RecordingSubscriber {
fields: Arc::clone(&fields),
span_names: Arc::new(Mutex::new(Vec::new())),
};
tracing::subscriber::with_default(subscriber, || {
let _span = agent_run_span("my_agent", "Hello!", "openai/gpt-4o", "");
});
assert!(!fields.lock().unwrap().contains_key("agent.session_id"));
}
#[tokio::test]
async fn test_traced_agent_run_returns_ok_result() {
let result: Result<i32> = traced_agent_run("a", "p", "m", "", || async { Ok(42) }).await;
assert_eq!(result.unwrap(), 42);
}
#[tokio::test]
async fn test_traced_agent_run_propagates_error() {
let result: Result<i32> = traced_agent_run("a", "p", "m", "", || async {
Err(ConductorError::agent("boom"))
})
.await;
result.unwrap_err();
}
#[tokio::test]
async fn test_traced_tool_call_returns_ok_result() {
let result: Result<i32> = traced_tool_call("a", "t", None, || async { Ok(7) }).await;
assert_eq!(result.unwrap(), 7);
}
#[test]
fn test_compile_span_omits_strategy_when_empty() {
let fields = Arc::new(Mutex::new(std::collections::HashMap::new()));
let subscriber = RecordingSubscriber {
fields: Arc::clone(&fields),
span_names: Arc::new(Mutex::new(Vec::new())),
};
tracing::subscriber::with_default(subscriber, || {
let _span = compile_span("a", "");
});
assert!(!fields.lock().unwrap().contains_key("agent.strategy"));
}
#[test]
fn test_compile_span_records_strategy_when_given() {
let fields = Arc::new(Mutex::new(std::collections::HashMap::new()));
let subscriber = RecordingSubscriber {
fields: Arc::clone(&fields),
span_names: Arc::new(Mutex::new(Vec::new())),
};
tracing::subscriber::with_default(subscriber, || {
let _span = compile_span("a", "plan_execute");
});
assert_eq!(
fields.lock().unwrap().get("agent.strategy").unwrap(),
"\"plan_execute\""
);
}
#[test]
fn test_tool_call_span_truncates_args_to_1000_chars() {
let fields = Arc::new(Mutex::new(std::collections::HashMap::new()));
let subscriber = RecordingSubscriber {
fields: Arc::clone(&fields),
span_names: Arc::new(Mutex::new(Vec::new())),
};
let long_args = "x".repeat(2000);
tracing::subscriber::with_default(subscriber, || {
let _span = tool_call_span("a", "t", Some(&long_args));
});
let recorded = fields.lock().unwrap().get("tool.args").unwrap().clone();
assert_eq!(recorded.len(), 1002);
}
#[test]
fn test_handoff_span_records_source_and_target() {
let fields = Arc::new(Mutex::new(std::collections::HashMap::new()));
let subscriber = RecordingSubscriber {
fields: Arc::clone(&fields),
span_names: Arc::new(Mutex::new(Vec::new())),
};
tracing::subscriber::with_default(subscriber, || {
let _span = handoff_span("agent_a", "agent_b");
});
let fields = fields.lock().unwrap();
assert_eq!(fields.get("handoff.source").unwrap(), "\"agent_a\"");
assert_eq!(fields.get("handoff.target").unwrap(), "\"agent_b\"");
}
#[test]
fn test_record_token_usage_only_records_nonzero_counts() {
let fields = Arc::new(Mutex::new(std::collections::HashMap::new()));
let subscriber = RecordingSubscriber {
fields: Arc::clone(&fields),
span_names: Arc::new(Mutex::new(Vec::new())),
};
tracing::subscriber::with_default(subscriber, || {
let span = llm_call_span("a", "m");
record_token_usage(&span, 100, 0, 100);
});
let fields = fields.lock().unwrap();
assert!(fields.contains_key("llm.prompt_tokens"));
assert!(!fields.contains_key("llm.completion_tokens"));
assert!(fields.contains_key("llm.total_tokens"));
}
#[test]
fn test_is_tracing_enabled_reflects_subscriber_registration() {
let subscriber = RecordingSubscriber::default();
tracing::subscriber::with_default(subscriber, || {
assert!(is_tracing_enabled());
});
}
}