Module logs 

Client-side log collection: a tracing-subscriber layer that writes structured log records to rolling files on the local filesystem, plus a reload handle that lets the cloud control the level filter at runtime.

The cloud is the source of truth for the level

The level filter starts at off. No tracing events are captured until the cloud pushes a crate::protocol::SetLogLevel over the ClientHost channel. The cloud sends one immediately after authenticating a connected endpoint, derived from the per-endpoint endpoint_log_settings row (when present) plus the project default.

Files live on the device

Records land in rolling JSON files under a caller-supplied directory. Operators view, ship, or aggregate them with whatever tooling they already use (tail, journalctl, vector, etc.).

Typical usage

use iroh_services::logs::{self, FileLoggerConfig};

// Installs a global subscriber. The filter starts at `off`; the
// Client pulls the cloud-persisted directive right after Auth and
// applies it via the collector. The dashboard can also push live
// overrides via ClientHost::set_log_level after that.
let (collector, _guard) = logs::install(FileLoggerConfig::new("./logs"))?;

Compose with additional layers (for example, a stderr fmt layer) via layer:

use iroh_services::logs::{self, FileLoggerConfig};
use tracing_subscriber::prelude::*;

let (collector, file_layer, _guard) = logs::layer(FileLoggerConfig::new("./logs"))?;
tracing_subscriber::registry()
    .with(file_layer)
    .with(tracing_subscriber::fmt::layer())
    .try_init()
    .ok();

Structs

FileLoggerConfig

Configuration for the rolling file logger.

LogCollector

Handle to the cloud-controlled tracing filter. Cheap to clone; all clones share the same backing reload handle.

Rotation

How often the rolling file appender starts a new file.

WorkerGuard

Guard returned by file_layer / layer / install that keeps the non-blocking writer’s worker thread alive. Drop this only at process shutdown; once dropped, any buffered records still in flight are flushed and the file layer stops accepting writes. A guard that flushes spans/events associated to a [NonBlocking] on a drop

Enums

FileLoggerError

Errors raised when constructing the file logger.

InstallError

Errors that can occur while installing the log collector.

SetFilterError

Errors that can occur while changing the active filter at runtime.

Functions

file_layer

Builds an unfiltered tracing layer that writes records to a rolling file under config.dir. Returns the layer plus a WorkerGuard the caller must hold for the lifetime of the process — drop it at shutdown so any buffered records flush before exit.

install

Installs a global tracing subscriber whose only output is a rolling file appender under config.dir. The level filter starts at off; the cloud must push a SetLogLevel for any events to be captured.

layer

Builds the cloud-controlled file layer and its LogCollector without installing a global subscriber. Use this when composing the file layer with other layers; the returned layer is pre-wrapped in the reloadable filter so the cloud’s SetLogLevel overrides take effect.