DEV Community: Kamil Mysliwiec

NestJS and OpenTelemetry: why we instrument the framework instead

Kamil Mysliwiec — Tue, 20 Oct 2026 07:18:40 +0000

When we started working on NestJS Observe, one of the first questions was straightforward: why not OpenTelemetry?

Fair question. OpenTelemetry is the industry standard, it's vendor-neutral, and a lot of smart people have been working on it full time for years. If you're standardising telemetry across a whole company and a dozen languages, it's the obvious choice, and further down I'll go through exactly when it's the better fit.

We made a different trade-off, on purpose. Here's what it was, what you get from it, and what it costs.

OpenTelemetry in a NestJS app: the setup

The setup first, since that's what most people looking up NestJS and OpenTelemetry are after. The zero-code route needs two packages:

npm i @opentelemetry/api @opentelemetry/auto-instrumentations-node

The instrumentation has to load before Nest does, so it goes on the node command rather than into main.ts. For a CommonJS build, which is what nest new generated up to Nest 11:

OTEL_SERVICE_NAME=orders-api \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
node --require @opentelemetry/auto-instrumentations-node/register dist/main.js

A project generated by nest new on Nest 12 builds ES modules, and for those OpenTelemetry needs its loader hook as well:

OTEL_SERVICE_NAME=orders-api \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
node --experimental-loader=@opentelemetry/instrumentation/hook.mjs \
  --import @opentelemetry/auto-instrumentations-node/register dist/main.js

That gives you spans for incoming and outgoing HTTP, Express and the common database drivers (pg, mysql2, mongodb, Mongoose). On NestJS 11 and earlier, @opentelemetry/instrumentation-nestjs-core adds Nest's own entry points as well. It doesn't cover NestJS 12 yet: support was added in September and reverted in October after it broke some bundled builds, so a Nest 12 app currently gets the HTTP and driver spans only. All of them go to whatever listens on port 4318, so you also need a backend. For a first look on your machine, Jaeger in a single container is enough:

docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger

Open http://localhost:16686, make a request, and the trace is there. In production that container becomes a collector and a backend you operate, or a vendor that accepts OTLP.

That's the whole setup. The rest of this post is about what those traces show you, what they don't, and why we built something else.

What OpenTelemetry is good at

Credit first, because it's deserved.

It's a standard and not a product. You instrument once and send the data anywhere, and you can change backends without touching application code. It's polyglot, so your Go service, your Python worker and your Node API all speak the same protocol and share one trace. The library coverage is enormous: Redis, Kafka, the AWS SDK, gRPC, dozens of databases, somebody has already written the instrumentation. And it's yours. Run the collector in your own network and the data never leaves.

Those strengths are real, and this is not an argument against OpenTelemetry. The distinction is that it addresses a broader organizational problem than the immediate debugging problem a NestJS team may be facing.

The problem we wanted to solve

A developer has a Nest app in production. Something is slow. They want to know which of their classes is responsible, and they want to know in the next ten minutes, not after a sprint of infrastructure work.

Two things stand in the way.

The setup

A working OpenTelemetry pipeline for a Node.js service means the SDK and its auto-instrumentations, an exporter, usually a collector, and a backend to store and query. To be fair, the first half has gotten short, as the commands above show. Running the backend, keeping the versions in step and turning raw spans into something a team actually looks at is the part that isn't short.

None of those steps is mysterious, but together they are still operational work that competes with product work. That effort is one reason an application may have logs in production without having traces. Instrumentation only helps once a team has installed and maintained it.

The vocabulary

This is the more interesting one.

Generic Node.js instrumentation sees your app from the outside. An HTTP request came in, some middleware ran, a database driver got called, a response went out. OpenTelemetry's NestJS instrumentation adds the framework's entry points: on NestJS 11 and earlier it emits three kinds of span, one for application creation, one for the request context (Controller.method), and one for the route handler. On NestJS 12 it doesn't run at all yet.

That's useful, and it stops exactly where a Nest app starts being interesting. Your code isn't a handler. It's a controller that calls a service that calls two other services and a repository, behind a guard, inside an interceptor, after a pipe. When a request takes 1.8 seconds, the question is never "was it the handler". Of course it was the handler. The question is which provider.

To get that out of OpenTelemetry you mostly add spans by hand. A decorator on every method you care about, or tracer.startActiveSpan calls sprinkled through your service layer. Teams do this. It's a lot of code, it goes stale, and it only ever covers the methods somebody already suspected. Some vendors built on OpenTelemetry go further (Sentry's Nest SDK adds spans for guards, pipes and interceptors), but the providers underneath, where the time actually goes, still aren't in the tree unless you put them there.

What "from the inside" means

Nest is a dependency injection framework. Every provider (controller, service, repository, guard, interceptor, pipe) gets instantiated by the container. So for every single one of them there's a moment where the framework holds the instance before anybody else does.

Nest exposes that moment through the instrument option of NestFactory.create():

const app = await NestFactory.create(AppModule, {
  instrument: ObserveInstrument,
});

instrument.instanceDecorator is called with every instance the container creates: classes it constructs, factory results, useValue providers, even global enhancers. @nestjs/observe returns a Proxy around each one that wraps methods lazily on first access and keeps their names and reflect-metadata intact, so Nest's own reflection still works. Calls run with the proxy as this, which is why this.pricing.quote() inside a service shows up as a child span. For your own classes there's no patching of module internals, no preload and no load order to worry about, because the framework simply hands us the instances. (Database drivers are a different story. pg, mysql2, mssql and mongodb we do patch, like everybody else, because no framework owns them. Outbound HTTP we don't patch at all: it's read from Node's diagnostics_channel.)

From then on, every method you call on a provider during a request, job or message becomes a span, named the way you named it:

POST /orders                          1,812 ms
  AuthGuard.canActivate                   3 ms
  OrdersController.create             1,806 ms   self 1 ms
    OrdersService.create              1,805 ms   self 6 ms
      CustomersService.findById          12 ms
        SELECT customers                 11 ms
      PricingService.quote               38 ms
      PaymentsService.charge          1,749 ms
        POST api.stripe.com           1,747 ms

Nobody wrote a span for PricingService.quote. Nobody had to guess ahead of time that it might matter. And since the tree is complete, self time (a span's duration minus its children) can be computed instead of guessed: OrdersController.create took 1.8 seconds and did one millisecond of actual work, and the trace says so. (When children run in parallel, say under Promise.all, their durations overlap and a parent's true self time is unknowable. Observe shows 0 there rather than inventing a number.)

That is the capability we were trying to make easy. It is not a claim that the tracing model is universally better; it follows from being inside the framework rather than observing it from the outside.

The same position is why the rest works without config. HTTP, microservices and GraphQL come in through hooks in Nest's adapters, the ones that also give us the route template rather than the raw URL. For BullMQ, Bull, @nestjs/schedule and WebSocket gateways we hook the Nest integration packages directly, which is manageable because we maintain those too. Either way the agent knows what a queue consumer is, what a @Cron() handler is, what a gateway's @SubscribeMessage() is, what a GraphQL resolver is, and records each as what it is, not as an HTTP request that looks a bit weird.

The pipeline

We didn't want the second half of the setup either. The agent encodes finished traces into a shared buffer, and a worker thread picks up the batch every few seconds, gzips it and POSTs it to our API, off the thread that serves your requests. No collector to run, no exporter to configure. Two env variables, a module in AppModule, and the instrument option.

It isn't free. Every property read on an instrumented provider goes through a proxy trap, and every traced call allocates a bit of async context. If that matters at your volume, tracesSampleRate samples at the head of the request, and sampled-out requests skip the span bookkeeping.

A product, not just a pipeline

An OpenTelemetry backend stores spans and lets you query them. What you do with them afterwards, grouping errors, deciding what pages someone, tracking the fix, is a second product you pick or something you build. Observe ships those parts with the tracing:

Error grouping. Occurrences are grouped into defects, split into handled and unhandled, and shown with the failing source lines, when the defect was first and last seen, and the release it first appeared in. A new unhandled one sends an email, on every plan.
Logs. Every ConsoleLogger line written during a traced operation carries its trace id by default. Turn on forwardLogs and the lines are collected too, redacted in your process, and shown under the trace they were written in.
Releases and regressions. Every request and job records the release that served it, and each release is compared with the one before it on error rate, latency and throughput. "What changed in the code" lists the queries, outbound calls and methods whose behaviour moved across the deploy, so a regression comes with a starting point.
Alerts. Rules on latency, error rate, job failures and queue wait, log patterns, new error groups, runtime metrics, and silence (an app or a cron that stopped reporting), delivered to email, Slack, a webhook, or straight into an issue.
Issues and incidents. An issue links to the error, request or trace it came from, and opens with an incident record: how many users and which customers were affected, a timeline from the release onwards, and a summary you can paste into the postmortem. Resolve it with the release that shipped the fix, and Observe watches that operation's telemetry to tell you whether the fix held.
An MCP server. Claude Code, or any MCP client, can ask the same questions directly: find_regressions, diff_release, get_trace, get_trace_logs, instead of you copying dashboard data into a prompt.

Error grouping, tracing and the new-error email are on every plan, Free included; log forwarding and alert rules start on Pro, and MCP access depends on the plan too. None of it is impossible with OpenTelemetry. It's the backend you'd choose, the alerting you'd configure and the glue you'd write, and keep running.

This part of the trade-off also has a clear cost.

What it costs

You're choosing a product, not a standard. The data goes to Observe. There's no OTLP export today and no OTLP ingest. You can't point an existing collector at us and you can't point our agent at your existing backend. If vendor-neutrality is a hard requirement for you, that ends the conversation, and it should.

It's NestJS on Node.js and nothing else. A Go service in the same request path won't show up in the trace. We correlate across services with a request id header (x-request-id) and not with W3C traceparent. Between Nest services that works on its own over fetch and undici, and over axios or HttpModule on Node 22.12 and later. The default generator also adopts an incoming x-request-id, so an id set by your load balancer carries through. To a service that isn't running our agent it means nothing.

Library coverage is narrower than OTel's, though less narrow than "four drivers" suggests. At the driver level, the agent records database queries through pg, mysql2, mssql and mongodb (so TypeORM, Drizzle, MikroORM, Mongoose and Prisma's pg and SQL Server adapters are covered) and outbound HTTP. Everything else you register as a Nest provider is instrumented the same way as your own classes, and that's how most apps wire up their Redis and Kafka clients. So an ioredis client injected into a service shows up as Redis.get under the method that called it, without anyone writing a span. For code that lives outside the container entirely, a client created with new inside a method or a plain function, there's a manual API:

