NestJS Plugin

@outray/nest offers request telemetry for Nest's Express adapter and an optional development tunnel. Register request instrumentation before the app initializes; start the tunnel after the server is listening.

Install

npm install @outray/nest

The package declares NestJS 8–11 compatibility. Its observability dependency requires Node.js 20 or later.

Register telemetry

// main.ts
import { NestFactory } from "@nestjs/core";
import { registerOutrayObservability } from "@outray/nest";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const telemetry = registerOutrayObservability(app, {
    apiKey: process.env.OBSERVABILITY_TOKEN,
    serviceName: "orders-api",
    environment: process.env.NODE_ENV,
    captureConsole: true,
    capturePayloads: {
      maxBodyBytes: 16 * 1024,
      redactedFields: ["accountPin"],
    },
  });

  if (telemetry) telemetry.info("request instrumentation registered");
  await app.listen(3000);
}

void bootstrap();

Provide a token with observability:write. This setup collects route-aware request spans and HTTP request count, duration, and active-request metrics without opening a tunnel.

Register before app.init() or app.listen(). Late registration and non-Express adapters are skipped with a warning; registerOutrayObservability returns false when request middleware could not be registered.

For automatic instrumentation of imported databases, HTTP clients, and loggers, start the Node.js SDK in a bootstrap before importing your application. Request middleware itself does not require a preloader.

Add a development tunnel

After the server has started:

import { outray } from "@outray/nest";

await app.listen(3000);
await outray(app, {
  apiKey: process.env.TUNNEL_TOKEN,
  subdomain: "my-api",
});

The tunnel defaults to enabled whenever NODE_ENV !== "production". Use enabled: false to turn it off explicitly. Unlike the Vite, Next.js, and Express plugins, the Nest plugin does not read OUTRAY_ENABLED.

The plugin detects the listening port, or you can pass port. Use a token with tunnel:connect; a saved CLI login is not used.

Options

Callbacks include onTunnelReady(url), onError(error), onClose(), onReconnecting(), and onLocalReady(info).

outray(app, { observability: ... }) can register telemetry before initialization, but it does not defer registration until after listening. For clarity, use the separate registration function before initialization and the tunnel function after listening.

Logs, spans, and capture

Successful registration returns structured debug, info, warn, and error methods plus forceFlush() and shutdown(). captureConsole: true also forwards console calls while preserving their local output.

Use withOutraySpan from @outray/nest for an operation that needs an application child span.

Payload capture is off unless explicitly configured. It requires the Express adapter and a recording span; request bodies must be exposed by Nest's parser. JSON and URL-encoded payloads are bounded and common sensitive fields and headers are redacted.

If another OpenTelemetry provider is already configured, registerOutrayPayloadCapture(app, options) installs capture independently, before app initialization. It does not create a telemetry exporter.

Add application-specific redaction rules and see request and trace inspection before using capture on real traffic. Flush telemetry through your application's existing shutdown path.