Indicators
Where indicators live, the framework-shipped ones, and how to write a custom check with #[indicators] and per-method probe attributes.
An indicator is one check a probe runs: a method on an #[injectable]
provider, tagged with #[liveness], #[readiness], or #[startup]
inside an #[indicators] impl block. It returns
anyhow::Result<()> — Ok(()) reports up, Err(_) reports down. The
method’s name becomes the indicator’s key.
The probe body carries a fixed reason, never your error. A failed check
reports "check failed" (or "timed out"), and the anyhow chain goes to
the log instead: warn on nest_rs::health, with indicator, kind and
error as fields. A check that panics reports "check failed" too, its panic
filed once at error, health indicator panicked, and the probe still answers
for every other indicator. That is deliberate — /health/* is routinely
unauthenticated, and an error from a connection check carries a DSN, an
internal hostname or a driver message. Triage is one filtered log query;
it is not a value anyone can read off an open port.
A first indicator
Section titled “A first indicator”use std::sync::Arc;
use nest_rs::core::injectable;use nest_rs::health::indicators;
use crate::upstream::UpstreamClient;
#[injectable]pub struct UpstreamHealthIndicator { #[inject] client: Arc<UpstreamClient>,}
#[indicators]impl UpstreamHealthIndicator { #[readiness] async fn upstream(&self) -> anyhow::Result<()> { self.client.ping().await }}use nest_rs::core::module;
use crate::upstream::health::indicator::UpstreamHealthIndicator;
#[module(providers = [UpstreamHealthIndicator])]pub struct UpstreamHealthModule;use features::upstream::UpstreamHealthModule;use nest_rs::core::module;use nest_rs::health::HealthModule;
#[module(imports = [HealthModule, UpstreamHealthModule])]pub struct ApiModule;The indicator’s key on the wire is upstream (the method name); it
runs only on /health/ready.
Where an indicator lives
Section titled “Where an indicator lives”The dividing rule matches every other adapter: a file lives in
crates/features/ the moment another app could reuse it, and under
apps/<x>/ only when exposing it any higher would be dishonest.
| Scope | Home | Example |
|---|---|---|
| Framework primitive (any nestrs project) | crates/nest-rs-<concern>/ behind a Cargo feature | redis, from RedisModule (next section) |
| Product feature (any app of this repo) | crates/features/<feature>/health/ | UpstreamHealthIndicator above |
| App-specific glue (this binary only) | apps/<x>/<feature>/health/ (exception) | a deployment-quirk check |
A loose health.rs at the root of apps/<x>/src/ is never the answer:
apps/<x>/ is composition only (main.rs + module.rs), so the file
would belong to no #[module]. See Monorepo
layout for
the full rule.
Framework-shipped indicators
Section titled “Framework-shipped indicators”A resource the framework opens ships its check in the crate that opens it,
behind that crate’s health feature — which cargo add nest-rs --features health turns on beside the resource’s own feature, so the manifest still names
the umbrella alone. The module that opens the resource attaches its check, so
HealthModule checks every resource your app or its features opened, and you
import nothing beside it:
| Resource | Opened by | Key | Check |
|---|---|---|---|
| The SeaORM pool | SeaOrmModule | seaorm | DatabaseConnection::ping |
| A Redis instance | RedisModule | redis | PING on the instance’s connection |
| A named Redis instance | RedisModule::<Cache> | redis:cache | the same, on that instance |
| The object store | StorageModule | storage | one page of the bucket’s listing |
The queue and the outbox are read through the Valkey and the pool they run on; the OTLP collector, an authorization server and a social provider have no check, because their outage must not take every replica out of rotation.
use nest_rs::core::module;use nest_rs::health::HealthModule;use nest_rs::redis::RedisModule;use nest_rs::seaorm::SeaOrmDatabaseModule;use nest_rs::storage::StorageModule;
#[module( imports = [ SeaOrmDatabaseModule, RedisModule, StorageModule, HealthModule, ],)]pub struct ApiModule;$ curl -s http://localhost:3000/health/ready | jq '.details | keys'[ "redis", "seaorm", "storage" ]A resource a binding or a feature opens is checked the same way. The demo’s audio feature
opens the store and a second Valkey, transcodes; the api app imports the
feature and HealthModule, never those resources, and its readiness reads
redis:transcodes and storage beside its own. Two modules opening one
resource report it once.
Each check runs on /health/ready and /health/startup, never on
/health/live: the orchestrator should not restart a pod because the
database or a Valkey blinked. A check answers within the ceilings of
Health, and its resource’s own budget bounds what it
sends — the Redis connection’s
<PREFIX>_REDIS__CONNECT_TIMEOUT_SECS, for one.
A key names the resource, never the probe. A framework indicator is named
for the crate owning the resource, plus : and the instance for a
named one — redis:cache for the
instance RedisModule::<Cache> opens — so a readiness 503
says which Valkey went away. Your own indicator keeps its method name: a method
named redis in an app that opens Redis fails the boot naming both, and the
fix is to drop yours.
A check exists where the module opening its resource is imported. A
seeded or overridden connection is what the pool’s or an instance’s check
pings — a suite booting on ephemeral_database still reads seaorm — while a
test that overrides Storage opens no store, and probes none.
What each check reads.
- The pool’s is a round-trip,
SELECT 1. - A Redis instance’s is a
PING, which every binding’s ACL rule already grants. On a Cluster it reaches every primary, so a primary down readsdownuntil its replica takes over. - The store’s is one attempt of the proof it passed at boot: a page of the
bucket’s listing under the URL’s prefix. A store reached over verified TLS
reads up even when it answers a
403naming no rejected key — most often a policy withouts3:ListBucket— as it boots, and the probe that first meets that refusal files the boot’swarnnaming the credential variables, so a policy revoked under a running app is said once; a key the store rejects, a bucket gone, a redirect, or no answer reads down. It sends that request on every probe, so a store billing per request bills the orchestrator’s probes too. Amemory:///store has nothing to reach and reads up.
See Database health for the pool end to end.
An indicator a module attaches
Section titled “An indicator a module attaches”#[indicators] names a check after its method, and a link-time registry
holds no generic type — so a resource opened once per instance cannot be
checked that way. A package that opens one ships its check as the framework
does: the module opening the resource attaches an IndicatorEntry from its
register, which runs only when an app imports it, so the check is gated like
every other discovered item and the app imports nothing more. Its key is
rooted at the package’s crate, as every name it owns is
(Naming a package): nestrs_acme, and
nestrs_acme:<instance> for a named one.
The attaching module is imported by type. Two features may each call
AcmeModule, bare or through its for_root, and the entry must land once.
AcmeModule is imported by type, and ConfigModule::setup imports it by type
too, so its register runs once per app — as SeaOrmModule and RedisModule
open their pool or instance. Never attach from a hand-written
DynamicModule’s own register: it runs once per import site, so the second
feature’s entry claims the key again and the boot’s name check refuses it.
use nest_rs::config::{ConfigModule, ConfigSetup};use nest_rs::core::{Collecting, Container, ContainerBuilder, Module, Registering, Unnamed};use nest_rs::health::{IndicatorEntry, IndicatorFuture, ProbeKind};
use crate::{AcmeClient, AcmeConfig};
fn ping(container: &Container) -> IndicatorFuture<'_> { Box::pin(async move { let client = container .get::<AcmeClient>() .ok_or_else(|| anyhow::anyhow!("AcmeModule opened no client"))?; client.ping().await })}
pub struct AcmeModule;pub type AcmeSetup = ConfigSetup<AcmeModule, AcmeConfig>;
impl AcmeModule { pub fn for_root(config: AcmeConfig) -> AcmeSetup { ConfigModule::setup(config) }}
impl Module for AcmeModule { fn collect(builder: ContainerBuilder, _: Collecting<Self>) -> ContainerBuilder { ConfigModule::provide_feature::<Unnamed, AcmeConfig>(builder) .provide_factory(|_| AcmeClient::connect()) }
fn register(builder: ContainerBuilder, _: Registering<Self>) -> ContainerBuilder { builder .provide_meta(IndicatorEntry::new::<Self>("nestrs_acme", ProbeKind::Readiness, ping)) .provide_meta(IndicatorEntry::new::<Self>("nestrs_acme", ProbeKind::Startup, ping)) }}Both registries answer the same probes and pass one name check at boot: two indicators claiming a key on one probe fail it naming the method’s module and the type of the module that attached the entry.
Going further
Section titled “Going further”- Discovery — what
#[indicators]registers, and how module-gating decides which indicators fire. - Database / Health — the pool’s indicator end to end.
- Providers —
#[injectable], the access graph, and what makes a provider reachable.