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 Discovered Services list 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 runs in Docker mode, eBPF traces your Node.js containers per service through the Off / eBPF toggle in Discovered Services, with no code change and no restart.
The agent can’t inject the in-process SDK into a running container, so SDK mode isn’t offered for containers. For full SDK depth, add OpenTelemetry to your image yourself and point it at the KloudMate agent’s OTLP endpoint. See Docker platform notes for the endpoint addresses. On systemd, Kubernetes, or Amazon ECS, the agent injects the instrumentation for you instead.
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.