1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
//! # solti-observe
//!
//! Observability primitives for the solti task execution system.
//!
//! This crate wires [`tracing`] into solti, covering three concerns:
//!
//! 1. **Logger initialization** - [`init_logger`] installs a global tracing
//! subscriber configured via [`LoggerConfig`] (format, level filter,
//! timezone, color).
//! 2. **Event logging** - [`TracingEventSubscriber`] (feature `subscriber`)
//! maps every [`taskvisor`] supervision event to a structured tracing call
//! at the appropriate severity level.
//! 3. **Timezone sync** - [`timezone_sync`] (feature `timezone-sync`) is a
//! periodic task that re-detects the local UTC offset so log timestamps
//! stay correct across DST transitions.
//!
//! ## Architecture
//!
//! ```text
//! main()
//! ├─ init_local_offset() // before tokio runtime
//! └─ tokio::Runtime::new()
//! └─ async_main()
//! ├─ init_logger(&cfg) // installs global tracing subscriber
//! │ ├─ Text → fmt::Layer (colored, RFC 3339 timestamps)
//! │ ├─ Json → fmt::Layer::json()
//! │ └─ Journald → tracing_journald::layer() (Linux only)
//! │
//! ├─ TracingEventSubscriber // feature: subscriber
//! │ └─ on_event() → trace!/debug!/info!/warn!/error!
//! │
//! └─ timezone_sync() // feature: timezone-sync
//! └─ periodic re-detection of local UTC offset
//! ```
//!
//! ## Public API
//!
//! | Item | Feature | Description |
//! |------------------------------------------|-----------------|----------------------------------------------------------|
//! | [`LoggerConfig`] | - | Logger configuration (format, level, timezone, color) |
//! | [`init_logger`] | - | Install global tracing subscriber |
//! | [`init_local_offset`] | - | Detect local UTC offset (call before tokio runtime) |
//! | [`LoggerFormat`] | - | Output format: `Text` / `Json` / `Journald` |
//! | [`LoggerLevel`] | - | Validated `EnvFilter` expression wrapper |
//! | [`LoggerTimeZone`] | - | Timestamp timezone: `Utc` / `Local` |
//! | [`LoggerError`] | - | Error type for logger initialization |
//! | [`TracingEventSubscriber`] | `subscriber` | Logs [`taskvisor`] events via tracing |
//! | [`timezone_sync`] | `timezone-sync` | Periodic task that re-detects the local UTC offset |
//!
//! ## Feature flags
//!
//! | Flag | Default | Dependencies | Effect |
//! |-----------------|---------|-------------------------------------|-----------------------------------------------|
//! | `subscriber` | off | `taskvisor`, `async-trait` | Enables [`TracingEventSubscriber`] |
//! | `timezone-sync` | off | `taskvisor`, `tokio-util`, `solti-model` | Enables [`timezone_sync`] periodic task |
//!
//! ## Quick start
//!
//! ```text
//! use solti_observe::{LoggerConfig, LoggerLevel, init_local_offset, init_logger};
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // 1) Must be called before spawning threads (tokio runtime).
//! init_local_offset();
//!
//! tokio::runtime::Runtime::new()?.block_on(async {
//! // 2) Initialize logger
//! let cfg = LoggerConfig {
//! level: LoggerLevel::new("info")?,
//! ..Default::default()
//! };
//! init_logger(&cfg)?;
//!
//! tracing::info!("ready");
//! Ok(())
//! })
//! }
//! ```
//!
//! ## Local timezone support
//!
//! On most Unix platforms, detecting the local UTC offset requires reading `/etc/localtime`,
//! which is unsafe in multi-threaded processes.
//!
//! To workaround this:
//! 1. Call [`init_local_offset`] in `main()` **before** `tokio::runtime::Runtime::new()`.
//! 2. Optionally submit the [`timezone_sync`] task to periodically re-detect
//! the offset (handles DST transitions in long-running daemons).
//!
//! If [`init_local_offset`] is not called, timestamps fall back to UTC with a warning printed to stderr on first use.
//!
//! ## Also
//!
//! - [`tracing`] the underlying structured logging framework.
//! - [`taskvisor::Subscribe`] trait that [`TracingEventSubscriber`] implements.
//! - `solti-prometheus` is a complementary metrics subscriber for the same event stream.
//! - See `examples/http-server` for a complete integration example.
pub use ;
// Periodic task that re-detects the local UTC offset.
// Enable with: `--features timezone-sync`
pub use timezone_sync;
pub use ;