Coroot-node-agent

Coroot-node-agent is a Prometheus- and OpenTelemetry-compatible agent that gathers comprehensive telemetry data about all containers running on a node and the node itself.

It collects and exports the following telemetry:

• Metrics: Exported in Prometheus format or sent using the Prometheus Remote Write protocol.
• Traces: eBPF-based network and application traces sent via OTLP/HTTP (OpenTelemetry protocol).
• Logs: Discovers container logs and sends them via OTLP/HTTP.
• Profiles: Uses the Pyroscope eBPF profiler to collect CPU profiles and sends them via a custom HTTP-based protocol.

Node Agent Configuration

You can configure coroot-node-agent using command-line flags or environment variables.

Flag	Env Variable	Default	Description
--listen	LISTEN	0.0.0.0:80	HTTP listen address
--cgroupfs-root	CGROUPFS_ROOT	/sys/fs/cgroup	Path to the host's cgroup filesystem root
--disable-log-parsing	DISABLE_LOG_PARSING	false	Disable container log parsing
--disable-json-log-parsing	DISABLE_JSON_LOG_PARSING	false	Disable extracting the message, severity, and attributes from JSON-formatted logs
--disable-pinger	DISABLE_PINGER	false	Disable ICMP ping to upstreams
--disable-l7-tracing	DISABLE_L7_TRACING	false	Disable application-layer (L7) tracing
--disable-gpu-monitoring	DISABLE_GPU_MONITORING	false	Disable GPU monitoring (NVML)
--enable-java-tls	ENABLE_JAVA_TLS	false	Enable Java TLS instrumentation via dynamic agent loading
--enable-java-async-profiler	ENABLE_JAVA_ASYNC_PROFILER	false	Enable Java profiling via async-profiler (CPU, memory allocations, lock contention)
--go-heap-profiler	GO_HEAP_PROFILER	enabled	Go heap profiling mode: disabled, enabled (passive), or force (enable profiling in all Go apps)
--instrumentation-delay	INSTRUMENTATION_DELAY	30s	Delay before enabling Python GIL and Node.js event loop instrumentation, after a process is started
--container-allowlist	CONTAINER_ALLOWLIST	–	List of allowed containers (regex patterns)
--container-denylist	CONTAINER_DENYLIST	–	List of denied containers (regex patterns)
--skip-systemd-system-services	SKIP_SYSTEMD_SYSTEM_SERVICES	true	Skip well-known systemd system services (apt, motd, udev, etc.)
--exclude-http-requests-by-path	EXCLUDE_HTTP_REQUESTS_BY_PATH	–	Exclude HTTP paths from metrics/traces
--track-public-network	TRACK_PUBLIC_NETWORK	0.0.0.0/0	Public IP networks to track
--ephemeral-port-range	EPHEMERAL_PORT_RANGE	32768-60999	TCP ports to exclude from tracking
--provider	PROVIDER	–	provider label for node_cloud_info
--region	REGION	–	region label for node_cloud_info
--availability-zone	AVAILABILITY_ZONE	–	availability_zone label for node_cloud_info
--instance-type	INSTANCE_TYPE	–	instance_type label for node_cloud_info
--instance-life-cycle	INSTANCE_LIFE_CYCLE	–	instance_life_cycle label for node_cloud_info
--log-per-second	LOG_PER_SECOND	10.0	Rate limit for logs per second
--log-burst	LOG_BURST	100	Max burst for log rate limiting
--log-patterns-per-container	LOG_PATTERNS_PER_CONTAINER	256	Max unique log patterns per container per level
--max-fqdns-per-container	MAX_FQDNS_PER_CONTAINER	50	Max unique FQDN values per container in container_dns_requests_total; extras are bucketed under ~other
--max-label-length	MAX_LABEL_LENGTH	4096	Max metric label length
--collector-endpoint	COLLECTOR_ENDPOINT	–	Unified base URL for telemetry export
--api-key	API_KEY	–	Coroot API key
--metrics-endpoint	METRICS_ENDPOINT	–	Custom URL for metrics export
--traces-endpoint	TRACES_ENDPOINT	–	Custom URL for traces export
--traces-sampling	TRACES_SAMPLING	1.0	Trace sampling rate (0.0 to 1.0)
--logs-endpoint	LOGS_ENDPOINT	–	Custom URL for logs export
--profiles-endpoint	PROFILES_ENDPOINT	–	Custom URL for profiles export
--profiles-prune-fraction	PROFILES_PRUNE_FRACTION	0.0025	Drop insignificant profile code paths accounting for less than this fraction of the profile total (0 to disable)
--insecure-skip-verify	INSECURE_SKIP_VERIFY	false	Skip TLS certificate verification
--ca-file	CA_FILE	–	Path to the custom CA certificate file
--scrape-interval	SCRAPE_INTERVAL	15s	How often to collect internal metrics
--wal-dir	WAL_DIR	/tmp/coroot-node-agent	Directory for WAL storage
--max-spool-size	MAX_SPOOL_SIZE	500MB	Max size for on-disk spool

Windows

The Windows agent uses the same flags, but only the platform-independent subset. Linux-only capabilities (eBPF L7 tracing and profiling, cgroups, Java/Python/Node.js instrumentation, the ICMP pinger, systemd handling, and trace/profile export) do not apply.

Flag names are identical (for example --scrape-interval), but environment variables are prefixed with COROOT_. On Windows environment variables are global, so the prefix avoids clashing with other software. For example, SCRAPE_INTERVAL becomes COROOT_SCRAPE_INTERVAL.

Flag	Env Variable	Description
--collector-endpoint	COROOT_COLLECTOR_ENDPOINT	Base URL of your Coroot instance
--api-key	COROOT_API_KEY	Project API key
--scrape-interval	COROOT_SCRAPE_INTERVAL	Metrics collection interval
--metrics-endpoint / --logs-endpoint	COROOT_METRICS_ENDPOINT / COROOT_LOGS_ENDPOINT	Custom export URLs
--insecure-skip-verify	COROOT_INSECURE_SKIP_VERIFY	Skip TLS verification of the collector
--ca-file	COROOT_CA_FILE	Path to a custom CA certificate
--disable-log-parsing	COROOT_DISABLE_LOG_PARSING	Disable Windows Event Log and container log collection
--disable-json-log-parsing	COROOT_DISABLE_JSON_LOG_PARSING	Disable extracting the message, severity, and attributes from JSON-formatted logs
--disable-gpu-monitoring	COROOT_DISABLE_GPU_MONITORING	Disable NVIDIA GPU monitoring
--container-allowlist / --container-denylist	COROOT_CONTAINER_ALLOWLIST / COROOT_CONTAINER_DENYLIST	Regex of services to include or exclude
--provider / --region / --availability-zone / --instance-type / --instance-life-cycle	COROOT_PROVIDER and so on	Override node_cloud_info labels
--wal-dir / --max-spool-size	COROOT_WAL_DIR / COROOT_MAX_SPOOL_SIZE	Spool directory and max size
--listen	COROOT_LISTEN	Local /metrics listen address

See the Windows installation guide for setting these via the MSI or machine environment variables.

Container Environment Variables

You can disable specific functionality for individual containers by setting environment variables within the container:

Environment Variable	Description
COROOT_EBPF_PROFILING=disabled	Disable eBPF profiling for this container
COROOT_LOG_MONITORING=disabled	Disable log monitoring and parsing for this container
COROOT_EBPF_TRACES=disabled	Disable eBPF traces for this container

These environment variables are read from the container's process environment and allow fine-grained control over which containers are monitored by the agent.