feature/improved logging

Cargo.toml

@@ -50,8 +50,13 @@ tracing-subscriber = { version = "0.3.20", features = [
     "fmt",
     "env-filter",
     "time",
+    "json",
 ] }
 tracing-futures = "0.2"
+tracing-tree = "0.4"
+nu-ansi-term = "0.50"
+atty = "0.2"
+time = { version = "0.3", features = ["macros", "formatting"] }
 
 # Network / RPC
 http = "1.1"

Makefile.toml

@@ -266,6 +266,8 @@ docker run --rm \
   -e "TEST_BINARIES_DIR=${TEST_BINARIES_DIR}" \
   -e "NEXTEST_EXPERIMENTAL_LIBTEST_JSON=1" \
   -e "CARGO_TARGET_DIR=/home/container_user/zaino/target" \
+  -e "ZAINOLOG_FORMAT=${ZAINOLOG_FORMAT:-stream}" \
+  -e "RUST_LOG=${RUST_LOG:-}" \
   -w /home/container_user/zaino \
   -u container_user \
   "${IMAGE_NAME}:$TAG" \

docs/logging.md

@@ -0,0 +1,90 @@
+# Logging Configuration
+
+Zaino provides flexible logging with three output formats and configurable verbosity levels.
+
+## Environment Variables
+
+| Variable | Values | Default | Description |
+|----------|--------|---------|-------------|
+| `RUST_LOG` | Filter string | `zaino=info,zainod=info` | Log level filter |
+| `ZAINOLOG_FORMAT` | `stream`, `tree`, `json` | `stream` | Output format |
+| `ZAINOLOG_COLOR` | `true`, `false`, `auto` | `true` | ANSI color output |
+
+## Log Formats
+
+### Stream (default)
+Flat chronological output with timestamps. Best for general use and piping to files.
+```
+14:32:01.234  INFO zaino_state::indexer: Starting indexer
+14:32:01.456  INFO zaino_state::indexer: Connected to validator
+```
+
+### Tree
+Hierarchical span-based output showing call structure. Best for debugging complex flows.
+```
+indexer
+├─ INFO Starting indexer
+└─ validator_connection
+   └─ INFO Connected to validator
+```
+
+### JSON
+Machine-parseable output. Best for log aggregation systems (ELK, Loki, etc).
+```json
+{"timestamp":"2024-01-15T14:32:01.234Z","level":"INFO","target":"zaino_state::indexer","message":"Starting indexer"}
+```
+
+## Usage Examples
+
+### Local Development
+
+```bash
+# Default logging (stream format, zaino crates only at INFO level)
+zainod start
+
+# Tree format for debugging span hierarchies
+ZAINOLOG_FORMAT=tree zainod start
+
+# Debug level for zaino crates
+RUST_LOG=zaino=debug,zainod=debug zainod start
+
+# Include zebra logs
+RUST_LOG=info zainod start
+
+# Fine-grained control
+RUST_LOG="zaino_state=debug,zaino_serve=info,zebra_state=warn" zainod start
+
+# Disable colors (for file output)
+ZAINOLOG_COLOR=false zainod start 2>&1 | tee zainod.log
+```
+
+### Makefile / Container Tests
+
+The test environment passes logging variables through to containers:
+
+```bash
+# Default (stream format)
+makers container-test
+
+# Tree format in tests
+ZAINOLOG_FORMAT=tree makers container-test
+
+# Debug logging in tests
+RUST_LOG=debug ZAINOLOG_FORMAT=tree makers container-test
+
+# JSON output for parsing test logs
+ZAINOLOG_FORMAT=json makers container-test 2>&1 | jq .
+```
+
+### Production
+
+```bash
+# JSON for log aggregation
+ZAINOLOG_FORMAT=json ZAINOLOG_COLOR=false zainod start
+
+# Structured logging to file
+ZAINOLOG_FORMAT=json ZAINOLOG_COLOR=false zainod start 2>> /var/log/zainod.json
+
+# Minimal logging
+RUST_LOG=warn zainod start
+```

zaino-common/Cargo.toml

@@ -18,3 +18,12 @@ serde = { workspace = true, features = ["derive"] }
 # Error handling
 thiserror = { workspace = true }
 
+# Logging
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+tracing-tree = { workspace = true }
+nu-ansi-term = { workspace = true }
+atty = { workspace = true }
+hex = { workspace = true }
+time = { workspace = true }
+

zaino-common/src/config/network.rs

@@ -1,5 +1,7 @@
 //! Network type for Zaino configuration.
 
+use std::fmt;
+
 use serde::{Deserialize, Serialize};
 use zebra_chain::parameters::testnet::ConfiguredActivationHeights;
 
@@ -28,6 +30,16 @@ pub enum Network {
     Regtest(ActivationHeights),
 }
 
+impl fmt::Display for Network {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Network::Mainnet => write!(f, "Mainnet"),
+            Network::Testnet => write!(f, "Testnet"),
+            Network::Regtest(_) => write!(f, "Regtest"),
+        }
+    }
+}
+
 /// Helper type for Network serialization/deserialization.
 ///
 /// This allows Network to serialize as simple strings ("Mainnet", "Testnet", "Regtest")

zaino-common/src/lib.rs

@@ -4,6 +4,7 @@
 //! and common utilities used across the Zaino blockchain indexer ecosystem.
 
 pub mod config;
+pub mod logging;
 pub mod net;
 pub mod probing;
 pub mod status;