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 - Distributed traces to Jaeger via OpenTelemetry
- Health - Health check endpoint at
/health
Local observability stack
When running npm run dev, the following services are available:
Default Grafana credentials: admin / admin
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. Cloud deployments do not set it, so deployed services log at info. 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, common fields like password, email, ssn, creditCard, token, secret, and apiKey are redacted.
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:
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
Distributed tracing helps debug requests across services. Traces are sent to Jaeger via OpenTelemetry OTLP.
Automatic tracing
HTTP requests are automatically traced. The TracingInterceptor creates spans for each request with:
- HTTP method and route
- Status code
- Duration
- Error details (if any)
Viewing traces
- Make a request to your API
- Open Jaeger UI: http://localhost:16686
- Select your service from the dropdown
- Click "Find Traces"
Manual spans
For custom operations within a request:
Trace context in logs
When tracing is enabled, logs automatically include trace_id and span_id. This allows you to correlate logs with traces in your observability platform.
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, and AKS automatically capture stdout and route it to their respective logging services.
For tracing in production, configure OTEL_EXPORTER_OTLP_ENDPOINT to point to your trace collector (Cloud Trace, X-Ray, or Application Insights).