await this.tracer.createSpan('pdf.render', () => renderInvoicePdf(order));

Yes, that's exactly the manual work I complained about above. It's just a much smaller surface.

And it's a hosted service. If your telemetry can't leave your network, this isn't for you.

When you should use OpenTelemetry instead

You run several languages and want one trace across all of them. You already operate a collector and a backend and they work. You need to keep telemetry on infrastructure you control. You depend heavily on libraries we don't instrument and their spans matter to you. You want to be able to change vendors without touching code.

If two of those conditions apply, OpenTelemetry is likely the better fit because its standardization and deployment model address those requirements directly.

When this trade-off is the better one

Your backend is NestJS, or mostly NestJS. You don't have tracing today, and the real reason is that nobody had the week. The question you keep asking is "which of our classes is slow", and route-level data keeps not answering it. You'd rather run one less piece of infrastructure.

For that team, the practical alternative may not be a carefully tuned OpenTelemetry pipeline; it may be continuing without tracing. Observe is intended for the gap between deciding that tracing would help and having the time to operate a full pipeline.

Can you run both?

In principle, yes. The agent doesn't depend on OpenTelemetry and doesn't replace any of it, so you can install them side by side, which is a decent way to compare them on real traffic. Both hook the database drivers though, so try it on staging first instead of taking my word for it. They won't share a trace. Different ids, different propagation.

Should Observe speak OTLP, so that the Go service shows up in the same picture? We get asked this a lot. It's not there today and I'd rather say that plainly than hint at something.

To sum up

OpenTelemetry answers "how does an organisation standardise telemetry". We wanted to answer "why is this NestJS endpoint slow, and can I know by lunch".

Being the framework's own team meant we could put the hooks we needed into Nest itself. They're public, and anyone can build on them; we built a product around them. Nest hands us every provider the moment it creates it, and we used that to make the trace look like your code and the setup a few lines long. Everything else about the trade-off, the lock-in and the narrower coverage, comes from choosing depth in one framework over breadth across all of them.

If that trade-off does not fit, OpenTelemetry remains a strong standard choice. If it does, the setup is npx @nestjs/observe link, which installs the SDK, wires it into your app and writes the key into .env.

You can look at a real trace before deciding. The live demo needs no signup.

NestJS Observe vs Sentry, Datadog and OpenTelemetry: which one for a NestJS app?

Kamil Mysliwiec — Fri, 09 Oct 2026 07:45:24 +0000

One disclosure up front: I created NestJS and my team builds Observe, so this comparison has a clear point of view. The statements about the other tools were checked against their documentation in September 2026; those details can change, so verify them for your own setup.

Every monitoring tool can trace a NestJS app. Only one of them was built from inside the framework, and that changes what a trace can show you. That's the short version of this whole post.

The four realistic options for a Nest backend:

NestJS Observe, the framework's own
Sentry, which is error tracking first with performance monitoring grown around it
A full-platform APM like Datadog, New Relic or Dynatrace
OpenTelemetry plus a backend: Grafana's stack, SigNoz, Jaeger, or any vendor that ingests OTLP

The short answer

If your backend is NestJS, Observe is a practical starting point: it is quick to set up and shows application classes and methods without hand-written spans. Add or switch tools when one of these requirements applies:

If you also...	Then
need browser or mobile errors and session replay	add Sentry for the frontend
run several languages and want them in one trace, or need to watch infrastructure	a full-platform APM
must keep telemetry in your own network, or need portable, vendor-neutral instrumentation	OpenTelemetry

The rest of the post is the reasoning, starting with the difference that matters most.

The same slow request, in each tool

POST /orders takes 1.8 seconds. The controller calls OrdersService, which loads the customer, asks PricingService for a quote, and has PaymentsService charge a card. Here's what each tool shows you.

