open_net/api/log/options.rs
1use super::{LogLevel, LogType};
2
3/// Filtering and queue budgets for a shared log subscription.
4///
5/// Defaults: all real levels (`Debug`), 256 queued records, 16 KiB per record,
6/// and 1 MiB of queued/reserved payload bytes. These are policy defaults, not
7/// measurements of an application's logging needs.
8///
9/// Payload bytes are the sum of `location.len()`, `tag.len()` and `content.len()`
10/// in UTF-8. Each subscription accounts for its own logical bytes even when
11/// records share storage. The budget includes brief reservations before enqueue,
12/// but excludes dequeued records, user-retained records, allocation overhead and
13/// formatting temporaries. It is not a process memory or allocation limit.
14#[derive(Clone, Debug)]
15pub struct LogSubscriptionOptions {
16 pub(crate) log_types: Vec<LogType>,
17 pub(crate) max_level: LogLevel,
18 pub(crate) queue_capacity: usize,
19 pub(crate) max_record_bytes: usize,
20 pub(crate) max_queued_bytes: usize,
21}
22
23impl LogSubscriptionOptions {
24 /// Selects explicit origins with the documented default levels and budgets.
25 /// An empty origin list is rejected when registering the subscription.
26 pub fn new(log_types: &[LogType]) -> Self {
27 Self {
28 log_types: log_types.to_vec(),
29 max_level: LogLevel::Debug,
30 queue_capacity: 256,
31 max_record_bytes: 16 * 1024,
32 max_queued_bytes: 1024 * 1024,
33 }
34 }
35
36 /// Accepts real levels up to this value: `Warn` accepts Error and Warn,
37 /// `Debug` accepts all real levels, and `None` disables this subscription.
38 /// A record whose level is `None` is never accepted by a shared subscription.
39 pub fn with_max_level(mut self, level: LogLevel) -> Self {
40 self.max_level = level;
41 self
42 }
43
44 /// Sets the number of waiting records, excluding the running callback.
45 /// Registration rejects values outside `1..=16_384`.
46 pub fn with_queue_capacity(mut self, records: usize) -> Self {
47 self.queue_capacity = records;
48 self
49 }
50
51 /// Sets the maximum logical payload bytes of one record, including synthetic
52 /// overflow reports. Registration rejects zero or a value greater than the
53 /// queued-byte budget. Oversized records are dropped whole, never truncated.
54 /// The check happens after formatting and cannot bound parameter allocations.
55 pub fn with_max_record_bytes(mut self, bytes: usize) -> Self {
56 self.max_record_bytes = bytes;
57 self
58 }
59
60 /// Sets the logical payload budget for queued records and pending enqueue
61 /// reservations. Registration rejects zero or a value below the single-record
62 /// limit. Bytes are released before invoking the callback, or when an enqueue
63 /// fails or a queued record is destroyed.
64 pub fn with_max_queued_bytes(mut self, bytes: usize) -> Self {
65 self.max_queued_bytes = bytes;
66 self
67 }
68}