Tracing, metrics, and health

Tracing is disabled by default. Enable telemetry with your application's choice of exporter and ownership. The health snapshot provides a read-only view of the application's HTTP lifecycle.

Enable tracing#

let mut config = lilyrs::http_api::TraceConfig::default();
config.enabled = true;
config.service_name = "users-api".into();
config.export.console = true;
let builder = lilyrs::http_api::AppBuilder::new("127.0.0.1:8080")
    .tracing_config(config);

TraceConfig and builder support are available through http-api; this example needs no separate trace dependency. To use the public lilyrs::trace module directly, add the trace feature to the same lilyrs dependency. This feature enables the console option; file and OTLP exporters are selected through runtime configuration.

Add this builder snippet to your application's startup chain. TraceConfig::default() alone does not enable tracing; enabled = true is required. Strict tracing_config_path(path) is an alternative.

Exporter ownership#

App-owned tracing starts before DI setup and is flushed after DI shutdown. If you choose tracing_external(), install the provider before build and complete its shutdown in the external application.

Console, file rotation, OTLP, sampling, and filter options are part of the lily_trace configuration surface. HTTP request/status/duration/body-byte, admission, timeout, connection, and DI lifecycle telemetry can be observed together.

Prefer route templates in metric labels over unbounded values such as user IDs. Preserve the distinction between application rejection and technical failure through the response outcome contract.

Readiness endpoint#

Import HttpHealthService, Service, ResponseBuilder, and HttpApiError in the controller and add this action:

#[get("/ready")]
async fn ready(&self, Service(health): Service<HttpHealthService>)
    -> Result<ResponseBuilder, HttpApiError>
{
    let snapshot = health.snapshot()
        .map_err(|_| HttpApiError::ServiceUnavailable("health unavailable".into()))?;
    let (code, reason) = if snapshot.ready { (200, "OK") } else { (503, "Service Unavailable") };
    Ok(ResponseBuilder::new().status(code, reason).json(snapshot))
}

It returns 200 when snapshot.ready is true and 503 otherwise. Returning the snapshot as JSON alone does not establish the HTTP readiness status policy; the example selects the status explicitly.

Health coverage#

The framework does not automatically add a /health route or probes for every database. The snapshot is the HTTP host's health view. Explicitly define your own health policy for additional application dependencies.