Node.js
The agent traces your Node.js services with the OpenTelemetry Node.js instrumentation, loaded at startup with no code change. How it attaches depends on where the service runs, so each environment is covered below. For the shared opt-in flow, restart consent, and automatic rollback, see the Application APM overview.
The instrumentation ships inside the KloudMate agent package and upgrades with it. When you instrument a Node.js service, the agent stops eBPF monitoring from tracing that service’s own requests, so you get the richer application spans without duplicates, on one connected trace.
On Linux
Section titled “On Linux”systemd services
Section titled “systemd services”When you turn on SDK tracing for a systemd service, the agent writes a startup config that loads the instrumentation through NODE_OPTIONS, then restarts the service after you confirm. It sets a fixed service.name, the sampling rate, and where to send traces up front. Turning tracing off removes the config and restarts the service. Running the same action twice changes nothing.
PM2 apps
Section titled “PM2 apps”For a Node.js app under PM2, the agent restarts it with tracing switched on (pm2 restart <app> --update-env). Each app keeps its PM2 process name as its service.name, so apps under the same PM2 manager stay separate. The agent covers PM2 for every user on the host, not just root. If an app doesn’t come back up after the change, the agent undoes it and restarts the app.
Standalone processes
Section titled “Standalone processes”The agent can instrument a Node.js process only when it runs under systemd or PM2. A process started on its own can’t be instrumented automatically. Run it under systemd or PM2 first; the Application Performance Monitoring card flags these and tells you so.
On Kubernetes
Section titled “On Kubernetes”Choose SDK for the workload and the agent adds the OpenTelemetry Operator annotation instrumentation.opentelemetry.io/inject-nodejs. The Operator injects the instrumentation, and that workload’s pods roll to pick it up.
If a workload isn’t detected automatically, add the annotation yourself, then restart the deployment:
The Operator and its Cert Manager prerequisite are installed with the agent. See Kubernetes setup and the Kubernetes installation guide.
On Amazon ECS
Section titled “On Amazon ECS”On Amazon ECS, the agent injects the Node.js instrumentation into the services you name, on both the EC2 and Fargate launch types. It rewrites the task definition and sends traces to the collector: the per-instance daemon on EC2, or a sidecar on Fargate. List your Node.js services in KM_ECS_SERVICES when you install. See the Amazon ECS install guide.
On Docker
Section titled “On Docker”When the agent monitors Docker containers, whether in Docker mode or as a Linux service on a Docker host, each Node.js container offers Off, eBPF, and SDK in the Application Performance Monitoring card. eBPF needs no code change and no restart.
SDK adds the OpenTelemetry Node.js instrumentation by recreating the container with the same settings, which restarts it for a few seconds. If the new container doesn’t come up healthy, the agent starts the original again. It loads for both CommonJS and ES-module apps and needs Node.js 18.19 or later. If the app already sets NODE_OPTIONS, the agent adds its loader to the existing value. Containers managed by Docker Compose or Swarm aren’t recreated: their row shows the settings to add at the next deploy. See Instrument Java, Node.js, Python, and .NET containers.
On Windows
Section titled “On Windows”The agent injects the instrumentation through the per-service registry environment at HKLM\SYSTEM\CurrentControlSet\Services\<service>\Environment, the Windows equivalent of a systemd startup config. It sets NODE_OPTIONS, then restarts the service. For how Windows discovers services and traces IIS, see Windows platform notes.
Limitations
Section titled “Limitations”- Standalone Node.js needs systemd or PM2. Without one of them, there’s no automatic way to instrument the app.