CodeXray Node Agent

The CodeXray Node Agent runs on every host (or Kubernetes node) you want to monitor. It uses eBPF to capture container activity, network traffic, and application behaviour directly from the Linux kernel — so you get service maps, RED metrics, log patterns, and traces without instrumenting your applications.

Zero code changes

eBPF lets the agent observe TCP connections, HTTP/gRPC/Redis/Postgres/MySQL/Mongo traffic, and container lifecycle events from outside your process — no SDKs, no restarts, no code modifications required to get rich telemetry on day one.

What It Collects

Capability	What you get
TCP connection tracing	A real-time service map built from actual `connect()` / `listen()` events — no distributed tracing required. Includes connection errors and network RTT between containers, nodes, and availability zones.
L7 (application) tracing	Automatically decoded HTTP, gRPC, PostgreSQL, MySQL, MongoDB, Redis, Memcached, RabbitMQ, and Kafka traffic — with latency and error signals per call.
Log pattern extraction	Discovers container logs, clusters them into recurring patterns on the node, and ships only the patterns + counts — drastically reducing log ingest cost. Supports `/var/log`, journald, Docker JSON file driver, and containerd CRI.
Delay accounting	Per-container CPU-delay and disk-wait metrics pulled via Netlink — tells you when a container is starved for CPU or blocked on I/O.
OOM kill events	Surfaces out-of-memory terminations as discrete events tied to the affected container.
Container profiling	Always-on CPU/memory profiles for containerised workloads.
Cloud metadata	Detects AWS, GCP, Azure, and Hetzner automatically and enriches telemetry with instance type, region, availability zone, and lifecycle (on-demand/spot).
GPU metrics (optional)	Dedicated build with NVIDIA GPU collection — enable via the GPU-variant manifest.

All of this is sent to the CodeXray backend as metrics, traces, logs, and profiles — no separate exporters needed.

Requirements

Host requirements

Linux kernel 4.16 or newer — eBPF features used by the agent require this minimum.
Architecture: amd64 or arm64.
Privileges: the agent needs elevated capabilities to run eBPF programs (CAP_BPF, CAP_SYS_ADMIN, CAP_NET_ADMIN, etc.). On Kubernetes this is handled by the provided DaemonSet manifest.

Network requirements

Outbound HTTPS (or HTTP) to the CodeXray collector endpoint.
No inbound connectivity is required — the agent pushes data out; nothing needs to reach the agent.

Credentials

A project API key from the CodeXray UI (Project Settings → API Keys).

Installation

The Node Agent can be deployed four ways. Pick the one that matches your environment.

Kubernetes — Helm chart (recommended)

The fastest path for any Kubernetes cluster. The chart is published as an OCI artifact on GHCR and rolls out the namespace, ServiceAccount, RBAC, and DaemonSet in a single command — with every knob exposed as a Helm value so you can keep your install reproducible and diff-able in Git.

Step 1 — Authenticate to GHCR

The chart packages are private, so Helm needs a GitHub token with read:packages scope before it can pull the chart.

echo "$GHCR_TOKEN" | helm registry login ghcr.io \
  -u <github-username> --password-stdin

You only need to do this once per machine (or once per CI runner).

Step 2 — Install the chart

helm upgrade --install node-agent oci://ghcr.io/codifinary/helm/node-agent \
  --version 0.1.0 \
  -n codexray --create-namespace \
  --set-string nodeAgent.collector_endpoint='https://your-codexray.example.com' \
  --set-string nodeAgent.apiKey='your-project-api-key'

The two values you almost always set:

Helm value	Description
`nodeAgent.collector_endpoint`	Base URL of your CodeXray collector
`nodeAgent.apiKey`	Project API key from the CodeXray UI

Common overrides:

Helm value	Default	When to change
`nodeAgent.image.tag`	`v1.2.4`	Pin a specific agent version
`nodeAgent.args`	sensible defaults	Tune trace sampling, container denylist, WAL directory, etc.
`nodeAgent.resources`	`100m`/`2Gi` requests, `500m`/`5Gi` limits	Right-size for your node footprint
`nodeAgent.tolerations` / `nodeSelector`	tolerate everything	Restrict which nodes the DaemonSet runs on
`serviceAccount.imagePullSecrets`	`ghcr-secret`	Swap if you mirror the image to a private registry

Full values reference: see the chart README on GitHub.

Deploying both Node + Cluster Agents

If you're running on Kubernetes you almost certainly want the Cluster Agent too. The same chart repo ships an umbrella chart that installs both in one shot — see the Cluster Agent's Helm section for the umbrella command.

Kubernetes — Manifest

If you'd rather skip Helm, a single manifest creates the same namespace, ServiceAccount, RBAC, and DaemonSet.

kubectl apply -f https://raw.githubusercontent.com/codifinary/codexray-node-agent/main/manifests/codexray-node-agent.yaml

Before applying, edit the manifest to set:

COLLECTOR_ENDPOINT — your CodeXray collector URL
API_KEY — your project API key

For clusters with NVIDIA GPUs, use the GPU-enabled variant instead:

