hermod/lib.rs
1//! hermod — Rust implementation of the Cardano trace-forward protocol
2//!
3//! This crate provides two things:
4//!
5//! 1. **A forwarder library** — embed in your Cardano node or any Rust application
6//! to ship traces to a running `hermod-tracer` instance via the Ouroboros Network
7//! mux protocol.
8//!
9//! 2. **A full tracer server** ([`server`]) — run as the `hermod-tracer` binary to
10//! accept trace connections, write log files, serve Prometheus metrics, and
11//! optionally re-forward to a downstream collector. The server reads a
12//! Haskell-compatible YAML config, so existing `cardano-tracer` config files work
13//! unchanged.
14//!
15//! # Quick start — forwarding traces from your application
16//!
17//! ```no_run
18//! use hermod::forwarder::{ForwarderAddress, ForwarderConfig, TraceForwarder};
19//! use hermod::tracer::TracerBuilder;
20//! use std::path::PathBuf;
21//! use tracing_subscriber::prelude::*;
22//!
23//! #[tokio::main]
24//! async fn main() {
25//! let config = ForwarderConfig {
26//! address: ForwarderAddress::Unix(PathBuf::from("/tmp/hermod-tracer.sock")),
27//! network_magic: 764824073, // mainnet
28//! ..Default::default()
29//! };
30//! let forwarder = TraceForwarder::new(config);
31//!
32//! // Build and plug into tracing-subscriber (also spawns forwarder)
33//! let (layer, _fwd) = TracerBuilder::new(forwarder).build();
34//! tracing_subscriber::registry().with(layer).init();
35//!
36//! tracing::info!("Hello from hermod!");
37//! }
38//! ```
39//!
40//! # Module overview
41//!
42//! | Module | Description |
43//! |--------|-------------|
44//! | [`protocol`] | Wire types: `TraceObject`, `Severity`, `DetailLevel` and CBOR codecs |
45//! | [`mux`] | Ouroboros Network mux layer — handshake and mini-protocol clients |
46//! | [`forwarder`] | Async forwarder that ships traces to `hermod-tracer` |
47//! | [`acceptor`] | Lightweight acceptor — receive traces over a socket |
48//! | [`dispatcher`] | Route and filter traces to multiple backends |
49//! | [`tracer`] | `tracing-subscriber` integration layer |
50//! | [`server`] | Full `hermod-tracer` server (file logging, Prometheus, EKG, re-forwarding) |
51
52#![warn(missing_docs)]
53
54pub mod acceptor;
55pub mod dispatcher;
56pub mod forwarder;
57pub mod mux;
58pub mod protocol;
59pub mod server;
60pub mod tracer;
61
62/// Library version
63pub const VERSION: &str = env!("CARGO_PKG_VERSION");
64
65#[cfg(test)]
66mod tests {
67 use super::*;
68
69 #[test]
70 fn test_version() {
71 assert!(!VERSION.is_empty());
72 }
73}