Nest.js
| Traces | Metrics | App Logs | Custom Logs | Profiling |
|---|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ | ✅ |
This guide provides instructions to set up Application Performance Monitoring (APM) in a Nest.js application. You can also find these instructions on the installation page in your Middleware account.
Prerequisites
- Node.js 18.17.1+: Verify with
node --version - Python Version 3.8+ Verify with
python3 --version
Introduction
@middleware.io/nestjs-apm is the official Middleware APM client for NestJS applications that automatically instruments your application with OpenTelemetry, sending runtime metrics, traces/spans, and console logs to Middleware.io.
Installation
1 Install Nest.js APM Package
Shell
npm install @middleware.io/nestjs-apm
2 Import the MiddlewareApmModule in your app.module.ts
app.module.ts
import { MiddlewareApmModule } from "@middleware.io/nestjs-apm";
@Module({
imports: [
MiddlewareApmModule.forRoot({
projectName: "Your application name",
serviceName: "Your service name",
}),
// ... other modules
], 3 Add the interceptor to your main.ts:
app.module.ts
import { MiddlewareApmInterceptor } from "@middleware.io/nestjs-apm";
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.useGlobalInterceptors(new MiddlewareApmInterceptor(app.get(Reflector)));
await app.listen(3000);
}
bootstrap();Features
- Automatic instrumentation of NestJS controllers and services
- Console log capture (info, warn, error)
- Distributed tracing
- Performance metrics
- Error tracking
- Custom span attributes
- Advanced instrumentation decorators
- OpenTelemetry log integration
- Exception tracking with OTEL events
Basic Usage
Ignoring Routes
You can use the @IgnoreApmTrace() decorator to exclude specific routes from tracing:
typescript
import { IgnoreApmTrace } from "@middleware.io/nestjs-apm";
@Controller("users")
export class UsersController {
@IgnoreApmTrace()
@Get("health")
healthCheck() {
return "OK";
}
}Advanced Instrumentation
Custom Attributes
Add custom attributes to spans:
typescript
import { WithAttributes } from "@middleware.io/nestjs-apm";
@Controller("orders")
export class OrdersController {
@WithAttributes({ "business.type": "order", "business.tier": "premium" })
@Post()
createOrder() {
// Your code here
}
}Custom Spans
Create custom spans with specific names and attributes:
typescript
import { CreateSpan } from "@middleware.io/nestjs-apm";
@Injectable()
export class UserService {
@CreateSpan("user.registration", { "user.type": "new" })
async registerUser(userData: any) {
// Your code here
}
}Parameter Recording
Automatically record method parameters as span attributes:
typescript
import { RecordParams } from "@middleware.io/nestjs-apm";
@Controller("users")
export class UsersController {
@RecordParams(["userId", "action"])
@Post(":userId/action")
performAction(userId: string, action: string) {
// Parameters will be recorded as span attributes
}
}Logging Integration
The module automatically records all NestJS logger output to OpenTelemetry. Just use the standard NestJS logger:
typescript
import { Logger, Injectable } from "@nestjs/common";
@Injectable()
export class UserService {
private readonly logger = new Logger(UserService.name);
async createUser(userData: any) {
try {
this.logger.log("Creating new user", { userId: userData.id });
// ... user creation logicYou can combine multiple decorators for comprehensive instrumentation:
typescript
@Controller("payments")
export class PaymentsController {
@CreateSpan("payment.process")
@WithAttributes({ "payment.type": "credit-card" })
@RecordParams(["amount", "currency"])
async processPayment(amount: number, currency: string) {
// Your code here
}
}