Skip to main content

CodeXray Windows Agent

The CodeXray Windows Agent brings Windows hosts into the same observability picture as your Linux fleet. It runs as a native Windows Service, collects hundreds of host, service, and workload metrics, and ships them to the CodeXray backend using the same project API key as every other agent.

Built on a proven foundation

The Windows Agent is built on windows_exporter, the widely-used Prometheus community exporter for Windows — extended to ship telemetry directly to the CodeXray backend and to integrate cleanly with the CodeXray UI.

What It Collects​

The Windows Agent exposes dozens of collectors, each targeting a different Windows subsystem or product. A few of the most commonly used:

CollectorWhat it reports
cpuPer-core CPU usage and C-states
memoryPhysical and virtual memory, page file, cache
logical_disk / physical_diskDisk usage, I/O rates, queue depths
netNetwork interface I/O and errors
osOS-level memory, processes, users
systemContext switches, system calls, exceptions
serviceWindows Service states (with name filters)
processPer-process CPU, memory, handles, threads
iisIIS sites and application pools
mssqlSQL Server performance objects
exchangeExchange Server metrics
hypervHyper-V host and guest metrics
ad / adfs / adcsActive Directory and certificate services
dns / dhcpDNS and DHCP server metrics
netframework.NET Framework runtime metrics
scheduled_taskWindows Task Scheduler execution state
textfileCustom Prometheus metrics from .prom files on disk (great for app-specific signals)
performancecounterAny Windows Performance Counter — powerful for custom metrics

The full list is long and covers almost every Windows role and feature. Enable only the collectors you need — keeping the surface area small keeps overhead low.

Requirements​

Host​

  • Windows Server 2016 or newer (or Windows 10/11 for workstation monitoring).
  • Admin privileges to install the service.
  • Architecture: amd64 or arm64.

Network​

  • Outbound HTTPS (or HTTP) to the CodeXray collector endpoint.
  • No inbound connectivity required.

Credentials​

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

Installation​

A Windows Installer package is provided — the easiest way to deploy the agent as a managed Windows Service.

  1. Download the CodeXray-Windows-Agent.msi from your CodeXray releases page.
  2. Double-click to install, or run silently from an elevated PowerShell:
msiexec /i CodeXray-Windows-Agent.msi /quiet `
  CODEXRAY_URL="https://your-codexray.example.com" `
  API_KEY="your-project-api-key"
  1. The installer registers codexray-windows-agent as a Windows Service and starts it automatically.

Verify:

Get-Service codexray-windows-agent

Standalone EXE​

For trials or environments where MSIs aren't permitted, a standalone binary is available:

.\codexray_windows_exporter.exe --config.file=config.yaml

Run it as a scheduled task, a custom service (via sc.exe create), or directly under a service manager of your choice.

Configuration​

Configuration is driven by a YAML file (config.yaml). Here's a minimal working example:

# Collectors to enable
collectors:
  enabled: cpu,cs,cpu_info,logical_disk,memory,net,os,process,service,system,tcp,time

collector:
  service:
    # Only report on these services (regex)
    include: "w3svc|mssqlserver|.*codexray.*"

# Web server (for local diagnostics)
web:
  listen-address: ":9182"

# Telemetry path
telemetry:
  path: /metrics

# CodeXray backend
codexray:
  url: https://your-codexray.example.com
  metrics-endpoint: /v1/metrics
  interval: 15   # seconds between pushes

# Logging
log:
  level: info
  format: logfmt
  file: stdout

Key sections​

SectionWhat it controls
collectors.enabledComma-separated list of collectors. Use only what you need — every enabled collector adds CPU and telemetry overhead.
collector.service.include / excludeRegex filters to scope which Windows Services are reported — avoids "noise from every Microsoft sub-service".
collector.processSimilar include/exclude regex filters for per-process metrics.
codexray.urlBase URL of your CodeXray collector (required).
codexray.intervalHow often the agent pushes to the backend. Defaults to a sensible value; tune for low-bandwidth links.
log.level / log.fileLog verbosity and destination (stdout, stderr, eventlog, or a file path). The MSI installer defaults to eventlog.

Listing available collectors​

To see what's available on your host:

.\codexray_windows_exporter.exe --collectors.print

Custom metrics via textfile or performance counters​

Two powerful escape hatches:

  • textfile collector: drop .prom files in a directory and they're served as metrics — ideal for shipping app-specific counters from scheduled jobs.
  • performancecounter collector: expose any Windows Performance Counter as a Prometheus metric, with custom labels and aggregations. Useful for third-party software (e.g., Photon server, custom ETW providers).

Verifying It's Working​

  1. Service status:

    Get-Service codexray-windows-agent

    The service should be Running.

  2. Local metrics endpoint: browse to http://localhost:9182/metrics on the Windows host — you should see a flood of windows_* metrics.

  3. CodeXray UI: the host appears in the Nodes view within a minute or two, with live CPU, memory, disk, and network data.

Troubleshooting "no metrics in UI"

If the service is running but no data shows up: (a) check the Event Log for agent errors (Get-EventLog -LogName Application -Source codexray-windows-agent), (b) confirm outbound connectivity to the collector URL from the host, and (c) verify the API_KEY is valid in the CodeXray UI.

Next Steps​