Skip to main content

mutil_ai/
audit.rs

1use std::sync::Arc;
2use std::sync::atomic::{AtomicU64, Ordering};
3use std::sync::mpsc::{Receiver, SyncSender, TrySendError, sync_channel};
4use std::time::{Duration, Instant};
5
6use crate::error::{Error, ErrorKind};
7use crate::headers::RequestOptions;
8use crate::normalize::NormalizeStats;
9use crate::profile::Capabilities;
10use crate::types::Usage;
11
12/// Controls which structured transport events are emitted.
13///
14/// Audit events never contain prompts, messages, reasoning, tool arguments,
15/// tool results, request bodies, or response bodies. Correlation identifiers
16/// and profile metadata require explicit opt-in.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub struct AuditConfig {
19    /// Master switch: when `false`, no audit events are emitted.
20    pub enabled: bool,
21    /// Emit [`AuditEvent::AttemptStarted`] and [`AuditEvent::AttemptFinished`].
22    pub record_attempts: bool,
23    /// Emit retry and stream-reconnect scheduling events.
24    pub record_retries: bool,
25    /// Emit success outcomes for attempts and requests.
26    pub record_success: bool,
27    /// Emit failure outcomes for attempts and requests.
28    pub record_failure: bool,
29    /// Emit a final [`AuditEvent::RequestFinished`] with outcome
30    /// [`AuditOutcome::Cancelled`] when a stream is dropped before completion.
31    pub record_cancellation: bool,
32    /// Emit response-header and first-token timing events.
33    pub record_timing: bool,
34    /// Emit context-free aggregate counts for normalization repairs.
35    pub record_normalization: bool,
36    /// Include the profile snapshot in [`AuditEvent::RequestStarted`].
37    pub include_profile: bool,
38    /// Include the caller-supplied SDK request id in
39    /// [`AuditEvent::RequestStarted`].
40    pub include_sdk_request_id: bool,
41    /// Include the provider's request id in header, attempt, and completion
42    /// events.
43    pub include_provider_request_id: bool,
44    /// Include the session id in [`AuditEvent::RequestStarted`]. Off by
45    /// default because session ids can be tenant-sensitive.
46    pub include_session_id: bool,
47    /// Include token usage in [`AuditEvent::RequestFinished`].
48    pub include_usage: bool,
49    /// Sample one out of every N logical requests. `1` records every request.
50    pub sample_every: u64,
51}
52
53impl Default for AuditConfig {
54    fn default() -> Self {
55        Self {
56            enabled: false,
57            record_attempts: true,
58            record_retries: true,
59            record_success: true,
60            record_failure: true,
61            record_cancellation: true,
62            record_timing: true,
63            record_normalization: true,
64            include_profile: false,
65            include_sdk_request_id: false,
66            include_provider_request_id: true,
67            include_session_id: false,
68            include_usage: true,
69            sample_every: 1,
70        }
71    }
72}
73
74impl AuditConfig {
75    /// Creates a config with auditing enabled and all other defaults kept.
76    pub fn enabled() -> Self {
77        Self {
78            enabled: true,
79            ..Self::default()
80        }
81    }
82
83    /// Sets whether attempt-level events are emitted.
84    pub fn record_attempts(mut self, enabled: bool) -> Self {
85        self.record_attempts = enabled;
86        self
87    }
88
89    /// Sets whether retry and reconnect scheduling events are emitted.
90    pub fn record_retries(mut self, enabled: bool) -> Self {
91        self.record_retries = enabled;
92        self
93    }
94
95    /// Sets whether success outcomes are emitted.
96    pub fn record_success(mut self, enabled: bool) -> Self {
97        self.record_success = enabled;
98        self
99    }
100
101    /// Sets whether failure outcomes are emitted.
102    pub fn record_failure(mut self, enabled: bool) -> Self {
103        self.record_failure = enabled;
104        self
105    }
106
107    /// Emit a final event when a stream is dropped before terminal completion.
108    pub fn record_cancellation(mut self, enabled: bool) -> Self {
109        self.record_cancellation = enabled;
110        self
111    }
112
113    /// Emit response-header and first-token timing events.
114    pub fn record_timing(mut self, enabled: bool) -> Self {
115        self.record_timing = enabled;
116        self
117    }
118
119    /// Emit context-free aggregate counts for normalization repairs.
120    pub fn record_normalization(mut self, enabled: bool) -> Self {
121        self.record_normalization = enabled;
122        self
123    }
124
125    /// Include the selected profile id, model-profile flag, and capability
126    /// snapshot in `RequestStarted`.
127    pub fn include_profile(mut self, enabled: bool) -> Self {
128        self.include_profile = enabled;
129        self
130    }
131
132    /// Sets whether the SDK request id is included in
133    /// [`AuditEvent::RequestStarted`].
134    pub fn include_sdk_request_id(mut self, enabled: bool) -> Self {
135        self.include_sdk_request_id = enabled;
136        self
137    }
138
139    /// Sets whether the provider request id is included in events.
140    pub fn include_provider_request_id(mut self, enabled: bool) -> Self {
141        self.include_provider_request_id = enabled;
142        self
143    }
144
145    /// Session IDs can be tenant-sensitive. They are excluded by default.
146    pub fn include_session_id(mut self, enabled: bool) -> Self {
147        self.include_session_id = enabled;
148        self
149    }
150
151    /// Sets whether token usage is included in
152    /// [`AuditEvent::RequestFinished`].
153    pub fn include_usage(mut self, enabled: bool) -> Self {
154        self.include_usage = enabled;
155        self
156    }
157
158    /// Sets the sampling rate; values below `1` are clamped to `1`.
159    pub fn sample_every(mut self, sample_every: u64) -> Self {
160        self.sample_every = sample_every.max(1);
161        self
162    }
163}
164
165/// The final outcome of an attempt or request.
166#[derive(Debug, Clone, Copy, PartialEq, Eq)]
167pub enum AuditOutcome {
168    /// The operation completed without error.
169    Success,
170    /// The operation ended with an error.
171    Failure,
172    /// The operation was cancelled (including drop-before-completion).
173    Cancelled,
174}
175
176/// Which model output started the stream.
177#[derive(Debug, Clone, Copy, PartialEq, Eq)]
178pub enum FirstTokenKind {
179    /// The first token was assistant-visible text.
180    Text,
181    /// The first token was reasoning output.
182    Reasoning,
183    /// The first token was tool-call data.
184    ToolCall,
185}
186
187/// Content-free request and response byte counts.
188///
189/// `request_body` is the serialized body size for one HTTP attempt. Retries
190/// reuse the same logical body. `response_body` is the cumulative decoded body
191/// size across retries and stream reconnects, including provider error bodies.
192#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
193pub struct ByteCounts {
194    /// Serialized request body size for one HTTP attempt; retries reuse the
195    /// same logical body.
196    pub request_body: u64,
197    /// Cumulative decoded response body size across retries and stream
198    /// reconnects, including provider error bodies.
199    pub response_body: u64,
200}
201
202/// Timing measured from the start of one logical request.
203///
204/// `time_to_headers` is available after the HTTP response headers arrive.
205/// `time_to_first_token` is only available for streaming model output.
206#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
207pub struct RequestTiming {
208    /// Time from request start until HTTP response headers arrived.
209    pub time_to_headers: Option<Duration>,
210    /// Time from request start until the first streamed token; `None` for
211    /// non-streaming requests.
212    pub time_to_first_token: Option<Duration>,
213    /// The kind of output that produced the first token.
214    pub first_token_kind: Option<FirstTokenKind>,
215}
216
217/// Non-content configuration snapshot for diagnostics.
218#[derive(Debug, Clone, PartialEq, Eq)]
219pub struct ProfileAuditSnapshot {
220    /// Provider profile id, when an explicit profile was selected.
221    pub provider_profile_id: Option<String>,
222    /// Whether a model-level profile matched this request.
223    pub model_profile_selected: bool,
224    /// Effective capability gate used for this request.
225    pub capabilities: Option<Capabilities>,
226}
227
228/// A structured, context-free audit event.
229#[derive(Debug, Clone, PartialEq, Eq)]
230pub enum AuditEvent {
231    /// A logical request (including all retries) began.
232    RequestStarted {
233        /// Provider identifier, e.g. `"openai"`.
234        provider: &'static str,
235        /// Wire protocol identifier, e.g. `"chat-completions"`.
236        protocol: &'static str,
237        /// Model name requested.
238        model: String,
239        /// Caller-supplied SDK request id, when opted in.
240        sdk_request_id: Option<String>,
241        /// Session id, when opted in.
242        session_id: Option<String>,
243        /// Profile snapshot, when opted in.
244        profile: Option<ProfileAuditSnapshot>,
245    },
246    /// One HTTP attempt began.
247    AttemptStarted {
248        /// Attempt number, as tracked by the SDK.
249        attempt: u32,
250    },
251    /// HTTP response headers arrived for an attempt.
252    ResponseHeaders {
253        /// Attempt this response belongs to.
254        attempt: u32,
255        /// Time from the start of that attempt until headers arrived.
256        elapsed: Duration,
257        /// HTTP status code.
258        status: u16,
259        /// Provider request id, when opted in.
260        provider_request_id: Option<String>,
261    },
262    /// One HTTP attempt ended.
263    AttemptFinished {
264        /// Attempt that finished.
265        attempt: u32,
266        /// Duration of the attempt.
267        duration: Duration,
268        /// Whether the attempt succeeded or failed.
269        outcome: AuditOutcome,
270        /// HTTP status code, when a response was received.
271        status: Option<u16>,
272        /// Error classification, when the attempt failed.
273        error_kind: Option<ErrorKind>,
274        /// Whether the SDK considers the error retryable.
275        retryable: bool,
276        /// Provider request id, when opted in.
277        provider_request_id: Option<String>,
278    },
279    /// The first streamed token arrived.
280    FirstToken {
281        /// Time from the start of the logical request.
282        elapsed: Duration,
283        /// Which kind of output produced the token.
284        kind: FirstTokenKind,
285    },
286    /// A response body required normalization; only aggregate counts are
287    /// reported, never content.
288    Normalization {
289        /// Context-free repair counters.
290        stats: NormalizeStats,
291    },
292    /// A caller-requested response transform was applied.
293    TransformApplied,
294    /// A retry of the request was scheduled.
295    RetryScheduled {
296        /// Attempt that failed.
297        attempt: u32,
298        /// Attempt number that will run next.
299        next_attempt: u32,
300        /// Delay before the next attempt.
301        delay: Duration,
302        /// Classification of the error that triggered the retry.
303        error_kind: Option<ErrorKind>,
304    },
305    /// A reconnect of an in-progress SSE stream was scheduled.
306    StreamReconnectScheduled {
307        /// Reconnect attempt number, starting at 1.
308        attempt: u32,
309        /// Delay before reconnecting.
310        delay: Duration,
311        /// Whether a last event id is available to resume from.
312        has_last_event_id: bool,
313    },
314    /// The logical request (including retries) ended. Emitted exactly once
315    /// per request.
316    RequestFinished {
317        outcome: AuditOutcome,
318        duration: Duration,
319        timing: RequestTiming,
320        bytes: ByteCounts,
321        status: Option<u16>,
322        error_kind: Option<ErrorKind>,
323        provider_request_id: Option<String>,
324        usage: Option<Usage>,
325    },
326}
327
328/// Receives context-free audit events.
329pub trait AuditSink: Send + Sync {
330    /// Handles one audit event. Implementations should be non-blocking; use
331    /// [`bounded_audit_channel`] for a queue that never backpressures the
332    /// request path.
333    fn record(&self, event: AuditEvent);
334}
335
336/// Runtime counters for a bounded audit channel.
337#[derive(Debug, Default)]
338pub struct AuditStats {
339    accepted: AtomicU64,
340    dropped_full: AtomicU64,
341    dropped_disconnected: AtomicU64,
342}
343
344impl AuditStats {
345    /// Loads the current counters as a plain snapshot.
346    pub fn snapshot(&self) -> AuditStatsSnapshot {
347        AuditStatsSnapshot {
348            accepted: self.accepted.load(Ordering::Relaxed),
349            dropped_full: self.dropped_full.load(Ordering::Relaxed),
350            dropped_disconnected: self.dropped_disconnected.load(Ordering::Relaxed),
351        }
352    }
353}
354
355/// A point-in-time copy of [`AuditStats`] counters.
356#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
357pub struct AuditStatsSnapshot {
358    /// Events successfully delivered to the channel.
359    pub accepted: u64,
360    /// Events dropped because the channel was full.
361    pub dropped_full: u64,
362    /// Events dropped because the receiver was disconnected.
363    pub dropped_disconnected: u64,
364}
365
366impl AuditStatsSnapshot {
367    /// Total number of dropped events.
368    pub const fn dropped(&self) -> u64 {
369        self.dropped_full + self.dropped_disconnected
370    }
371}
372
373struct AuditChannelSink {
374    sender: SyncSender<AuditEvent>,
375    stats: Arc<AuditStats>,
376}
377
378impl AuditSink for AuditChannelSink {
379    fn record(&self, event: AuditEvent) {
380        match self.sender.try_send(event) {
381            Ok(()) => {
382                self.stats.accepted.fetch_add(1, Ordering::Relaxed);
383            }
384            Err(TrySendError::Full(_)) => {
385                self.stats.dropped_full.fetch_add(1, Ordering::Relaxed);
386            }
387            Err(TrySendError::Disconnected(_)) => {
388                self.stats
389                    .dropped_disconnected
390                    .fetch_add(1, Ordering::Relaxed);
391            }
392        }
393    }
394}
395
396/// Create a non-blocking, bounded audit channel.
397///
398/// A full queue drops the event and increments [`AuditStatsSnapshot::dropped_full`].
399/// The model request path is never blocked by audit backpressure.
400pub fn bounded_audit_channel(
401    capacity: usize,
402) -> (Arc<dyn AuditSink>, Receiver<AuditEvent>, Arc<AuditStats>) {
403    let (sender, receiver) = sync_channel(capacity.max(1));
404    let stats = Arc::new(AuditStats::default());
405    let sink = Arc::new(AuditChannelSink {
406        sender,
407        stats: stats.clone(),
408    });
409    (sink, receiver, stats)
410}
411
412#[derive(Default)]
413struct AuditState {
414    time_to_headers_nanos: AtomicU64,
415    time_to_first_token_nanos: AtomicU64,
416    first_token_kind: AtomicU64,
417    response_body_bytes: AtomicU64,
418}
419
420impl AuditState {
421    const UNSET: u64 = u64::MAX;
422}
423
424#[derive(Clone)]
425pub(crate) struct AuditContext {
426    sink: Arc<dyn AuditSink>,
427    config: AuditConfig,
428    provider: &'static str,
429    protocol: &'static str,
430    model: String,
431    profile: Option<ProfileAuditSnapshot>,
432    sdk_request_id: Option<String>,
433    session_id: Option<String>,
434    request_body_bytes: u64,
435    started_at: Instant,
436    state: Arc<AuditState>,
437}
438
439pub(crate) struct AuditRequestMeta<'a> {
440    pub provider: &'static str,
441    pub protocol: &'static str,
442    pub model: &'a str,
443    pub profile: Option<ProfileAuditSnapshot>,
444    pub request_body_bytes: u64,
445}
446
447impl AuditContext {
448    pub(crate) fn new(
449        sink: Arc<dyn AuditSink>,
450        config: AuditConfig,
451        options: &RequestOptions,
452        meta: AuditRequestMeta<'_>,
453    ) -> Self {
454        let AuditRequestMeta {
455            provider,
456            protocol,
457            model,
458            profile,
459            request_body_bytes,
460        } = meta;
461        Self {
462            sink,
463            config,
464            provider,
465            protocol,
466            model: model.to_string(),
467            profile: config.include_profile.then_some(profile).flatten(),
468            sdk_request_id: config
469                .include_sdk_request_id
470                .then(|| options.context.request_id.clone())
471                .flatten(),
472            session_id: config
473                .include_session_id
474                .then(|| options.context.session_id.clone())
475                .flatten(),
476            request_body_bytes,
477            started_at: Instant::now(),
478            state: Arc::new(AuditState {
479                time_to_headers_nanos: AtomicU64::new(AuditState::UNSET),
480                time_to_first_token_nanos: AtomicU64::new(AuditState::UNSET),
481                first_token_kind: AtomicU64::new(AuditState::UNSET),
482                response_body_bytes: AtomicU64::new(0),
483            }),
484        }
485    }
486
487    pub(crate) fn request_started(&self) {
488        if !self.config.enabled {
489            return;
490        }
491        self.sink.record(AuditEvent::RequestStarted {
492            provider: self.provider,
493            protocol: self.protocol,
494            model: self.model.clone(),
495            sdk_request_id: self.sdk_request_id.clone(),
496            session_id: self.session_id.clone(),
497            profile: self.profile.clone(),
498        });
499    }
500
501    pub(crate) fn attempt_started(&self, attempt: u32) {
502        if !self.config.enabled || !self.config.record_attempts {
503            return;
504        }
505        self.sink.record(AuditEvent::AttemptStarted { attempt });
506    }
507
508    pub(crate) fn response_headers(
509        &self,
510        attempt: u32,
511        elapsed: Duration,
512        status: u16,
513        provider_request_id: Option<String>,
514        successful: bool,
515    ) {
516        if !self.config.enabled || !self.config.record_timing {
517            return;
518        }
519        if successful {
520            let _ = self.state.time_to_headers_nanos.compare_exchange(
521                AuditState::UNSET,
522                duration_nanos(elapsed),
523                Ordering::Relaxed,
524                Ordering::Relaxed,
525            );
526        }
527        self.sink.record(AuditEvent::ResponseHeaders {
528            attempt,
529            elapsed,
530            status,
531            provider_request_id: self
532                .config
533                .include_provider_request_id
534                .then_some(provider_request_id)
535                .flatten(),
536        });
537    }
538
539    pub(crate) fn first_token(&self, kind: FirstTokenKind) {
540        if !self.config.enabled || !self.config.record_timing {
541            return;
542        }
543        let kind_code = first_token_kind_code(kind);
544        if self
545            .state
546            .first_token_kind
547            .compare_exchange(
548                AuditState::UNSET,
549                kind_code,
550                Ordering::Relaxed,
551                Ordering::Relaxed,
552            )
553            .is_err()
554        {
555            return;
556        }
557
558        let elapsed = self.started_at.elapsed();
559        self.state
560            .time_to_first_token_nanos
561            .store(duration_nanos(elapsed), Ordering::Relaxed);
562        self.sink.record(AuditEvent::FirstToken { elapsed, kind });
563    }
564
565    pub(crate) fn normalization(&self, stats: NormalizeStats) {
566        if !self.config.enabled || !self.config.record_normalization || stats.is_clean() {
567            return;
568        }
569        self.sink.record(AuditEvent::Normalization { stats });
570    }
571
572    pub(crate) fn transform_applied(&self) {
573        if self.config.enabled {
574            self.sink.record(AuditEvent::TransformApplied);
575        }
576    }
577
578    pub(crate) fn add_response_bytes(&self, bytes: usize) {
579        if !self.config.enabled || bytes == 0 {
580            return;
581        }
582        self.state
583            .response_body_bytes
584            .fetch_add(bytes as u64, Ordering::Relaxed);
585    }
586
587    pub(crate) fn attempt_finished_with_request_id(
588        &self,
589        attempt: u32,
590        duration: Duration,
591        status: Option<u16>,
592        provider_request_id: Option<String>,
593        error: Option<&Error>,
594    ) {
595        if !self.config.enabled || !self.config.record_attempts {
596            return;
597        }
598        let outcome = if error.is_some() {
599            AuditOutcome::Failure
600        } else {
601            AuditOutcome::Success
602        };
603        if outcome == AuditOutcome::Success && !self.config.record_success {
604            return;
605        }
606        if outcome == AuditOutcome::Failure && !self.config.record_failure {
607            return;
608        }
609        self.sink.record(AuditEvent::AttemptFinished {
610            attempt,
611            duration,
612            outcome,
613            status,
614            error_kind: error.map(Error::kind),
615            retryable: error.is_some_and(Error::is_retryable),
616            provider_request_id: self
617                .config
618                .include_provider_request_id
619                .then_some(provider_request_id)
620                .flatten(),
621        });
622    }
623
624    pub(crate) fn retry_scheduled(
625        &self,
626        attempt: u32,
627        next_attempt: u32,
628        delay: Duration,
629        error: &Error,
630    ) {
631        if !self.config.enabled || !self.config.record_retries {
632            return;
633        }
634        self.sink.record(AuditEvent::RetryScheduled {
635            attempt,
636            next_attempt,
637            delay,
638            error_kind: Some(error.kind()),
639        });
640    }
641
642    pub(crate) fn stream_reconnect_scheduled(
643        &self,
644        attempt: u32,
645        delay: Duration,
646        has_last_event_id: bool,
647    ) {
648        if !self.config.enabled || !self.config.record_retries {
649            return;
650        }
651        self.sink.record(AuditEvent::StreamReconnectScheduled {
652            attempt,
653            delay,
654            has_last_event_id,
655        });
656    }
657
658    pub(crate) fn request_finished_with_request_id(
659        &self,
660        outcome: AuditOutcome,
661        status: Option<u16>,
662        provider_request_id: Option<String>,
663        error: Option<&Error>,
664        usage: Option<Usage>,
665    ) {
666        if !self.config.enabled {
667            return;
668        }
669        if outcome == AuditOutcome::Success && !self.config.record_success {
670            return;
671        }
672        if outcome == AuditOutcome::Failure && !self.config.record_failure {
673            return;
674        }
675        if outcome == AuditOutcome::Cancelled && !self.config.record_cancellation {
676            return;
677        }
678        self.sink.record(AuditEvent::RequestFinished {
679            outcome,
680            duration: self.started_at.elapsed(),
681            timing: self.timing_snapshot(),
682            bytes: ByteCounts {
683                request_body: self.request_body_bytes,
684                response_body: self.state.response_body_bytes.load(Ordering::Relaxed),
685            },
686            status,
687            error_kind: error.map(Error::kind),
688            provider_request_id: self
689                .config
690                .include_provider_request_id
691                .then_some(provider_request_id)
692                .flatten(),
693            usage: self
694                .config
695                .include_usage
696                .then_some(usage)
697                .flatten()
698                .map(Usage::without_raw),
699        });
700    }
701
702    fn timing_snapshot(&self) -> RequestTiming {
703        if !self.config.record_timing {
704            return RequestTiming::default();
705        }
706        let time_to_headers = load_duration(&self.state.time_to_headers_nanos);
707        let time_to_first_token = load_duration(&self.state.time_to_first_token_nanos);
708        let first_token_kind = match self.state.first_token_kind.load(Ordering::Relaxed) {
709            1 => Some(FirstTokenKind::Text),
710            2 => Some(FirstTokenKind::Reasoning),
711            3 => Some(FirstTokenKind::ToolCall),
712            _ => None,
713        };
714        RequestTiming {
715            time_to_headers,
716            time_to_first_token,
717            first_token_kind,
718        }
719    }
720}
721
722fn duration_nanos(duration: Duration) -> u64 {
723    duration.as_nanos().min(u64::MAX as u128 - 1) as u64
724}
725
726fn load_duration(value: &AtomicU64) -> Option<Duration> {
727    match value.load(Ordering::Relaxed) {
728        AuditState::UNSET => None,
729        nanos => Some(Duration::from_nanos(nanos)),
730    }
731}
732
733const fn first_token_kind_code(kind: FirstTokenKind) -> u64 {
734    match kind {
735        FirstTokenKind::Text => 1,
736        FirstTokenKind::Reasoning => 2,
737        FirstTokenKind::ToolCall => 3,
738    }
739}