//! Wire log — an opt-in, on-disk record of everything Luxe sends to a model and gets back. //! //! Set `LUXE_WIRE_LOG=` and every provider call appends JSONL: the exact request body as it //! goes on the wire (after provider-specific shaping — `cache_control` markers, tool schemas, //! thinking config), the request headers with credential values redacted, and every normalized //! [`ProviderEvent`] coming back. `luxe wire ` turns that into an audit report. //! //! Off unless the variable is set, and never fatal: a log that cannot be written is dropped with a //! warning rather than failing a turn. The file is local — nothing here phones home. //! //! Requests are recorded by the adapters, the only place the final body exists; responses by //! [`RecordingProvider`], which wraps any adapter and needs no per-provider knowledge. The two //! halves are tied together by a call id the decorator puts in a task-local, so concurrent //! sessions never interleave into one another's records. use std::io::Write; use std::sync::atomic::{AtomicU64, Ordering}; use std::sync::{Arc, Mutex, OnceLock}; use std::time::{SystemTime, UNIX_EPOCH}; use luxe_core::provider::{CompletionRequest, Provider, ProviderError, ProviderEvent}; /// Header names whose value is a credential and must never reach the log. const SECRET_HEADERS: &[&str] = &["authorization", "x-api-key", "api-key", "cookie", "proxy-authorization"]; /// The open log file, resolved once from the environment. static SINK: OnceLock>> = OnceLock::new(); /// Monotonic provider-call counter. static SEQ: AtomicU64 = AtomicU64::new(0); tokio::task_local! { /// The call id of the provider call this task is inside, set by [`RecordingProvider`]. static CALL_ID: u64; } fn sink() -> Option<&'static Mutex> { SINK.get_or_init(|| { let path = std::env::var("LUXE_WIRE_LOG").ok().filter(|path| !path.trim().is_empty())?; let path = std::path::PathBuf::from(path); if let Some(parent) = path.parent() { let _ = std::fs::create_dir_all(parent); } match std::fs::OpenOptions::new().create(true).append(true).open(&path) { Ok(file) => { tracing::info!(path = %path.display(), "wire log enabled"); Some(Mutex::new(file)) } Err(error) => { tracing::warn!(path = %path.display(), %error, "wire log could not be opened"); None } } }) .as_ref() } /// Whether wire logging is on. Cheap enough to guard every call site. pub fn enabled() -> bool { sink().is_some() } /// The call this task belongs to, or `0` for a provider used without the recording wrapper. pub fn current_call_id() -> u64 { CALL_ID.try_with(|id| *id).unwrap_or(0) } fn append(record: serde_json::Value) { if let Some(sink) = sink() { append_to(sink, &record); } } /// Writes `record` to `sink`, saying once if it could not. fn append_to(sink: &Mutex, record: &serde_json::Value) { let written = match sink.lock() { Ok(mut out) => write_record(&mut *out, record), Err(_) => Err(std::io::Error::other("the log's lock was poisoned")), }; if let Err(error) = written { note_dropped(&error); } } /// One record as one line. fn write_record(out: &mut impl Write, record: &serde_json::Value) -> std::io::Result<()> { let line = serde_json::to_string(record).map_err(std::io::Error::other)?; writeln!(out, "{line}") } /// Whether the log has already said it is dropping records. static DROPPING: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false); /// Says, once, that the log is dropping records, so a cut-short capture does not pass for a /// quiet run. Returns whether this call was the one that said it. fn note_dropped(error: &dyn std::fmt::Display) -> bool { let first = !DROPPING.swap(true, Ordering::Relaxed); if first { tracing::warn!(%error, "the wire log could not be written; later records may be missing"); } first } fn now_ms() -> u128 { SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_millis()).unwrap_or_default() } /// Record one outgoing request exactly as it will be sent. /// /// `headers` carries only what the adapter sets explicitly; credential header values become /// ``, and the body goes through the shared secret redactor in case a key reached the /// prompt by some other route. pub fn record_request( provider: &str, url: &str, headers: &[(&str, &str)], body: &serde_json::Value, ) { if !enabled() { return; } let headers: serde_json::Map = headers .iter() .map(|(name, value)| { let secret = SECRET_HEADERS.contains(&name.to_ascii_lowercase().as_str()); let value = if secret { "" } else { *value }; ((*name).to_string(), serde_json::Value::String(value.to_string())) }) .collect(); let body = match serde_json::to_string(body) { Ok(text) => serde_json::from_str(&luxe_core::redact::process_secrets().redact(&text)) .unwrap_or_else(|_| body.clone()), Err(_) => body.clone(), }; append(serde_json::json!({ "kind": "request", "call": current_call_id(), "ts_ms": now_ms(), "provider": provider, "url": url, "headers": headers, "body": body, })); } /// Longest reply text kept verbatim; beyond this the record keeps the count and an excerpt. const MAX_TEXT: usize = 4_000; /// Longest tool-call argument payload kept verbatim. const MAX_ARGS: usize = 2_000; /// Most arrival samples kept, so a pathological stream can't unbound the record. const MAX_ARRIVALS: usize = 2_000; /// Accumulates one call's response into a single record. /// /// One line per event would be one line per *token* — unreadable, and it would bury the structure /// an audit is actually looking for. Instead the stream is folded into what came back (text, tool /// calls, usage, stop reason) plus an arrival timeline of `[ms_offset, chars]` pairs, which is what /// proves "renders as it arrives" without duplicating the text. #[derive(Default)] struct ResponseRecord { counts: std::collections::BTreeMap<&'static str, u64>, text: String, thinking_chars: usize, tool_calls: Vec<(String, String, String)>, usage: Option, stop: Option, errors: Vec, arrival: Vec<(u128, usize)>, first_delta_ms: Option, } impl ResponseRecord { fn observe(&mut self, event: &ProviderEvent, elapsed_ms: u128) { let kind = match event { ProviderEvent::Start => "start", ProviderEvent::TextStart { .. } => "text_start", ProviderEvent::TextDelta { delta, .. } => { if self.first_delta_ms.is_none() { self.first_delta_ms = Some(elapsed_ms); } if self.text.len() < MAX_TEXT { self.text.push_str(delta); } if self.arrival.len() < MAX_ARRIVALS { self.arrival.push((elapsed_ms, delta.chars().count())); } "text_delta" } ProviderEvent::TextEnd { .. } => "text_end", ProviderEvent::ThinkingStart { .. } => "thinking_start", ProviderEvent::ThinkingDelta { delta, .. } => { if self.first_delta_ms.is_none() { self.first_delta_ms = Some(elapsed_ms); } self.thinking_chars += delta.chars().count(); if self.arrival.len() < MAX_ARRIVALS { self.arrival.push((elapsed_ms, delta.chars().count())); } "thinking_delta" } ProviderEvent::ThinkingSignature { .. } => "thinking_signature", ProviderEvent::ReasoningItem { .. } => "reasoning_item", ProviderEvent::ReasoningOpaque { .. } => "reasoning_opaque", ProviderEvent::RedactedThinking { .. } => "redacted_thinking", ProviderEvent::ThinkingEnd { .. } => "thinking_end", ProviderEvent::ToolCallStart { id, name, .. } => { self.tool_calls.push((id.clone(), name.clone(), String::new())); "tool_call_start" } ProviderEvent::ToolCallDelta { json_delta, .. } => { if let Some(call) = self.tool_calls.last_mut() { if call.2.len() < MAX_ARGS { call.2.push_str(json_delta); } } "tool_call_delta" } ProviderEvent::ToolCallEnd { .. } => "tool_call_end", ProviderEvent::Usage(usage) => { self.usage = Some(serde_json::json!({ "prompt_tokens": usage.prompt_tokens, "completion_tokens": usage.completion_tokens, "total_tokens": usage.total_tokens, "cache_read_tokens": usage.cache_read_tokens, "cache_write_tokens": usage.cache_write_tokens, "reasoning_tokens": usage.reasoning_tokens, })); "usage" } ProviderEvent::PlanUsage(_) => "plan_usage", ProviderEvent::Done { reason } => { self.stop = Some(format!("{reason:?}")); "done" } ProviderEvent::Error { message, kind } => { self.errors.push(format!("{kind:?}: {message}")); "error" } }; *self.counts.entry(kind).or_default() += 1; } fn finish(self, call: u64, provider: &str, elapsed_ms: u128, completed: bool) { let text = luxe_core::redact::process_secrets().redact(&self.text); append(serde_json::json!({ "kind": "response", "call": call, "ts_ms": now_ms(), "provider": provider, "elapsed_ms": elapsed_ms, "first_delta_ms": self.first_delta_ms, "drained": completed, "events": self.counts, "text": text, "thinking_chars": self.thinking_chars, "tool_calls": self.tool_calls.iter().map(|(id, name, args)| serde_json::json!({ "id": id, "name": name, "arguments": luxe_core::redact::process_secrets().redact(args), })).collect::>(), "usage": self.usage, "stop": self.stop, "errors": self.errors, "arrival": self.arrival, })); } } fn record_error(call: u64, provider: &str, error: &ProviderError) { append(serde_json::json!({ "kind": "error", "call": call, "ts_ms": now_ms(), "provider": provider, "error": luxe_core::redact::process_secrets().redact(&error.to_string()), })); } /// Wraps any provider and records the event stream it produces. /// /// Provider-agnostic on purpose: it sees normalized [`ProviderEvent`]s, so a new adapter is logged /// the day it exists. The request half lives in the adapters, which are the only place the final /// wire body is known. pub struct RecordingProvider { inner: Arc, } impl RecordingProvider { /// Wrap `inner`, or hand it back untouched when logging is off. pub fn wrap(inner: Arc) -> Arc { if enabled() { Arc::new(Self { inner }) } else { inner } } } #[async_trait::async_trait] impl Provider for RecordingProvider { fn name(&self) -> &str { self.inner.name() } async fn stream( &self, req: CompletionRequest, cancel: tokio::sync::watch::Receiver, ) -> Result, ProviderError> { let call = SEQ.fetch_add(1, Ordering::Relaxed); let provider = self.inner.name().to_string(); let started = std::time::Instant::now(); // The adapter records its request from inside this scope, so both halves share `call`. let stream = match CALL_ID.scope(call, self.inner.stream(req, cancel)).await { Ok(stream) => stream, Err(error) => { record_error(call, &provider, &error); return Err(error); } }; Ok(Box::pin(Recording { inner: stream, open: Some(OpenRecord { call, provider, started, record: ResponseRecord::default() }), })) } // Forwarded, or wrapping a provider for the log would quietly switch its cache warming off fn prompt_cache_ttl(&self, req: &CompletionRequest) -> Option { self.inner.prompt_cache_ttl(req) } async fn warm_cache( &self, req: CompletionRequest, ) -> Result { let call = SEQ.fetch_add(1, Ordering::Relaxed); let started = std::time::Instant::now(); let warmed = CALL_ID.scope(call, self.inner.warm_cache(req)).await; match &warmed { // A response half, so `luxe wire` shows what the refresh read rather than a row of zeros Ok(usage) => { let mut record = ResponseRecord::default(); record.observe(&ProviderEvent::Usage(usage.clone()), started.elapsed().as_millis()); record.finish(call, self.inner.name(), started.elapsed().as_millis(), true); } Err(error) => record_error(call, self.inner.name(), error), } warmed } } /// The in-flight half of a recorded stream. struct OpenRecord { call: u64, provider: String, started: std::time::Instant, record: ResponseRecord, } /// A stream that folds what passes through it into one response record. /// /// The record is flushed on **drop**, not just on end-of-stream: the engine stops polling the /// moment it sees `Done` and drops the rest, so an end-of-stream hook alone would silently log /// nothing for a normal turn. `drained` in the record says which of the two happened. struct Recording { inner: S, open: Option, } impl Recording { fn flush(&mut self, drained: bool) { if let Some(open) = self.open.take() { let elapsed = open.started.elapsed().as_millis(); open.record.finish(open.call, &open.provider, elapsed, drained); } } } impl futures::Stream for Recording where S: futures::Stream + Unpin, { type Item = ProviderEvent; fn poll_next( self: std::pin::Pin<&mut Self>, cx: &mut std::task::Context<'_>, ) -> std::task::Poll> { let this = self.get_mut(); match std::pin::Pin::new(&mut this.inner).poll_next(cx) { std::task::Poll::Ready(Some(event)) => { if let Some(open) = this.open.as_mut() { open.record.observe(&event, open.started.elapsed().as_millis()); } std::task::Poll::Ready(Some(event)) } std::task::Poll::Ready(None) => { this.flush(true); std::task::Poll::Ready(None) } std::task::Poll::Pending => std::task::Poll::Pending, } } } impl Drop for Recording { fn drop(&mut self) { self.flush(false); } } #[cfg(test)] mod tests { use super::*; #[test] fn credential_headers_are_redacted_and_protocol_headers_are_not() { for name in ["Authorization", "x-api-key", "API-KEY", "Cookie"] { assert!( SECRET_HEADERS.contains(&name.to_ascii_lowercase().as_str()), "{name} must be treated as a credential" ); } for name in ["anthropic-version", "Content-Type", "Accept", "anthropic-beta"] { assert!( !SECRET_HEADERS.contains(&name.to_ascii_lowercase().as_str()), "{name} is protocol, not a credential" ); } } /// A record the log cannot take is said, once, rather than dropped without a word. /// /// The break this catches: every failure was swallowed, so a capture that stopped partway read /// as a session that went quiet. #[test] fn a_record_the_log_cannot_take_is_said_once() { struct Full; impl Write for Full { fn write(&mut self, _: &[u8]) -> std::io::Result { Err(std::io::Error::other("disk full")) } fn flush(&mut self) -> std::io::Result<()> { Ok(()) } } append_to(&Mutex::new(Full), &serde_json::json!({"kind": "request"})); let error = std::io::Error::other("again"); assert!(!note_dropped(&error), "the append said it, so this one does not"); } #[tokio::test] async fn a_call_id_is_zero_outside_a_recorded_call_and_set_inside_one() { assert_eq!(current_call_id(), 0, "an unwrapped adapter still records, under call 0"); CALL_ID.scope(7, async { assert_eq!(current_call_id(), 7) }).await; } }