Setting up telemetry on Microsoft Windows hosts doesn't have to feel like guesswork. If you're running infrastructure on Windows servers, collecting performance metrics, event logs, and traces requires a reliable, lightweight collector. Grafana Agent fills this gap by gathering system data locally and forwarding it securely to your observability backend.
Getting this collector running on a Windows machine involves downloading the installer, configuring local scrape parameters, and ensuring the Windows service runs reliably. Whether you're targeting Prometheus metrics or sending logs to Loki, proper deployment ensures you spot performance bottlenecks before users notice them.
Preparing Your Windows Server Environment
Before running any installation binaries, you need to verify system compatibility and network permissions. Grafana Agent on Windows supports 64-bit AMD64 architectures. You'll also need administrative privileges on the target server to install Windows services and modify local configuration files.
Network egress rules matter just as much as host permissions. Ensure your Windows firewall allows outbound traffic on TCP port 443 if you're pushing metrics to Grafana Cloud, or your internal port if you're streaming to an on-premises Prometheus or Mimir instance.
- Log in to your Windows Server using an account with local administrator rights.
- Open PowerShell as an administrator to check your system architecture by running
Get-WmiObject Win32_OperatingSystem | Select-Object OSArchitecture. - Verify that outbound network paths to your metrics ingestion endpoint are open and responsive.
Installing Grafana Agent on Windows
You can install the agent using either the standard graphical installer or a silent command-line script for automated deployments. The graphical approach works best for single servers, while silent options suit larger fleet rollouts.
Grab the latest Windows installer package (grafana-agent-installer.exe.zip) from the official Grafana GitHub releases page. Extract the contents to a temporary directory on your machine.
Double-click the extracted installer executable to launch the setup wizard. By default, the installer places the application files inside C:\Program Files\Grafana Agent or C:\Program Files\Grafana Agent Flow depending on the version. The installation process automatically registers the software as a native Windows service, ensuring it starts up automatically if the server reboots.
For automated scripting environments, execute a silent installation via PowerShell:
Start-Process -FilePath ".\grafana-agent-installer.exe" -ArgumentList "/S" -Wait
Configuring Metrics and Local Scrapes
Once installed, the core behavior of your collector is controlled via a configuration file. For static mode, you'll edit agent-config.yaml, and for flow mode, you'll modify config.river located in the installation directory.
To collect native operating system performance counters, enable the embedded windows_exporter integration. This extracts CPU, memory, disk utilization, and service states without requiring separate exporter binaries.
Open your configuration file using a text editor running with administrator permissions. Define your remote write blocks to point toward your telemetry storage backend, making sure to include necessary authentication headers or tokens.
server:
log_level: info
http_listen_port: 12345
metrics:
configs:
- name: windows-integrations
remote_write:
- url: https://prometheus-prod-us-central-01.grafana.net/api/v1/write
basic_auth:
username: "your_username"
password: "your_api_token"
scrape_configs:
- job_name: windows_exporter
static_configs:
- targets: ['localhost:12345']
After saving your adjustments, you must restart the background service to apply the new settings.
Managing the Windows Service
Because the agent runs as a native Windows service, you manage its lifecycle directly through standard operating system tools. If a configuration change fails, checking the Windows Event Logs provides immediate diagnostic feedback.
Open the Windows Services manager by pressing Win + R, typing services.msc, and pressing Enter. Locate the service named either Grafana Agent or Grafana Agent Flow. From here, you can stop, start, or restart the service.
Alternatively, manage the service state via an elevated PowerShell prompt:
Restart-Service -Name "Grafana Agent"
To confirm the service is healthy and scraping targets correctly, open a web browser on the host machine and navigate to http://localhost:12345/-/healthy or check the targets page at http://localhost:12345/agent/api/v1/targets. Seeing a healthy status confirms your local endpoint bindings are correct.
Common Configuration Mistakes
Avoiding a few typical missteps saves hours of troubleshooting when deploying monitoring agents across Windows environments.
- Incorrect File Paths: Using single backslashes in YAML configuration files often causes parsing errors. Always use double backslashes (
C:\\ProgramData\\Grafana\\) or forward slashes (C:/ProgramData/Grafana/) inside configuration files. - Firewall Blocking Local Ports: Forgetting to allow local loopback traffic or blocking the default HTTP listen port (
12345) prevents internal health checks from responding. - Ignoring Service Permissions: Running custom log scrapers that read protected Windows Event Log channels without granting the Grafana Agent service adequate local security privileges results in silent data omission.
- Stale Write-Ahead Logs: If you abruptly kill the service during disk I/O operations, a corrupted Write-Ahead Log (WAL) can block startup. Clear the contents of the
waldirectory inside your data storage path if the service loops on startup crashes.
Frequently Asked Questions
Can Grafana Agent collect Windows Event Logs alongside metrics?
Yes. You can configure log collection blocks to capture Windows Event Logs and forward them directly to Grafana Loki using embedded scraping rules. This unifies your metrics and log pipelines into a single agent binary.
How do I change the default HTTP port used by the agent?
You can modify the listening port by updating the server block in your YAML configuration file or by adjusting the command-line arguments stored in the Windows Registry under HKEY_LOCAL_MACHINE\SOFTWARE\Grafana\Grafana Agent.
What happens to my metrics if the network connection drops?
Grafana Agent utilizes a Write-Ahead Log (WAL) for its remote write pipelines. When network connectivity is lost, metrics are temporarily buffered to local disk storage and flushed automatically once the connection to your remote endpoint is restored.
Do I need to install windows_exporter separately?
No. The windows_exporter capability is built directly into the agent package as an internal integration. You only need to enable it inside your configuration file to start harvesting host performance counters.
