Health Checks

The SDK registers a PostgreSQL health check automatically. The host application exposes the standard ASP.NET Core health endpoints via MapDefaultEndpoints() (provided by BeaconTower.Observability.AspNetCore).

Endpoints

Endpoint	Purpose	Behaviour
/alive	Liveness probe	Returns 200 when the process is running. Should only fail on a deadlock.
/ready	Readiness probe	Returns 200 only when all health checks (tagged ready) pass.
/health	Detailed report	JSON with each registered check's status.

Response shape

{
  "status": "Healthy",
  "totalDuration": 0.35,
  "checks": [
    {
      "name": "npgsql",
      "status": "Healthy",
      "duration": 0.31,
      "description": null,
      "error": null,
      "data": {}
    }
  ]
}

status ∈ Healthy | Degraded | Unhealthy.

What the SDK registers

Check	Registered by	Verifies
npgsql	reference host (AddHealthChecks().AddNpgSql(connStr, tags: ["ready"]))	PostgreSQL connection is open and responsive.

The SDK itself does not register health checks for NATS or MQTT. Those subsystems handle their own reconnection — a transient NATS outage doesn't mean the provider is unhealthy. If you want to surface NATS state, register a custom check (see below).

Diagnostics surface (snapshot endpoint)

GET /api/diagnostics/info returns a runtime snapshot — provider id, build version, and a count of currently-tracked devices and active log filters. It is part of the diagnostics REST surface, not the health-check pipeline; it requires JWT auth and is gated by Diagnostics:Enabled. See Reference › Diagnostics.

Diagnostics:Enabled = false short-circuits all /api/diagnostics/* endpoints (including /info) with HTTP 404 — see Operational Notes › Diagnostics enable-toggle. The probes at /alive / /ready / /health are unaffected.

Kubernetes integration

livenessProbe:
  httpGet:
    path: /alive
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5

• Liveness — if /alive fails, Kubernetes restarts the pod. Failure indicates the process is deadlocked.
• Readiness — if /ready fails (e.g. PostgreSQL unreachable), Kubernetes removes the pod from the service so no traffic routes to it until it recovers.

Adding custom health checks

builder.Services.AddHealthChecks()
    .AddCheck("my-broker", () =>
    {
        var adapter = serviceProvider.GetRequiredService<MyAdapter>();
        return adapter.IsBrokerConnected
            ? HealthCheckResult.Healthy()
            : HealthCheckResult.Degraded("Broker disconnected, reconnecting");
    });

Tag a check with "ready" if it should gate the readiness probe.

Monitoring

BeaconTower.Observability.AspNetCore exposes health-check duration and status as OpenTelemetry metrics. In Grafana / Prometheus:

aspnetcore_healthchecks{name="npgsql", status!="Healthy"}

Pair this with the pipeline metrics from Telemetry Pipeline › Metrics for end-to-end provider observability.