Observability
tsdevstack includes a complete observability stack: structured logging, Prometheus metrics, distributed tracing, and health checks. All features are enabled by default when you import ObservabilityModule.
Quick start
Import the module in your app:
This enables:
- Logging - Structured JSON logs with Pino
- Metrics - Prometheus-compatible metrics at
/metrics - Tracing - One OpenTelemetry trace per request, to Jaeger locally and to your cloud's trace service when deployed
- Health - Health check endpoint at
/health
For deployed environments, see Cloud Logs (reading logs from the terminal) and Traces and Dashboards.
Local observability stack
When running npm run dev, the following services are available:
Grafana's dashboards are in the tsdevstack folder and open without a login. Sign in with admin / admin to edit them.
Logging
The LoggerService provides structured JSON logging with automatic trace context injection.
Basic usage
Log methods
Log output
In development, each entry is one line: time, level, [context], message, then any extra fields. The service name comes from the dev runner's line prefix.
In production, logs are JSON for log aggregation:
Request logs
Each request logs one entry when it ends, in the HTTP context. The message summarizes the request. The request fields are grouped under http; the local one-line output hides them, since the message already shows them:
- Successful requests log at
info. - Client errors (4xx) log at
warn, with the error message inreasonand no stack trace. - Server errors (5xx) log at
error, with the stack trace. /healthand/metricslog atdebug. A failing probe logs atwarn.correlationIdis Kong's request id (X-Request-ID), also returned to the client asX-Correlation-ID. Requests with a partner API key addapiKeyIdandapiKeyConsumer.
Nest's own messages (startup, routes, unhandled errors) use the same logger and the same LOG_LEVEL: JSON in the cloud, one line locally. An unhandled error is logged once.
Configuration
Set LOG_LEVEL environment variable to control log verbosity:
debug- All logsinfo- Info and above (default)warn- Warnings and errorserror- Errors only
Locally, the generated .env sets LOG_LEVEL=debug. Deployed services and workers log at the logLevel set for them in infrastructure.json, info by default (see Cloud Logs). Framework classes that log through Nest's Logger follow the same level.
PII redaction
The logger automatically redacts sensitive data to prevent PII from appearing in logs. By default it redacts these fields:
- Personal data:
email,ssn,creditCard - Passwords:
password,newPassword,currentPassword,passwordHash - Tokens and keys:
token,accessToken,refreshToken,secret,privateKey,apiKey - Request headers:
authorization,cookie,set-cookie,x-api-key,x-kong-trust,x-tsdevstack-frontend-token(lowercase, as Node gives them inreq.headers)
Each name is matched at the top of the entry and one level down: { password } and { user: { password } }, or { headers: req.headers }. A field nested deeper, like { body: { user: { email } } }, is logged as it is. Add a path for it (below) or log the inner object.
Custom redaction paths
Configure additional paths to redact:
Or via environment variable:
Disabling default redaction
If you need full control over redaction paths:
Path syntax
Redaction paths support wildcards:
Each pattern matches one depth only, so a pattern per level is needed.
Metrics
The MetricsService provides Prometheus-compatible metrics using OpenTelemetry.
Built-in metrics
These metrics are automatically collected for all HTTP requests:
Metrics include labels: method, route, status_code
Accessing metrics
Each service exposes metrics at /metrics:
Prometheus scrapes these endpoints automatically.
Custom metrics
Available metric types:
Tracing
Each request gets one span around everything Nest does with it: guards, interceptors, the handler and the exception filter. It records the method, the route (/auth/v1/users/:id) and the status code. A 5xx response marks the span as an error; a 4xx is an answer, not a failure. Health checks and /metrics get no span.
The span continues the trace Kong started. Calls through generated clients carry the trace to the next service, and BullMQ jobs, messages and Prisma queries join it. Locally, open Jaeger at http://localhost:16686, pick a service and click Find Traces.
Every line logged inside a request carries trace_id and span_id, the request line included.
What a trace contains, where it goes in each cloud, sampling and your own spans: Traces and Dashboards.
Health checks
The health endpoint provides service status for load balancers and orchestrators.
Endpoints
Health check response
Status values: ok, degraded, down. /health always answers HTTP 200. It is the liveness check that Cloud Run, ECS and Container Apps act on, so a Redis outage shows as degraded in the body and the service keeps running. It does not check the database: a service starts listening only once its database answers (waitForDatabase() in PrismaService).
Configuring health checks
Redis is checked automatically when the service imports RedisModule. ObservabilityModule.forRoot({ health: false }) turns the health endpoints off.
Configuration options
Customize observability features:
Environment variables:
Infrastructure endpoints
Health and metrics endpoints are marked @Public() and excluded from API documentation (@ApiExcludeController()). They bypass authentication so load balancers and monitoring systems can access them.
These routes also bypass Kong's trust header requirement since they're infrastructure endpoints, not user-facing APIs.
Cloud environments
In production, logs are sent to your cloud provider's logging service. The JSON format produced by Pino integrates seamlessly with:
No code changes required: the same JSON logs work everywhere. Cloud Run, ECS, Container Apps and App Service capture standard output and send it to the cloud's logging service. Read them from your terminal with infra:logs.
Traces go to Cloud Trace, X-Ray or Application Insights without configuration. See Traces and Dashboards.