Node.js Integration
Auto-instrument your Node.js services with one package install. Event loop lag, V8 heap metrics, async traces, and framework instrumentation — all with zero configuration.
How It Works
Install the SDK
Run npm install @tigerops/node. The SDK is a zero-config auto-instrumentation package that wraps the OpenTelemetry Node.js SDK with TigerOps-specific defaults and a direct export path.
Initialize Before App Code
Require @tigerops/node/register at the very top of your entry point (before any other imports). It patches Node.js core modules and popular frameworks via OpenTelemetry auto-instrumentation.
Set Your API Key
Export TIGEROPS_API_KEY as an environment variable. The SDK auto-configures the OTLP exporter endpoint to TigerOps. No other configuration is required for basic tracing.
Traces, Metrics & Logs Flow In
Within seconds of startup, TigerOps receives HTTP traces, database query spans, event loop lag, heap metrics, and structured logs from your Node.js application.
What You Get Out of the Box
Event Loop Lag Monitoring
Track event loop delay using Node.js perf_hooks with P50, P95, and P99 percentiles. TigerOps alerts when lag exceeds your SLO and correlates spikes with specific request traces.
V8 Heap Metrics
Heap used, heap total, external memory, and GC pause duration from the V8 GC API. TigerOps detects memory leak patterns and alerts before heap exhaustion causes OOM crashes.
Async Trace Propagation
Full async context propagation across Promises, async/await, and callbacks. Traces correctly link parent spans to child operations even across async boundaries.
Auto-Instrumented Frameworks
Zero-config instrumentation for Express, Fastify, Koa, NestJS, Hapi, and more. HTTP handler spans, middleware timing, and route-level latency are captured automatically.
Database Query Spans
Automatic instrumentation for pg, mysql2, mongodb, ioredis, and Prisma. Every database query becomes a child span with the normalized query text and row count.
Worker Threads & Cluster
TigerOps propagates trace context across worker_threads message channels and child_process forks, giving you complete visibility into multi-process Node.js architectures.
Install & Initialize
One package install. One import. Full Node.js observability.
# Install the TigerOps Node.js SDK
npm install @tigerops/node
# Set your API key
export TIGEROPS_API_KEY="your-api-key"
export TIGEROPS_SERVICE_NAME="my-api"
export TIGEROPS_ENVIRONMENT="production"
# For CJS: require the register module FIRST in your entry point
# server.js (CommonJS)
require('@tigerops/node/register')
const express = require('express')
const { createClient } = require('redis')
const app = express()
// All routes are automatically traced
app.get('/orders/:id', async (req, res) => {
// This span is automatically created
const order = await db.query('SELECT * FROM orders WHERE id = $1', [req.params.id])
res.json(order)
})
// For ESM: use the --import flag
// package.json
{
"scripts": {
"start": "node --import @tigerops/node/register src/server.mjs"
}
}
// Add custom spans for business logic
import { trace } from '@tigerops/node'
const tracer = trace.getTracer('order-service')
async function processPayment(orderId: string) {
return tracer.startActiveSpan('process-payment', async (span) => {
span.setAttribute('order.id', orderId)
try {
const result = await paymentGateway.charge(orderId)
span.setAttribute('payment.status', result.status)
return result
} catch (err) {
span.recordException(err)
span.setStatus({ code: SpanStatusCode.ERROR })
throw err
} finally {
span.end()
}
})
}Common Questions
Does @tigerops/node add significant overhead to my application?
The overhead is typically under 2% CPU and under 20MB memory for most applications. Event loop lag monitoring uses setImmediate scheduling which adds negligible latency. You can configure sampling rates to reduce overhead for very high-traffic services.
Does TigerOps support ESM (ECMAScript Modules) in Node.js?
Yes. Use node --import @tigerops/node/register your-app.mjs for ESM applications (Node.js 18.19+). For CommonJS applications, use require('@tigerops/node/register') at the top of your entry point. Both modes support the full feature set.
Can I use TigerOps with existing OpenTelemetry instrumentation?
@tigerops/node is built on the OpenTelemetry JS SDK. If you already have OTel instrumentation, you can point your existing OTLP exporter at TigerOps' OTLP endpoint instead of installing @tigerops/node — all data formats are compatible.
Does the SDK work with serverless Node.js environments like Lambda and Vercel?
Yes. @tigerops/node includes a lightweight serverless mode that flushes telemetry synchronously before the function handler returns. Configure it with TIGEROPS_FLUSH_ON_EXIT=true for cold-start-aware trace collection.
How do I add custom spans and attributes to my traces?
Use the @tigerops/node API: import { trace, context } from '@tigerops/node'. The trace.getTracer() and tracer.startActiveSpan() APIs are fully OpenTelemetry-compatible. Custom attributes, events, and span status are all supported.
Full Node.js Observability in One npm Install
Event loop lag, heap metrics, async traces, and framework instrumentation — no code changes required.