A generic Node.js agent (any platform APM, or OpenTelemetry's auto-instrumentation) sees the process from the outside. The HTTP server, the router under Nest, the database driver, the outbound call.

POST /orders                          1,812 ms
  express.middleware  (x6)                4 ms
  pg.query  SELECT customers             11 ms
  http.request  POST api.stripe.com   1,747 ms

That view is accurate and may be enough for this particular case. (OpenTelemetry's Nest instrumentation adds two more per request: one for the request context and one for the route handler.) It does not identify work inside your application, though. If those 1.7 seconds move from Stripe into a loop inside PricingService, the trace still shows a 1.8-second request without identifying the loop.

Sentry goes further into Nest than the generic agents do. Its SDK adds spans for guards, pipes, interceptors and the route handler. So now you see the pipeline around your code, but still not the services behind the controller, and that's usually where the time is.

Observe shows the application you wrote:

POST /orders                          1,812 ms
  AuthGuard.canActivate                   3 ms
  OrdersController.create             1,806 ms   self 1 ms
    OrdersService.create              1,805 ms   self 6 ms
      CustomersService.findById          12 ms
        SELECT customers                 11 ms
      PricingService.quote               38 ms
      PaymentsService.charge          1,749 ms
        POST api.stripe.com           1,747 ms

No span was added manually for PricingService.quote; every provider method that runs during the request is a span. That attributes self time to your own classes and allows the data to be aggregated into a ranking of classes by time. The other options can provide this depth with additional service-layer instrumentation, which then has to be maintained.

Why generic agents don't do this

Nest creates every provider through its DI container and exposes a hook at exactly that moment: instrument.instanceDecorator, an option of NestFactory.create(). Observe uses it to wrap each controller, service, guard, interceptor and pipe the container creates. (Instances you create inline, like @UsePipes(new MyPipe()), bypass the container and get no span.)

The hook is public, so anyone could build on it. Generic Node agents don't: they patch libraries they know by name, like Express or pg, and have no way of knowing that PricingService exists. The closest thing out there is a community package for Datadog that wraps providers. It's not the vendor's agent, and you maintain it.

This also explains the setup. There's nothing to preload: your own classes are handed over by the container, and the few libraries we do patch (the database drivers and the queue clients) are patched on their prototypes when the module starts, so load order doesn't matter:

// app.module.ts
export const { ObserveModule, ObserveInstrument } = createObserveModule();

@Module({
  imports: [
    ObserveModule.forRoot({
      appKey: process.env.OBSERVE_APP_KEY!,
      appSecret: process.env.OBSERVE_APP_SECRET!,
      serviceId: 'orders-api',
    }),
  ],
})
export class AppModule {}

// main.ts
const app = await NestFactory.create(AppModule, { instrument: ObserveInstrument });

One package, two env variables, one option (NestFactory.createMicroservice() takes the same one). No instrument file that has to be imported first, no agent process, no collector, no exporter.

What else Observe does

Knowing the framework is also why the rest needs no config. HTTP, microservices and GraphQL come in through hooks in Nest's adapters; BullMQ, Bull, @nestjs/schedule and gateways through the Nest integration packages, which we also maintain. So the agent knows what a queue consumer, a @Cron() handler, a @SubscribeMessage() and a GraphQL resolver are.

Database queries and outbound HTTP show up inside the trace, under the method that made the call. Queries go through pg, mysql2 and mongodb, so TypeORM, Drizzle, MikroORM, Mongoose and Prisma's pg driver adapter work untouched. Outbound HTTP is read from Node's diagnostics channels, so fetch, axios and SDKs built on node:http are covered without patching anything. We record statement shapes only, never values. And these spans aren't billed.

Queues, cron, GraphQL, microservices and WebSocket gateways are each recorded as what they are, not as a strange looking HTTP request. A BullMQ or Bull job shares a trace with the request that enqueued it, automatically (producer and worker on 0.3 or later; scheduled jobs and FlowProducer flows start their own trace).

Errors are split into handled and unhandled (a thrown NotFoundException is your API working, not an incident): by status code over HTTP, and by whether it's one of Nest's intrinsic exceptions elsewhere. They're grouped into defects, they come with the failing source line, and you get an email the first time a new unhandled one appears. On every plan.

You can capture the input of failed or slow requests, redacted inside your process, with bodies being opt-in. There's a service map drawn from real traffic. And there's an MCP server, so your coding agent can investigate a failure with the same data you'd use.

Pricing is simple and per event: every request, job, error, log line and span from your own code is one event, while query and outbound HTTP spans are free. Free covers 300,000 events a month with 3 days of retention and a hard cap. Pro is $29 a month for 25 million events and 30 days. Scale is $99 for 200 million and 90 days. Overage on those two is $0.60 and $0.40 per extra million. Error monitoring, tracing and auto-instrumentation are on every plan, and so are trace ids in your ConsoleLogger lines; log forwarding and alert rules start on Pro. I'm not going to quote other vendors' prices here, because they change and because per-host, per-seat and per-gigabyte models don't convert cleanly. But do price your own traffic on each of them before you decide. I'm comfortable with how that comparison comes out.

Where the others are the better choice

Observe does one thing, NestJS backends, and outside of that the alternatives are simply better.

Sentry

What it's best at: errors. Sentry has had over a decade to get error tracking right and it shows. Grouping, release health, suspect commits, source map handling, a mature issue workflow, and integrations with everything: GitHub, Jira, Linear, Slack, PagerDuty. It covers browsers, mobile and backends in one product, with session replay on the frontend. You can self-host it.

For NestJS there's an official @sentry/nestjs SDK. It uses OpenTelemetry under the hood, which means an instrumentation file that has to be imported before anything else, plus SentryModule and a global filter. Out of the box you get spans for incoming and outgoing HTTP, for database calls through the common drivers (pg, mysql2, MongoDB and Mongoose, ioredis, GraphQL, while Prisma needs an extra integration), and for Nest's request pipeline: middleware, guards, pipes, interceptors, filters and route handlers, as long as they have @Injectable() on them. That's further into Nest than any generic agent goes.

Where it's weaker: Sentry's centre of gravity is the error, not the structure of your application. Performance data is there, but "which of my providers holds the time across all traffic" isn't what it was designed around. Your service layer only shows up in a trace where you add spans yourself.

Pick it when errors across a web or mobile frontend and a backend are your main concern, or when you need its integrations and workflow.

Full-platform APMs (Datadog, New Relic, Dynatrace and friends)

What they're best at: breadth. Application traces next to host metrics, containers and Kubernetes, database monitoring, log management, synthetic checks, real-user monitoring, security signals, all correlated, across every language you run. Their auto-instrumentation covers a huge range of drivers and clients. For a big organisation with a platform team this is the right kind of tool, and nothing in this post competes with it.

For NestJS these agents instrument Node.js generically: the HTTP server and the router underneath Nest (Express or Fastify), database and cache drivers, outbound calls, and more and more often queues (Datadog's tracer lists BullMQ as supported). Nest itself gets less attention. It's not among the frameworks Datadog's Node.js tracer lists, and their docs mention it only as a framework with a custom entry point that needs the tracer preloaded. New Relic's agent recognises Nest for naming transactions. You get an accurate trace that's well connected to the infrastructure around it, written in the vocabulary of libraries (express.middleware, pg.query) and not of your application. To see OrdersService.create you add spans yourself, or you reach for a community package. nestjs-ddtrace, for example, can wrap controllers and providers in Datadog spans.

Where they can be a less natural fit is cost and operational weight. There may be an agent or collector to deploy, pricing may combine hosts, ingested volume, and retention, and the product surface is large enough to need an owner. For a small team with three Nest services, that can be more platform than the immediate problem requires.

Pick one when you have more than one language, real infrastructure to watch next to the application, and the budget and people to run it.

OpenTelemetry plus a backend

What it's best at: independence. Instrument once with an open standard, send the data anywhere, change your mind later without touching application code. The collector can run inside your network, so telemetry never has to leave it. Library coverage is the widest of any option and every serious vendor ingests it.

For NestJS the auto-instrumentation bundle covers HTTP, the common drivers and Nest's entry points. Same as with the agents above, your own providers are yours to instrument.

Where it can require more effort is that it is a toolkit rather than a single product. You choose and run the SDK, instrumentations, exporter, collector, and backend, then build the dashboards and alerts and own the upgrades. Each step is manageable, but together they require sustained ownership. I wrote a whole post about this trade-off: Why we didn't just use OpenTelemetry.

Pick it when vendor-neutrality, data residency or a polyglot stack is a requirement and not a preference.

What Observe doesn't do

So nothing surprises you later.

It's NestJS on Node.js only. A Go or Python service in the same request path won't show up in the trace, and services are correlated with a request id header, not W3C traceparent (automatic over HTTP; over microservice transports you carry the id in the payload yourself). There's no frontend SDK and no infrastructure monitoring (it reports the process's own runtime metrics, not your hosts or your database server). It's hosted and it's not an open standard: no self-hosted edition, no OTLP in or out today. Library coverage is narrow on purpose. Prisma on its own query engine, Redis and Kafka client calls don't appear as spans, and cloud SDK calls appear only as the HTTP requests they make (POST s3.amazonaws.com), not as named operations. Your own @MessagePattern() handlers on a Kafka or Redis transport are recorded; the clients underneath aren't. Anything else goes through the manual span API. And alert rules (Pro and up) go to email, Slack, a webhook or the built-in issue tracker; the free plan gets the new-error email only. There's no native PagerDuty or Opsgenie integration yet.

It launched in 2026, so it's younger than everything else on this page. It's also built and maintained by the same people who build the framework, and it runs on NestJS 11.1+ and 12, Node 20.19+, with Express or Fastify. When Nest changes, we're the ones changing it, and we're the ones keeping the agent working.

Side by side

	NestJS Observe	Sentry	Full-platform APM	OpenTelemetry + backend
Time to first useful trace	Minutes	An hour or two	Hours to days, plus an agent	Days
Setup	One package, one module, one option	Preloaded instrument file, module, filter	Agent plus preloaded tracer	SDK, exporter, collector, backend
Spans for your own providers, automatically	Yes	No, manual spans	Not built in (community package for Datadog)	No, manual spans
Self time per class across all traffic, without manual spans	Yes	No	No	No
Spans for Nest's pipeline (guards, pipes, interceptors)	Yes	Yes	No	No
Queue job in the same trace as the request that enqueued it	Automatic (BullMQ, Bull; not flows or scheduled jobs)	Check per queue library	Datadog lists BullMQ, check others	Depends on what you add
Database queries and outbound HTTP in traces	Yes, and not billed	Yes (also Redis, GraphQL)	Yes (widest)	Yes (widest)
Something to operate	Nothing	Nothing	Agent	Collector and backend
Error grouping and workflow	Good	Best in class	Good	Depends on backend
Breadth of library instrumentation	Narrow	Wide	Widest	Widest
Frontend / mobile / session replay	No	Yes	Yes	Partly
Infrastructure monitoring	No	No	Yes	With more components
Languages	NestJS only	Many	Many	Many
Open standard / portable	No	OTel-based tracing	OTLP ingest, proprietary agents	Yes
Self-hostable	No	Yes	No	Yes
On-call integrations	Email, Slack, webhook (alert rules on Pro and up)	Many	Many	Depends on backend

They work well together

Since Observe is narrow, it sits nicely next to the others.

Observe for the NestJS backend and Sentry for the frontend: provider-level depth where your logic lives, browser errors and replay where Observe has nothing to offer. Observe for the application layer and a platform APM for infrastructure: the generic agent's view stops at the router, and that's where Observe's starts. Or Observe this week and OpenTelemetry as the long-term standard. One takes an afternoon and the other takes a quarter, and nothing stops you from doing both.

If two agents hook the same database driver, test the combination in staging before using it in production.

How I'd decide in ten minutes

Is your backend NestJS, and is the current state basically "we have logs"? Install Observe today. It's free to start and takes minutes, and everything below can still happen later.

Is your biggest pain browser or mobile errors? Add Sentry for the frontend.

Is something in the request path not NestJS, and does it have to be in the same trace? Then a platform APM or OpenTelemetry. Observe alone won't cover it.

Does telemetry have to stay in your network, or does the instrumentation have to be portable? OpenTelemetry.

Do you have infrastructure to watch and a team to run the tooling? A platform APM, with Observe next to it if you want to see inside your services.

The worst choice is the one that stays on the backlog. And for a NestJS team, the shortest way off the backlog is the thing the framework's own team built for exactly that.

You can look at real traces, errors and the service map without signing up: the NestJS Observe demo. Spotted something wrong about another tool here? support@nestjs.com and I'll correct it.

NestJS Production Checklist: 17 Checks Before You Deploy

Kamil Mysliwiec — Wed, 30 Sep 2026 08:55:09 +0000

Locally, a Nest app runs as one process, restarts when you save, talks to a database with no other clients, and gets requests straight from your browser. In production it runs as several replicas behind a load balancer, gets stopped on every deploy, shares its database with other processes, and depends on APIs that sometimes don't answer. A lot of defaults that are fine for the first setup are wrong for the second.

Startup and deploys

1. Validate config at boot, and keep secrets out of the image

A missing or malformed environment variable should stop the process before it accepts a request. Otherwise the app boots, passes its health check, takes traffic, and fails the first request that reads the value.

@nestjs/config accepts any Standard Schema (Zod, Valibot, ArkType) as validationSchema:

import { z } from 'zod';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validationSchema: z.object({
        NODE_ENV: z.enum(['development', 'test', 'production']),
        DATABASE_URL: z.url(),
        STRIPE_SECRET_KEY: z.string().min(1),
        PORT: z.coerce.number().default(3000),
      }),
    }),
  ],
})
export class AppModule {}

