Observability examples

Two runnable examples ship with Kerniq Observe, in the examples/ folder of the repository. This page is generated from their sources, so the code below is what CI builds and lints.

#observability-minimal

The smallest useful setup: HTTP metrics on /metrics for Prometheus and human-readable logs. No Collector required.

cargo run -p example-observability-minimal
curl localhost:3000/users/42
curl localhost:3000/metrics

rust

use kerniq_server::observability::prelude::*;
use kerniq_server::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let observability = Observability::builder()
        .service_name("minimal-api")
        .metrics(MetricsConfig::prometheus())
        .logs(LogsConfig::compact())
        .build()
        .await?;

    App::new()
        .observability(observability)
        .get("/health", || async { "OK" })
        .get("/users/{id}", |Path(id): Path<u64>| async move {
            tracing::info!(user_id = id, "user fetched");
            format!("user {id}")
        })
        .run("127.0.0.1:3000")
        .await
}

Source: examples/observability-minimal. Next steps: Prometheus for the scrape endpoint, Structured logging for log formats.

#observability-demo

A payments-and-inference service that exercises every Kerniq Observe feature. It is the sample application of observability/docker-compose.yml.

Configuration (environment):

Variable	Default	Meaning
`PORT`	`3000`	application port
`KERNIQ_METRICS`	`prometheus`	`prometheus` (Option A), `otlp` (Option B) or `both`
`KERNIQ_METRICS_PORT`	—	serve `/metrics` on its own port instead of `PORT`
`KERNIQ_OTLP`	`false`	export traces and logs over OTLP
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4317`	Collector (gRPC)
`KERNIQ_TRACE_RATIO`	`1.0`	trace sampling ratio
`KERNIQ_LOG_FORMAT`	`json`	`json`, `pretty` or `compact`
`KERNIQ_ENVIRONMENT`	`development`	`deployment.environment.name`

cargo run -p example-observability-demo
curl -X POST 'localhost:3000/payments?type=transfer&amount_minor=1250&currency=USD'
curl -N 'localhost:3000/v1/generate?model=chat-small&tokens=40'
curl localhost:3000/metrics

#Source files

File
`main.rs`	A payments-and-inference service that exercises every Kerniq Observe feature. It is the sample application of `observability/docker-compose.yml`.
`business.rs`	Business instrumentation: banking transactions, loan processing, database calls, authentication, outbound HTTP and queue processing.
`inference.rs`	A simulated LLM endpoint streaming tokens as server-sent events, with the `kerniq_telemetry::inference` conventions.

The business metrics it records are listed in Custom metrics, and the inference metrics in AI inference.

#Run it with Prometheus, Grafana, Tempo and Loki

# Option A: Prometheus scrapes the app (no Collector)
docker compose -f observability/docker-compose.yml --profile prometheus up --build

# Option B: OTLP → Collector → Prometheus, Tempo, Loki
docker compose -f observability/docker-compose.yml --profile otlp up --build

Then open Grafana at http://localhost:3001 (folder Kerniq). The stack, its dashboards and the load generator are described in Grafana dashboards and the local stack; the configuration files are in observability/.