Tracing

Consumer tracing is disabled by default. Enabling tracing is a separate choice from automatically discovering a configuration file or reading a readiness snapshot. Use the builder to state who installs and closes the application’s tracing runtime.

Choose the ownership mode#

Disabled mode does not search the current working directory for a tracing file. An explicit path that is missing or invalid does not silently fall back to disabled mode. External mode also does not read another owner’s configuration file or take over its lifecycle.

Console tracing example#

[dependencies]
lilyrs = { version = "0.1.0", features = ["consumer", "trace"] }

use lilyrs::consumer::{Consumer, ConsumerError};
use lilyrs::trace::TraceConfig;

async fn run_traced() -> Result<(), ConsumerError> {
    let mut config = TraceConfig::default();
    config.enabled = true;
    config.service_name = "orders-consumer".into();
    config.export.console = true;
    Consumer::builder().tracing_config(config).run().await
}

This function uses the first application’s linked handler and lily.toml; it does not define another queue. Keep the application’s existing dependencies and add trace to its facade features. TraceConfig::default() alone is not an enabled exporter; the example enables it explicitly.

The facade has no trace-file or trace-otlp feature. File rotation, OTLP, sampling, filters and attribute limits are runtime choices in TraceConfig. Service names and environment labels are observability data; the environment field does not select Lily’s configuration or secret-resolver environment.

Message context and component identity#

Validated W3C propagation metadata in the canonical envelope connects spans along the message flow. The current trace context can be captured when an outbox message is created, persisted with the database record and carried into relay publication. This connection does not guarantee broker acknowledgment or downstream business success.

Use .trace_cells(...) to provide component identities. TraceCellConfig contains id, worker_type, worker_name and kind; worker-type and component-kind matching is validated against the source contract. Do not use high-cardinality values such as event IDs as stable component identities. An empty list does not mean every handler requires a cell definition.

Relationship to snapshots and shutdown#

ManagedConsumer::snapshot() is available even when tracing is disabled. It describes bounded runtime state rather than successful span export or a full event audit log. Do not automatically add payloads, credentials or all headers to application spans; choose the diagnostic fields explicitly.

Owned tracing flush and shutdown share Consumer’s aggregate shutdown budget. The parent owner closes external tracing. Pending exporter data does not permit an unlimited wait; inspect shutdown evidence through the shutdown report.