Read required values with config.getOrThrow('STRIPE_SECRET_KEY') rather than get(). During a rolling deploy, a version that fails on boot never becomes ready and the previous one keeps serving. That's the failure mode you want.

While you're here, check where the values come from. Secrets belong in the platform's secret store (Kubernetes Secrets, AWS Secrets Manager, Vault, your PaaS's config), injected at runtime. Not in a .env file copied into the image, and not as a Docker ARG/ENV: both end up in the image layers, readable by anyone who can pull the image. A .dockerignore with .env* in it is a cheap guard.

And don't log the config object. console.log(config) at startup is a common debugging step that stays in, and it ships every credential to your log pipeline. If you need to see what loaded, log the keys, not the values.

2. Handle SIGTERM, and get the container right

Deploys, scale-downs and node drains all send SIGTERM. Nest doesn't listen for it unless you ask, so by default onModuleDestroy and onApplicationShutdown never run: pools stay open, queue workers are killed mid-job, in-flight requests are dropped.

const app = await NestFactory.create(AppModule);
app.enableShutdownHooks();
await app.listen(process.env.PORT ?? 3000);

With hooks enabled, a signal runs: the HTTP adapter is marked as closing, onModuleDestroy, beforeApplicationShutdown, the HTTP server, gateways and microservices close, then onApplicationShutdown. Most integrations clean up in that last one. @nestjs/bullmq, for example, closes its workers there, and worker.close() waits for the jobs they're running.

Two ways the signal gets lost in containers:

Something between the runtime and Node. CMD npm run start:prod, or the shell form CMD node dist/main.js, puts npm or a shell in front of Node, and neither reliably forwards signals. Use the exec form: CMD ["node", "dist/main.js"].
Node running as PID 1. The kernel doesn't apply default signal behaviour to PID 1. enableShutdownHooks installs its own handler, so the hooks run, but Nest then exits by removing that handler and re-sending the signal to its own process. As PID 1, that second signal is ignored, and the process only exits if the event loop happens to be empty. Run with an init process (docker run --init, or tini as the entrypoint), or use app.enableShutdownHooks(undefined, { useProcessExit: true }) so Nest calls process.exit().

The rest of the image is worth a look while you're in the Dockerfile. Build in one stage and run in another, so compilers, dev dependencies and your source tree don't ship; set NODE_ENV=production; and don't run as root, since the official Node images already include a node user:

FROM node:24-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

FROM node:24-slim
ENV NODE_ENV=production
WORKDIR /app
COPY --from=build /app/package.json ./
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "--enable-source-maps", "dist/main.js"]

(package.json is copied on purpose: the Nest 12 starter is ESM, and Node reads "type": "module" from it.)

Then check memory. If the container has a memory limit and V8's heap limit is higher than what the container can actually give it, the kernel kills the process before V8 gets a chance to complain: exit code 137, no JavaScript error, no log line, just a restart. Depending on the Node version and how the limit is set, the default heap size doesn't necessarily follow the container's limit, so set it explicitly to leave room for everything that isn't heap (buffers, native memory, the stack):

env:
  - name: NODE_OPTIONS
    value: "--max-old-space-size=768" # ~75% of a 1 GiB limit

Now a leak or an oversized payload ends in a JavaScript heap out of memory error with a stack trace in your logs, instead of a silent kill. Alert on restarts either way, and on OOMKilled specifically.

3. Drain before you close

When Kubernetes terminates a pod, two things start at the same time: the pod is removed from the Service's endpoints, and the kubelet stops the container (preStop hook, then SIGTERM). Endpoint removal takes a few seconds to reach every load balancer and kube-proxy. A server that closes immediately on SIGTERM refuses the requests routed to it during that window.

The usual fix is a short delay before shutdown starts:

lifecycle:
  preStop:
    exec:
      command: ["sleep", "5"]

Nest 12 also has return503OnClosing: true on NestFactory.create(). It answers new requests with a 503 and Connection: close while in-flight ones finish. That's useful once traffic has drained, but during the propagation window those 503s reach clients, so use it together with the delay, not instead of it.

Then check the time budget. Kubernetes sends SIGKILL after terminationGracePeriodSeconds (default 30), and the preStop time counts against it. A queue job that runs longer than what's left gets killed, BullMQ marks it stalled, and another worker runs it again from the start. Either raise the grace period or keep jobs short, and make them idempotent regardless, because a crash does the same thing.

4. Scheduled jobs run on every replica

@Cron(), @Interval() and @Timeout() from @nestjs/schedule run in-process. Three replicas means the nightly invoice export runs three times. It's one of the most common production bugs in Nest apps, because it can't happen on a single dev instance.