kubectl apply -f https://raw.githubusercontent.com/codifinary/codexray-node-agent/main/manifests/codexray-node-agent-gpu.yaml

Systemd (bare-metal / VM)

For Linux hosts that aren't part of a Kubernetes cluster, the installer drops a systemd unit onto the machine:

curl -fsSL https://raw.githubusercontent.com/codifinary/codexray-node-agent/main/install.sh | sudo sh -

After install, configure the agent by editing the environment file the installer creates:

sudo vi /etc/systemd/system/codexray-node-agent.service.env

Set at minimum:

COLLECTOR_ENDPOINT=https://your-codexray.example.com
API_KEY=your-project-api-key

Then start the service:

sudo systemctl enable --now codexray-node-agent

To uninstall: sudo /usr/bin/codexray-node-agent-uninstall.sh.

Docker

For quick trials or Docker-only hosts:

docker run -d \
  --name codexray-node-agent \
  --privileged \
  --pid host \
  --network host \
  -v /sys/fs/cgroup:/sys/fs/cgroup \
  -v /proc:/proc \
  -e COLLECTOR_ENDPOINT=https://your-codexray.example.com \
  -e API_KEY=your-project-api-key \
  ghcr.io/codifinary/codexray-node-agent:latest

The agent needs host networking, host PID namespace, and access to /proc and /sys/fs/cgroup to see every container on the host.

Configuration

All configuration is via environment variables (or equivalent CLI flags). The two you almost always need to set:

Variable	Description
`COLLECTOR_ENDPOINT`	Base URL of your CodeXray collector. The agent derives `/v1/metrics`, `/v1/traces`, `/v1/logs`, and `/v1/profiles` from this.
`API_KEY`	Project API key from the CodeXray UI.

Optional toggles

Every feature is on by default. Disable any that don't fit your environment:

Variable	Default	Effect when set
`DISABLE_L7_TRACING`	`false`	Skip application-protocol tracing (HTTP, gRPC, DB protocols) — useful if you only want network + resource telemetry.
`DISABLE_LOG_PARSING`	`false`	Skip log discovery and pattern extraction.
`DISABLE_PINGER`	`false`	Stop measuring RTT to upstream services.
`CONTAINER_ALLOWLIST` / `CONTAINER_DENYLIST`	—	Regex patterns to scope which containers the agent watches.
`EXCLUDE_HTTP_REQUESTS_BY_PATH`	—	Skip HTTP metrics/traces for noisy paths like health checks (`/healthz`, `/metrics`).
`TRACES_SAMPLING`	`1.0`	Trace sampling rate (`0.0` disables traces, `0.1` = 10%).
`SCRAPE_INTERVAL`	`15s`	How often the agent gathers metrics.
`MAX_SPOOL_SIZE`	`500MB`	On-disk buffer size for telemetry that couldn't be sent (e.g. collector unreachable).

Cloud metadata overrides

If the agent can't auto-detect your cloud provider — or you run on a private cloud — you can set the labels manually:

PROVIDER=my-dc
REGION=ap-south-1
AVAILABILITY_ZONE=ap-south-1a
INSTANCE_TYPE=m5.large
INSTANCE_LIFE_CYCLE=on-demand

Reliability Details

On-disk spool: if the collector is unreachable, the agent buffers telemetry on disk (default 500 MB) and replays when the connection recovers. No data loss during short collector outages.
Rate limiting: log ingestion is rate-limited (default 10 events/sec with a burst of 100) to prevent a noisy container from overwhelming the pipeline. Tune with LOG_PER_SECOND and LOG_BURST.
No scraping from outside: by default the agent only pushes outbound. If you need Prometheus-style scraping for diagnostics, the agent also exposes metrics on :80 — but pushing to the collector is the primary path.

Verifying It's Working

After install, check a few places:

On the host: systemctl status codexray-node-agent (systemd) or kubectl -n codexray-agents get pods (Kubernetes). The agent should be active / Running on every node.
In the UI: open the Nodes view — your node should appear within a minute or two with live CPU, memory, network, and container counts.
Service map: the Topology view starts populating as soon as the agent captures its first TCP events — typically under two minutes.

Troubleshooting "no data"

If the agent is running but you see no telemetry, the two most common causes are: (a) the COLLECTOR_ENDPOINT isn't reachable from the host (check egress firewalls), or (b) the API_KEY is for a different project than the one you're viewing. Check the agent logs — they're explicit about auth and connectivity failures.

Next Steps

Node Agent Metrics — full catalogue of the container, network, and runtime metrics the Node Agent emits
CodeXray Cluster Agent — pair the Node Agent with the Cluster Agent on Kubernetes for full control-plane visibility
Application Categories — organise the services the Node Agent discovers
Architecture — how agent telemetry flows through the CodeXray platform

What It Collects​

Requirements​

Host requirements​

Network requirements​

Credentials​

Installation​

Kubernetes — Helm chart (recommended)​

Step 1 — Authenticate to GHCR​

Step 2 — Install the chart​

Kubernetes — Manifest​

Systemd (bare-metal / VM)​

Docker​

Configuration​

Optional toggles​

Cloud metadata overrides​

Reliability Details​

Verifying It's Working​

Next Steps​