Skip to content

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.

crates/features/src/upstream/health/indicator.rs
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
}
}
crates/features/src/upstream/health/module.rs
use nest_rs::core::module;
use crate::upstream::health::indicator::UpstreamHealthIndicator;
#[module(providers = [UpstreamHealthIndicator])]
pub struct UpstreamHealthModule;
apps/api/src/module.rs
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.

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.

ScopeHomeExample
Framework primitive (any nestrs project)crates/nest-rs-<concern>/ behind a Cargo featureredis, 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.

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:

ResourceOpened byKeyCheck
The SeaORM poolSeaOrmModuleseaormDatabaseConnection::ping
A Redis instanceRedisModuleredisPING on the instance’s connection
A named Redis instanceRedisModule::<Cache>redis:cachethe same, on that instance
The object storeStorageModulestorageone 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.

apps/api/src/module.rs
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;
Terminal window
$ 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 reads down until 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 403 naming no rejected key — most often a policy without s3:ListBucket — as it boots, and the probe that first meets that refusal files the boot’s warn naming 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. A memory:/// store has nothing to reach and reads up.

See Database health for the pool end to end.

#[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.

crates/acme/src/module.rs
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.

  • 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.