actor_framework/tracing.rs
1//! # Observability & Tracing
2//!
3//! This module provides the tracing infrastructure for the entire actor system.
4//!
5//! ## Overview
6//!
7//! The [`setup_tracing`] function initializes structured logging with the `tracing` crate,
8//! providing hierarchical spans that show the complete request flow through the system.
9//!
10//! ## Configuration
11//!
12//! The framework uses a compact format that hides the crate/module prefix (`with_target(false)`).
13//! This keeps log lines short while still providing rich structured data.
14//!
15//! - **Structured logging** with `tracing` crate
16//! - **Hierarchical spans** for request tracing
17//! - **Configurable log levels** via `RUST_LOG` environment variable
18//! - **Compact format** optimized for development
19//!
20//! ## What Gets Traced
21//!
22//! - **Actor Lifecycle**: Startup, shutdown, and final state
23//! - **Entity Operations**: Create, Get, Update, Delete, and custom Actions
24//! - **Request Flow**: Hierarchical spans showing the complete request path
25//! - **Errors**: Detailed error context with entity IDs and failure reasons
26//!
27//! ## Usage Examples
28//!
29//! ```bash
30//! # Compact logs (default)
31//! RUST_LOG=info cargo run
32//!
33//! # Show full payloads with debug logs
34//! RUST_LOG=debug cargo run
35//!
36//! # Very verbose tracing
37//! RUST_LOG=trace cargo run
38//!
39//! # Filter to specific modules
40//! RUST_LOG=actor_recipe::framework=debug cargo run
41//! ```
42//!
43//! ## Debug Flag for Full Payload
44//!
45//! When you run with `RUST_LOG=debug`, functions log full payloads **once** at the start:
46//!
47//! ```rust
48//! # use tracing::debug;
49//! # #[derive(Debug)]
50//! # struct Order { id: String }
51//! # let order = Order { id: "123".to_string() };
52//! debug!(?order, "create_order called");
53//! ```
54//!
55//! The `?` syntax is a `tracing` macro feature that records the variable using its
56//! `Debug` representation as a structured field.
57//!
58//! Running with `RUST_LOG=debug` will show:
59//!
60//! ```text
61//! DEBUG create_order called order={...}
62//! INFO order_processing:create_order: Processing create_order request (Client Side)
63//! ```
64//!
65//! All subsequent logs remain concise, showing only the workflow hierarchy.
66//!
67//! ## Workflow Trace Example
68//!
69//! The tracing output shows the complete order creation workflow with hierarchical spans.
70//!
71//! **With `RUST_LOG=info`** (compact):
72//!
73//! ```text
74//! INFO Sending create_order to actor
75//! INFO Created user_id="user_1" size=1
76//! INFO Created product_id="product_1" size=1
77//! INFO Action ok product_id="product_1"
78//! INFO Created order_id="order_1" size=1
79//! ```
80//!
81//! **With `RUST_LOG=debug`** (detailed):
82//!
83//! ```text
84//! DEBUG create_order called order=Order { id: "", user_id: "user_1", product_id: "product_1", quantity: 3, total: 75.0 }
85//! INFO Sending create_order to actor
86//! DEBUG Get user_id="user_1"
87//! INFO Created user_id="user_1" size=1
88//! DEBUG Get product_id="product_1"
89//! INFO Created product_id="product_1" size=1
90//! DEBUG Action product_id="product_1" action=ReserveStock(3)
91//! INFO Action ok product_id="product_1"
92//! DEBUG Create params=OrderCreate { user_id: "user_1", product_id: "product_1", quantity: 3, total: 75.0 }
93//! INFO Created order_id="order_1" size=1
94//! ```
95//!
96//! **Key Observations**:
97//! 1. **User Validation** → `Get user_id="user_1"` → User found in actor
98//! 2. **Product Validation** → `Get product_id="product_1"` → Product found
99//! 3. **Stock Reservation** → `Action...ReserveStock(3)` → Stock reserved (happens in `Order::on_create`)
100//! 4. **Order Creation** → `Create params=OrderCreate{...}` → Order created
101//!
102//! Each step is traced with structured fields that can be filtered and analyzed in
103//! production logging systems.
104//!
105//! ## Output Formats
106//!
107//! The compact format shows span hierarchy inline:
108//! - `INFO user_creation: Creating test user` - top-level span
109//! - `INFO order_processing:create_order: Processing request` - nested spans
110//!
111//! Use `debug` level to see full object details at function entry points.
112pub fn setup_tracing() {
113 tracing_subscriber::fmt()
114 .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
115 .with_target(false) // Don't show module paths - we use entity_type instead
116 .compact() // Compact format shows spans inline (e.g., "order_processing:create_order")
117 .init();
118}