@nestjs/locks handles this with decorators:

@Cron('0 2 * * *')
@OnOneInstance({ key: 'invoices:export' })
async exportInvoices() {
  // runs on exactly one instance; the others skip the tick
}

@Cron('*/5 * * * *')
@WithoutOverlapping()
async reconcile() {
  // skips a tick while the previous run is still going
}

@OnOneInstance() holds a lease that the owning instance renews every ttl / 3 (30 s TTL by default). If that instance dies, another one takes over once the TTL runs out. @WithoutOverlapping() only holds the lock for the length of a run, which covers the other common bug: a 5-minute job that sometimes takes 7.

The lock store must be shared, and it's yours to provide: you register a LockStore backed by Redis or Postgres (the docs include both). The in-memory store only excludes other callers in the same process, so LocksModule refuses to use it in production unless you set allowInMemoryStorage. Missed ticks aren't replayed, so write jobs that process current state ("export everything not yet exported") rather than "yesterday's rows".

For code that has to be safe if a lock is lost mid-run (a long GC pause, a network partition), each acquisition comes with a signal that aborts on lease loss and a monotonically increasing fencingToken. Pass the signal to your I/O, and use the token to reject writes from a holder whose lock was taken over.

Queues have their own version of this. BullMQ doesn't retry unless you set attempts, a job whose worker dies or blocks the event loop past its lock gets marked stalled and run again, and completed and failed jobs stay in Redis until something removes them. The minimum is to set attempts, backoff and removeOnComplete/removeOnFail explicitly in defaultJobOptions, and make every job safe to run twice.

The edge

5. Make authentication deny-by-default

The usual pattern is @UseGuards(AuthGuard) on each controller. It fails open: the one controller where someone forgets the decorator is public, and nothing tells you. Invert it. Require authentication globally and opt routes out explicitly.

@nestjs/authentication works that way out of the box. AuthenticationModule registers a global guard, so every route requires a signed-in user and anything else gets a 401, and you mark the exceptions:

@Public()
@Controller('auth')
export class AuthController {
  // sign-in, sign-up, password reset
}

It covers sessions, JWT bearer tokens, OpenID Connect, magic links and API keys, and @CurrentUser() gives handlers the resolved user.

If you keep your own guard, get the same property by registering it with APP_GUARD and letting a metadata decorator opt out:

export const IS_PUBLIC = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC, true);

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

  canActivate(context: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (isPublic) return true;
    // verify the token or session here
  }
}

// app.module.ts
providers: [{ provide: APP_GUARD, useClass: AuthGuard }],

Either way, a review now has one thing to check: every @Public() in the diff.

6. Security headers, CORS, rate limits, and the proxy in front

Nest now sets the standard security headers itself, with the same defaults as Helmet 8 (CSP, HSTS, X-Content-Type-Options, X-Frame-Options and the rest):

const app = await NestFactory.create(AppModule);
app.useSecurityHeaders();

It has to be called before app.init()/app.listen(), and only once; otherwise it throws. Individual headers are configurable, e.g. app.useSecurityHeaders({ contentSecurityPolicy: { directives: { ... } } }).

CORS: app.enableCors() with no arguments allows every origin. For an API used by one frontend with cookies, list the origins:

app.enableCors({ origin: ['https://app.example.com'], credentials: true });

Rate-limit at least the expensive or brute-forceable endpoints (login, password reset, anything that sends email or SMS):

ThrottlerModule.forRoot([{ ttl: 60_000, limit: 100 }]),
// ...
providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }],

Counters are per process unless you configure shared storage, so with N replicas the effective limit is N times higher.

Rate limiting also depends on knowing who the client is, and behind a load balancer every request comes from the load balancer's address. Until Express trusts X-Forwarded-*, req.ip is that address, all clients share one limit, and req.protocol is http even for HTTPS clients, which breaks secure cookies and audit logs too:

const app = await NestFactory.create<NestExpressApplication>(AppModule);
app.set('trust proxy', 1); // number of proxies in front of the app

Set the actual hop count. true trusts whatever the client sends in X-Forwarded-For, which lets any client choose its own IP.

Input and output

7. Validate every input

With class-validator classes:

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
  }),
);

whitelist strips properties that aren't declared on the DTO. That's what stops { "email": "...", "role": "admin" } from reaching a repository.save(dto). forbidNonWhitelisted rejects them with a 400 instead, which also surfaces client typos.

With Zod, Valibot or ArkType, use StandardSchemaValidationPipe and attach the schema to the parameter:

app.useGlobalPipes(new StandardSchemaValidationPipe());

export const createUserSchema = z.object({
  email: z.email(),
  password: z.string().min(8),
});
export type CreateUserDto = z.infer<typeof createUserSchema>;

@Post()
create(@Body({ schema: createUserSchema }) dto: CreateUserDto) {
  return this.users.create(dto);
}

Here unknown keys are the schema's business, not the pipe's. z.object() strips them by default; use z.strictObject() if you want them rejected. Either way, the handler receives the schema's output, so coercions and defaults are applied.

One thing to know about useGlobalPipes(): it's applied to the app instance, so an e2e test that builds its own app from AppModule doesn't get it. Either repeat the call in the test setup, or register the pipe as an APP_PIPE provider so the module brings it along.

Validation is also where you bound list endpoints. A limit or take query parameter without a maximum lets one request load every row in the table into memory; so does a list endpoint with no default. Put the cap in the DTO or schema, and give every list query a default:

export const listOrdersQuery = z.object({
  limit: z.coerce.number().int().min(1).max(100).default(20),
  cursor: z.string().optional(),
});

(@Max(100) plus a default value does the same with class-validator.) The same applies to anything that fans out per item: a bulk endpoint that accepts 10,000 ids is a list endpoint too.

The body size limit is already reasonable: Express's JSON parser stops at 100 KB. The mistake is raising it globally for one upload endpoint. app.useBodyParser('json', { limit: '50mb' }) applies to every route, and parsing a 50 MB JSON body blocks the event loop for every other request on that process. Stream large payloads on the route that needs them, or upload them directly to object storage.

8. Control what goes out

Returning ORM entities from controllers leaks every column, including the ones added after the endpoint was written. Map to response DTOs, or use @Exclude() with a global ClassSerializerInterceptor. The interceptor only applies to class instances, so plain objects (raw query results, { ...user, extra }) are serialized as-is.

Don't expose Swagger publicly in production. SwaggerModule.setup() publishes a complete map of the API. Skip it when NODE_ENV === 'production', or put it behind auth.

9. Make writes safe to repeat

Clients retry. A mobile app on a flaky connection, a user who double-clicks, a proxy or SDK that retries on a timeout: any of them can send the same POST /orders/:id/pay twice, and the second one charges the card again. Your handler can't tell a retry from a new request unless the client says so.

The standard contract is an Idempotency-Key header: the client generates a key per logical operation and sends it with every attempt, and the server runs the operation once and replays the stored response for repeats. @nestjs/idempotency implements it:

IdempotencyModule.forRoot({
  // keys are per user, so two clients can't collide or read each other's results
  scope: (req: { user?: User }) => req.user?.id,
}),

@Post(':id/pay')
@Idempotent({ required: true })
pay(@Param('id') id: string, @Body() dto: PayOrderDto, @CurrentUser() user: User) {
  return this.orders.pay(id, user, dto);
}

A repeat with the same key gets the stored response (with Idempotent-Replayed: true) and the handler doesn't run. A duplicate that arrives while the first is still running gets a 409 with Retry-After. The same key with a different body is a 422, which catches client bugs that reuse keys. 5xx responses aren't stored, so a request that failed on your side can be retried and will run again. required: true rejects requests without a key, which is what you want on payment-like endpoints.

The records need a shared store (Postgres or Redis; the docs have both), for the same reason as the lock store in item 4: in memory, a retry that lands on another replica, or arrives after a deploy, runs the handler again. The module refuses to start in production without one. Stored responses are kept for 24 hours by default (ttl), and the whole response body is stored, so keep that in mind for endpoints that return large payloads.

This is different from @Retry({ idempotent: true }) in item 12, which lets the server re-run a handler within one request. @Idempotent() deduplicates the client's retries across requests. If you use both, register IdempotencyModule before ResilienceModule in imports, because import order sets the order of their global interceptors.

