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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub struct AuditConfig {
19 pub enabled: bool,
21 pub record_attempts: bool,
23 pub record_retries: bool,
25 pub record_success: bool,
27 pub record_failure: bool,
29 pub record_cancellation: bool,
32 pub record_timing: bool,
34 pub record_normalization: bool,
36 pub include_profile: bool,
38 pub include_sdk_request_id: bool,
41 pub include_provider_request_id: bool,
44 pub include_session_id: bool,
47 pub include_usage: bool,
49 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 pub fn enabled() -> Self {
77 Self {
78 enabled: true,
79 ..Self::default()
80 }
81 }
82
83 pub fn record_attempts(mut self, enabled: bool) -> Self {
85 self.record_attempts = enabled;
86 self
87 }
88
89 pub fn record_retries(mut self, enabled: bool) -> Self {
91 self.record_retries = enabled;
92 self
93 }
94
95 pub fn record_success(mut self, enabled: bool) -> Self {
97 self.record_success = enabled;
98 self
99 }
100
101 pub fn record_failure(mut self, enabled: bool) -> Self {
103 self.record_failure = enabled;
104 self
105 }
106
107 pub fn record_cancellation(mut self, enabled: bool) -> Self {
109 self.record_cancellation = enabled;
110 self
111 }
112
113 pub fn record_timing(mut self, enabled: bool) -> Self {
115 self.record_timing = enabled;
116 self
117 }
118
119 pub fn record_normalization(mut self, enabled: bool) -> Self {
121 self.record_normalization = enabled;
122 self
123 }
124
125 pub fn include_profile(mut self, enabled: bool) -> Self {
128 self.include_profile = enabled;
129 self
130 }
131
132 pub fn include_sdk_request_id(mut self, enabled: bool) -> Self {
135 self.include_sdk_request_id = enabled;
136 self
137 }
138
139 pub fn include_provider_request_id(mut self, enabled: bool) -> Self {
141 self.include_provider_request_id = enabled;
142 self
143 }
144
145 pub fn include_session_id(mut self, enabled: bool) -> Self {
147 self.include_session_id = enabled;
148 self
149 }
150
151 pub fn include_usage(mut self, enabled: bool) -> Self {
154 self.include_usage = enabled;
155 self
156 }
157
158 pub fn sample_every(mut self, sample_every: u64) -> Self {
160 self.sample_every = sample_every.max(1);
161 self
162 }
163}
164
165#[derive(Debug, Clone, Copy, PartialEq, Eq)]
167pub enum AuditOutcome {
168 Success,
170 Failure,
172 Cancelled,
174}
175
176#[derive(Debug, Clone, Copy, PartialEq, Eq)]
178pub enum FirstTokenKind {
179 Text,
181 Reasoning,
183 ToolCall,
185}
186
187#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
193pub struct ByteCounts {
194 pub request_body: u64,
197 pub response_body: u64,
200}
201
202#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
207pub struct RequestTiming {
208 pub time_to_headers: Option<Duration>,
210 pub time_to_first_token: Option<Duration>,
213 pub first_token_kind: Option<FirstTokenKind>,
215}
216
217#[derive(Debug, Clone, PartialEq, Eq)]
219pub struct ProfileAuditSnapshot {
220 pub provider_profile_id: Option<String>,
222 pub model_profile_selected: bool,
224 pub capabilities: Option<Capabilities>,
226}
227
228#[derive(Debug, Clone, PartialEq, Eq)]
230pub enum AuditEvent {
231 RequestStarted {
233 provider: &'static str,
235 protocol: &'static str,
237 model: String,
239 sdk_request_id: Option<String>,
241 session_id: Option<String>,
243 profile: Option<ProfileAuditSnapshot>,
245 },
246 AttemptStarted {
248 attempt: u32,
250 },
251 ResponseHeaders {
253 attempt: u32,
255 elapsed: Duration,
257 status: u16,
259 provider_request_id: Option<String>,
261 },
262 AttemptFinished {
264 attempt: u32,
266 duration: Duration,
268 outcome: AuditOutcome,
270 status: Option<u16>,
272 error_kind: Option<ErrorKind>,
274 retryable: bool,
276 provider_request_id: Option<String>,
278 },
279 FirstToken {
281 elapsed: Duration,
283 kind: FirstTokenKind,
285 },
286 Normalization {
289 stats: NormalizeStats,
291 },
292 TransformApplied,
294 RetryScheduled {
296 attempt: u32,
298 next_attempt: u32,
300 delay: Duration,
302 error_kind: Option<ErrorKind>,
304 },
305 StreamReconnectScheduled {
307 attempt: u32,
309 delay: Duration,
311 has_last_event_id: bool,
313 },
314 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
328pub trait AuditSink: Send + Sync {
330 fn record(&self, event: AuditEvent);
334}
335
336#[derive(Debug, Default)]
338pub struct AuditStats {
339 accepted: AtomicU64,
340 dropped_full: AtomicU64,
341 dropped_disconnected: AtomicU64,
342}
343
344impl AuditStats {
345 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#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
357pub struct AuditStatsSnapshot {
358 pub accepted: u64,
360 pub dropped_full: u64,
362 pub dropped_disconnected: u64,
364}
365
366impl AuditStatsSnapshot {
367 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
396pub 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}