Dependencies

10. Run current versions of Node, Nest and your dependencies

Old versions are a production risk even when nothing is visibly broken: security fixes, memory leak fixes and bug fixes only land in supported release lines, and the longer you wait, the bigger and riskier the eventual upgrade.

Node: run an LTS release that's still supported, Active or Maintenance. Odd-numbered majors never become LTS, and an end-of-life line gets no security patches at all: Node 20 reached end-of-life in April 2026, so anything still on it is unpatched. Pin the major in the base image (node:24-slim) and rebuild regularly so patch releases actually reach production, rather than building once and running that image for a year.
Nest: stay on the current major, and keep every @nestjs/* package on matching versions. Mismatched @nestjs/common and @nestjs/core versions cause confusing DI and metadata errors. Several items in this list (useSecurityHeaders(), StandardSchemaValidationPipe, return503OnClosing) only exist in recent releases.
Everything else: commit the lockfile, install with npm ci in CI and in the image, and let Renovate or Dependabot open small update PRs continuously. Twenty small upgrades with passing tests are much cheaper than one big one after two years. Run npm audit --omit=dev in CI to catch known vulnerabilities in what actually ships.

11. Time out every outbound call

A dependency that stops responding is worse than one that errors. Every request waiting on it holds memory, a socket and often a database connection, and under load you run out of those before the dependency recovers. Few clients time out by default:

fetch waits up to 5 minutes for response headers. Pass signal: AbortSignal.timeout(5_000).
For HTTP APIs, use @nestjs/http-client, the Promise-based replacement for the axios-based HttpModule. Configure a timeout per client:

  HttpClientModule.register({
    name: 'payments',
    baseUrl: 'https://api.payments.example.com',
    timeout: '5s',
  }),

The timeout applies per attempt, and retries are on by default for idempotent methods (GET, HEAD, OPTIONS, PUT, DELETE: 3 attempts with exponential backoff, and on timeouts too). So a 5 s timeout can mean 15 s or more before the call fails. Make sure that fits the caller's budget, or tune retry.

Database queries: set a statement timeout. With pg, that's statement_timeout in the pool config, whatever ORM sits on top.

12. Plan for dependencies that are down

Timeouts cap one call. When a dependency is down for minutes, you also want to stop calling it for a while, limit how much of your capacity it can occupy, and serve something reasonable in the meantime. @nestjs/resilience provides that as decorators and presets:

ResilienceModule.forRoot({
  presets: {
    carrier: {
      timeout: '2s',
      retry: { attempts: 2 },
      circuitBreaker: { failureRateThreshold: 50, minimumCalls: 10, openDuration: '30s' },
    },
  },
}),

@Get('quotes')
@Resilience('carrier')
@Fallback('flatRateQuotes', { handleIf: (error) => error instanceof CircuitOpenError })
getQuotes(@Query('orderId') orderId: string, @Signal() signal: AbortSignal) {
  return this.shipping.getQuotes(orderId, signal);
}

When the breaker is open, calls fail immediately with a 503 and Retry-After instead of waiting 2 s each, and the fallback answers. @Bulkhead() caps concurrent calls, so a slow dependency can't tie up every request on the process. Pass the injected signal down to your I/O so a timed-out attempt actually stops. Inside services (jobs, cron, anything that isn't a handler), use ResilienceService.preset('carrier').execute(...). Two details: @Retry() only applies to safe methods unless the handler is also @Idempotent() (item 9) and the retry is marked idempotent: true, and retries multiply across layers. A resilience retry around an @nestjs/http-client call that retries itself makes 3 x 3 = 9 attempts, so decide which layer owns retries.

13. Run migrations as a deploy step

Every ORM has a way to sync the schema directly from your model: TypeORM's synchronize: true, drizzle-kit push, prisma db push. They're convenient in development and unsafe against production data, because they apply whatever diff they compute, and a renamed field can look like a drop plus an add.

In production, apply reviewed migrations (TypeORM migrations, drizzle-kit migrate, prisma migrate deploy) as a separate step before the new version starts: a Kubernetes Job, a release phase, a CI step. Don't run them from app startup (migrationsRun: true and equivalents) when you have several replicas, because they all start at once and race.

Also check that migrations are backward compatible with the version still running. During a rolling deploy, old and new code share the new schema. Dropping or renaming a column the old version still reads breaks it for the length of the rollout, so split those into expand and contract steps across two deploys.

The same rule is what makes rollback possible. The goal is that at any moment you can redeploy the previous image and it works against the current schema, because down-migrations under incident pressure are rarely tested and often lossy. If a deploy can't be rolled back that way, it should be a deliberate, reviewed exception, not something you discover during an incident.

14. Check the connection pool math

Every replica has its own pool. Five replicas with a pool of 20 is 100 connections. That's Postgres's default max_connections, and you haven't counted the migration job, the workers, an admin tool, or the deploy window where old and new pods run at the same time.

Set the pool size explicitly (for pg, the max option of the pool, however your ORM passes it through). Multiply by the maximum replica count during a deploy, and check it fits. When it no longer fits, add a pooler like PgBouncer rather than raising max_connections.

15. Watch for request-scoped chains

Scope.REQUEST propagates up the dependency graph. Anything that injects a request-scoped provider becomes request-scoped, and so does anything that injects that, up to the controllers. A request-scoped logger near the bottom of the graph can mean a dozen objects constructed per request across a module, without any code saying so.

Check for it before launch. If you need per-request data rather than per-request instances, AsyncLocalStorage (or nestjs-cls) provides it without rebuilding the graph. If you need per-tenant instances, durable providers reuse them per tenant instead of creating them per request.

Errors and visibility

16. Errors: statuses, logs, source maps

Keep the default exception handling semantics: real statuses for HttpException, an opaque 500 plus a log entry for everything else. If you customise the response shape, extend BaseExceptionFilter and delegate to it. A filter written from scratch drops Nest's ExceptionsHandler log line, and unhandled errors stop appearing in logs.
Errors outside handlers. An unhandled promise rejection crashes the process (Node's default since v15). That's the correct behaviour. Make sure the error is logged with its stack before exit, and that repeated restarts alert someone.
Source maps. The starter already emits them. Start Node with --enable-source-maps (or NODE_OPTIONS=--enable-source-maps) so stack traces point at .ts files and lines.

17. Logs, health checks, monitoring

Logs: JSON, production log levels, structured params, and a trace id on every line. How to monitor a NestJS app covers each.

Health checks: separate liveness from readiness. Liveness asks whether this process is stuck, and it shouldn't check dependencies: if the database goes down and liveness fails, Kubernetes restarts every pod, which doesn't help and adds a reconnect storm when the database comes back. Readiness asks whether the pod should receive traffic, and that's where the @nestjs/terminus database check goes.

Monitoring: the items above prevent known failure modes. For the rest, you need per-route latency and error rates, traces that show which of your methods and queries took the time, errors grouped into defects with an alert on new ones, and visibility into jobs and scheduled runs.

For Nest specifically, that's what we built NestJS Observe for. It instruments through Nest's DI container, so spans are your own providers, and setup is a module and one option:

// app.module.ts
export const { ObserveModule, ObserveInstrument } = createObserveModule();

@Module({
  imports: [
    ObserveModule.forRoot({
      appKey: process.env.OBSERVE_APP_KEY!,
      appSecret: process.env.OBSERVE_APP_SECRET!,
      serviceId: 'orders-api',
      // nothing is ignored by default; keep probes out of the latency numbers
      http: { ignore: [/^\/health(?:\/|\?|$)/] },
    }),
  ],
})
export class AppModule {}

// main.ts
const app = await NestFactory.create(AppModule, { instrument: ObserveInstrument });

That gives you requests, jobs, cron runs and messages with p95 and error rate, traces with the SQL under each method, unhandled errors grouped with the failing source line and an email on new ones, and trace ids on ConsoleLogger output. The free tier covers 300,000 events a month.

Summary

Config is validated at boot, required values use getOrThrow, secrets come from a secret store, and the config object is never logged.
enableShutdownHooks() is on, Node receives SIGTERM directly, and there's an init process; the image is multi-stage, runs as non-root, and the heap limit fits the container's memory limit.
Pods drain before closing, and the grace period covers the longest job.
Scheduled jobs are guarded with @OnOneInstance()/@WithoutOverlapping() on a shared lock store, and every job is idempotent.
Authentication is global, and every @Public() is deliberate.
useSecurityHeaders() is on, CORS lists its origins, sensitive endpoints are rate-limited, and trust proxy matches the number of proxies.
A global ValidationPipe (with whitelist) or StandardSchemaValidationPipe is registered, list endpoints have a maximum page size, and the body limit is unchanged.
Responses are DTOs or serialized classes; Swagger isn't public.
Endpoints that must not run twice require an Idempotency-Key, backed by a shared store.
Node is on a supported LTS, @nestjs/* packages are current and aligned, and dependency updates arrive continuously.
Every outbound call and query has a timeout, and retry budgets add up.
Unreliable dependencies have a circuit breaker, a bulkhead or a fallback, and retries are owned by one layer.
Migrations run as a separate deploy step and are backward compatible, so the previous image can always be redeployed.
Pool size times peak replica count fits in the database.
No unintended request-scoped chains.
Error handling keeps statuses and logs; stack traces resolve to source.
Logs are structured, liveness doesn't depend on the database, and the service is monitored.

If you'd rather see the monitoring side of this (item 17) in action than read about it, here's a walkthrough of setting up NestJS Observe: NestJS Observe: Zero-Config Observability for NestJS on YouTube.

How to monitor a NestJS app

Kamil Mysliwiec — Mon, 21 Sep 2026 13:07:01 +0000

How to monitor a NestJS app

When something breaks in production, the first question is usually why it happened. Monitoring gives you a much better answer than a collection of isolated logs, so here's a practical way to think about the signals that help.

Many applications start with logs and a health check, while a broader monitoring plan waits for a quieter week. That's a reasonable place to begin. Logs are much more useful when you already know what to look for, though, and during an incident that context is often the first thing you need.

So let's go through what's actually worth having, roughly in the order I'd add it.

Health checks

This is a useful first layer, and Nest has @nestjs/terminus for it:

@Controller("health")
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private db: TypeOrmHealthIndicator,
  ) {}

  @Get()
  @HealthCheck()
  check() {
    return this.health.check([() => this.db.pingCheck("database")]);
  }
}

Point your load balancer at /health and it knows when an instance is dead. Keep in mind that's all it knows. An app can answer /health in 2 ms while every real request takes 9 seconds, and as far as the load balancer is concerned everything is fine.

It is worth excluding this endpoint from the other instrumentation below. A probe every few seconds creates thousands of identical requests a day and can pull latency numbers toward a route that does very little real work.

Logs

The built-in Logger is often enough during development. In production, a few ConsoleLogger options make a real difference:

const levels = (process.env.LOG_LEVELS ?? "fatal,error,warn,log").split(
  ",",
) as LogLevel[];

const logger = new ConsoleLogger({
  json: true,
  flattenParams: true,
  logLevels: levels,
});

const app = await NestFactory.create(AppModule, { logger });

json: true gives your log system one object per line instead of coloured text it has to parse back apart.

Levels are a contract

logLevels decides what gets written at all, but the levels only help if everyone on the team uses them the same way. The split I'd use:

fatal: the process can't continue. Bad config at startup, a lost connection that won't come back.
error: an operation failed and somebody should look at it. If nobody would act on it, it isn't an error.
warn: something went wrong and was handled. A retry, a fallback, a degraded response. One of these is noise; a hundred in a minute is an early warning.
log: business events you'll want during an incident. Order placed, payment captured, job finished.
debug and verbose: off in production. They bury the lines you're looking for, and you pay to ship and store every one of them.

Structured params

Since Nest 12, plain objects passed after the message are treated as data attached to the entry, not printed as extra messages. With flattenParams, their keys land at the top level of the JSON line:

this.logger.warn("Payment declined", { orderId, provider: "stripe", attempt });
// {"level":"warn",...,"message":"Payment declined","context":"PaymentsService","orderId":"ord_91f2","provider":"stripe","attempt":2}

Now your log system can filter on orderId and group by provider instead of you grepping text. A few rules make this pay off:

Constant message, variables in params. "Payment declined" written 400 times is a pattern you can count and alert on. 400 different strings with the order id baked into each one are not.
Objects, never extra strings. this.logger.log('Order shipped', order.id) doesn't do what it looks like. A trailing string is how Nest passes a context, so on a context-less logger the id replaces the context, and on a new Logger(OrdersService.name) it's printed as a second, separate log line. { orderId: order.id } is always safe.
Errors keep their stack. Params go before the stack: this.logger.error('Charge failed', { orderId }, err.stack) produces one line with orderId and a stack field.
Framework fields win. A param called message, level or timestamp is dropped silently rather than overwriting the real one. Name it reason or status.
Ids, not objects. { user } ships the whole entity, five levels deep, including whatever PII is on it. { userId: user.id } is what you'll actually filter on.

Trace ids

What the built-in logger can't give you is a trace id on every line. Without one, finding the dozen entries for a failed request among thousands of lines written that minute is guesswork, and filtering by orderId only helps if every line in the request happened to include it.

A hand-rolled request id (a middleware plus AsyncLocalStorage) gets you part of the way, but it only covers HTTP. Queue jobs, cron runs and microservice handlers never pass through that middleware, and it isn't the id of anything else you can look at: not a trace, not an error report.

ConsoleLogger has no idea which operation it's logging for, so something that does has to add the id. That's one of the things @nestjs/observe does. It hooks into ConsoleLogger, and every line written during a traced operation (a request, a queue job, a cron run, a microservice message) gets the id of that trace:

{
  "level": "warn",
  "pid": 4242,
  "timestamp": 1789992138000,
  "message": "Payment declined",
  "context": "PaymentsService",
  "orderId": "ord_91f2",
  "provider": "stripe",
  "attempt": 2,
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

The id is read when the line is written, so it's the right one even when a hundred requests interleave across awaits. It's the same id as the trace in the dashboard, so even if your logs stay in your own pipeline, you can go from a slow request to its log lines and back. If you log through pino or winston instead, the hook doesn't apply; TracerService.currentTraceId() gives you the id to add yourself, for example from pino's mixin.

Metrics

Requests per second, error rate, latency, memory, event loop delay. Cheap to collect, and they're what you put alerts on.

Two choices matter here. First, average latency can hide one request in twenty taking four seconds, so p95 is usually a more useful view of the slower experience. Second, break the data down by route. A global number changes when your traffic mix changes, even if the code has not become slower.

Metrics tell you that something changed. They never tell you why.

Traces

Traces are often what turns a broad symptom into a short list of likely causes, although they do take more setup than logs and metrics.

A trace is a single request broken into the things that happened during it: the guard, the controller method, the service it called, the three queries that service ran, the call to Stripe. Each one with a start time and a duration. Instead of "it's probably the database" you get a picture, and the picture is usually surprising.

The traditional setup can be substantial: the OpenTelemetry SDK, auto-instrumentation packages, an exporter, a collector, and a backend to store the data. Depending on the existing infrastructure, it can take a few days before the first useful trace is available, which is difficult to prioritize alongside product work.

If you do go shopping for a tracing tool, here's what I'd look for in a Nest app specifically. Spans named after your code (OrdersService.create, not middleware - <anonymous>). Self time and not only total time, because a controller that awaits a slow repository didn't do anything wrong and you don't want it at the top of your list. Database queries and outbound HTTP calls as their own spans, with the statement visible. And traces that survive a queue, so the request that enqueues a job and the job itself are one story.

Error tracking

Logs contain errors, but they do not automatically tell you that this TypeError has happened 3,140 times since the last deploy, that those occurrences represent one bug, or that the bug is new.

That's what error tracking is for: group occurrences into actual defects, remember when each one first showed up and in which release, and tell you when a new one appears. It should also know the difference between errors you threw on purpose (a NotFoundException is your API doing its job) and the ones you didn't see coming. If those two end up in the same bucket, your error rate is permanently at 4% and everybody learns to ignore it.

Queues

If you use BullMQ or Bull, half your app runs somewhere no HTTP dashboard can see. For each queue I want to know how long jobs wait before a worker picks them up, how often they fail and on which attempt, and which request enqueued them. I wrote a separate post about this because it deserves one.

Doing all of this without losing a week

You can assemble everything above from separate tools. Terminus, a log shipper, Prometheus and Grafana, an OpenTelemetry pipeline, an error tracker, something for queues. Lots of teams run exactly that and it works. It's also five or six systems to keep alive.

This is the reason we built NestJS Observe. We're the framework team, so we could do something nobody else can: instrument the app from the inside, using Nest's own hooks, instead of wrapping a generic Node.js agent around it. The whole setup is this:

npm install @nestjs/observe

and with this package installed, the rest is configuration:

// app.module.ts
import { createObserveModule } from "@nestjs/observe";

export const { ObserveModule, ObserveInstrument } = createObserveModule();

@Module({
  imports: [
    ObserveModule.forRoot({
      appKey: process.env.OBSERVE_APP_KEY,
      appSecret: process.env.OBSERVE_APP_SECRET,
      serviceId: "orders-api",
      http: {
        // keep the load balancer probe out of your percentiles
        ignore: [/^\/health(?:\?|$)/],
      },
    }),
  ],
})
export class AppModule {}

// main.ts
const app = await NestFactory.create(AppModule, {
  instrument: ObserveInstrument,
});

And that's it. No spans to write, nothing to preload, no collector to run. From that point you get requests, GraphQL operations, microservice messages, WebSocket messages, queue jobs and cron jobs, per route, with throughput, error rate and p95. Every request has a trace where the spans are your own classes and methods. SQL queries show up under the method that ran them (through pg, mysql2 and mongodb, so TypeORM, Drizzle, MikroORM and Mongoose just work), and so do outbound HTTP calls. We only record the shape of a statement, never the values. Unhandled errors come with the failing source line, get grouped into defects, and you get an email when a new one shows up. Jobs carry their wait time and attempts, and they share a trace with the request that enqueued them. And every line your ConsoleLogger writes during any of that carries its trace id.

It needs @nestjs/core 11.1 or newer and works with both Express and Fastify. The free tier is 300,000 events a month, which is plenty to find out if it's useful to you. Trace ids in your logs are on every plan. Log forwarding (the lines themselves shipped to Observe and placed on the trace's timeline, with redaction on by default) and alert rules are on the paid plans.

Two caveats. Keep your Terminus health check, because your orchestrator still needs an endpoint to hit. And if your company runs five languages and has standardised on OpenTelemetry, stick with that. A shared standard across your whole stack is worth more than a shortcut for one framework.

If I were starting from zero today

Health check first, excluded from everything else. Then JSON logs with production log levels and structured params. Then tracing and error tracking together, since they come from the same instrumentation and an error without its trace is half a story, and the same instrumentation puts a trace id on every log line. Alerts on error rate and p95 once you have a week of data to set thresholds against. Queue monitoring the day you add a queue.

The goal is not a collection of attractive dashboards. It is a shorter path from a production symptom to the line of code or dependency that needs attention.

You can click around a live project without signing up here: the demo dashboard.

Announcing NestJS Monorepos and new CLI commands

Kamil Mysliwiec — Tue, 01 Oct 2019 12:52:25 +0000

Originally published on the Trilon Blog on Sep 31, 2019.

In this blog post, we'll be looking at a new API of the latest Nest CLI, which supports an alternate structure for managing multiple projects and libraries in a one single repo called monorepo. In addition, I'll give you some insights about the new CLI commands that have just been introduced, respectively nest build and nest start.

If you're not familiar with NestJS, it is a TypeScript Node.js framework that helps you build enterprise-grade efficient and scalable Node.js applications.

History

Before we dive further, let's take a step back to see how everything was handled in the past.

Until now, we used TypeScript tsc compiler by default. To provide a good developer experience in the development environment (e.g. reload the application on file change), we utilized nodemon, ts-node and tsc-watch.
This was perfect for most projects, but we found that some members of the community moved toward webpack in combination with ts-loader. That means, that eventually several packages were needed in order to handle basic features which led to various side-effects and inconsistencies.

Similarly, some companies needed to follow a monorepo approach, instead of having a separate repository for every single application (or library).
Consequently, even more libraries, tools and different packages become required.
In order to solve this problem, we made a decision to address all these issues directly in the official CLI.

Builders 🏗

With nest build, you can use the same command to compile your application or library in either development or production environment.
Would you like to watch for changes and recompile on each source file modification? Use nest build --watch. Would you like to switch to webpack? Use nest build --webpack.

nest build --watch --webpack example

But the builder itself is not just a wrapper around the compiler (webpack or tsc).
It also has plugin system that allows you to leverage the build process itself for pre or post compilation (e.g. to automatically provide additional metadata for @nestjs/swagger to reduce the boilerplate).
In fact, one plugin is already built-in into the compiler. This plugin will automatically resolve your path aliases (e.g. @trilon/core imports) so you will no longer have to use helper packages like tsconfig-paths.

HINT: Learn more about the available builder options here.

Start 🚀

In the past you may have been confused by all of the different package.json scripts in a starter application (ts-node, tsc-watch and nodemon).
Thanks to nest start (and nest start --watch), all listed packages become useless.

nest start --watch example

In the past, you may have faced an issue after adding a single TS file in the root directory of your project - and npm run start:* stopped working. But rest assured - that will no longer be the case. Nest CLI will automatically detect whether your output files are located within dist or dist/src directory and execute appropriate entry file based on that assumption.

HINT: Learn more about the available nest start options here.

Monorepos 🐱

Over the last few years, monorepos became quite popular in the developer community. And even though there are downsides of using monorepos, the benefits they bring provide substantial value.
Monorepos make it easier to compose modular components and libraries, track cross-project changes, promote code re-use, and make integration testing simpler.

Monorepo that consist of 2 applications (payments and alerts) and 1 shared library

Applications and libraries

In order to meet the demands of the community, we've added nest g app and nest g lib commands that allow you to convert the existing structure to a monorepo mode structure.
For example:

$ nest g app alert-service

will scaffold the sub-application alongside your existing application within the same workspace. These two applications will share the same node_modules folder (single-version policy) and configuration files (e.g. tsconfig.json and nest-cli.json).
However, these applications can be executed, developed and deployed separately.

nest g app example

Similarly, to generate a library (a general-purpose feature that can be used within multiple projects), you can use the following command:

$ nest g lib users

Note that a library created inside a monorepo is not suitable for publishing to the NPM registry. If you want to create a package that you want to publish / share across different repos, you should rather use nest new.

Both these commands will automatically update the nest-cli.json which holds the metadata needed to build and organize workspace projects. Typically though, you won't have to edit its content manually (unless you want to change the default file names etc.). You can read more about the monorepo mode here.

Building projects

To build a single project, you can simply call $ nest build NAME command where NAME is the name of the application / library you passed to the $ nest g command.

NOTE: In the monorepo mode, CLI will use webpack instead of tsc by default. The reason for this change is that webpack can produce a single file bundling all project components together (resolves cross-references out-of-the-box).

Running projects

Likewise, in order to run particular application, you can call $ nest start NAME command where NAME is the name of the application / library you passed to the $ nest g command.

However, keep in mind that libraries cannot run on their own because they don't have main.ts file.

Generate building blocks

If you are familiar with Nest CLI already, you know that $ nest g allows you to quickly scaffold essential building blocks of your application, such as controllers and providers.
However, what happens if you switch from single project mode to a monorepo? Nest CLI is now setup to show an interactive list of all applications / library in a workspace so you can select exactly where you want something generated!

nest g service example

Backward compatibility

Using nest start and nest build is not required. All existing applications will work as expected - there are no breaking changes! New features were implemented to make developers life easier, but you can still use the same techniques as before to compile and serve your application (using either typescript compiler or webpack directly is totally fine).

In Conclusion

With the latest CLI we've introduced many new great features for your applications.

New build & start commands
Monorepo support
Generate upgrades
- nest g app NAME
- nest g lib NAME
- Interactive support letting you choose exactly where to generate

We hope you're as excited about these new features as we are, and we look forward to hearing your feedback and how we can improve the NestJS ecoystem even more!

Become a Backer or Sponsor to Nest by donating to our open collective. ❤