mirrors/prometheus
1
0
Fork 0
mirror of https://github.com/prometheus/prometheus.git synced 2025-12-03 16:41:05 +01:00
Code Issues Projects Releases Wiki Activity

Update Prometheus Agent doc (#17591)

Browse Source 
* Add a nav title to fix docs website generator.
* Make it more clear that "Prometheus Agent" is a mode, not a seaparate
  service.
* Add to index.
* Cleanup some wording.
* Add a downsides section.

Signed-off-by: SuperQ <superq@gmail.com>
(cherry picked from commit d0d2699dc5f454ebca53e56247281447f8dd8c5a)
This commit is contained in:
Ben Kochie 2025-11-21 11:34:19 +01:00 committed by SuperQ
parent a9bfead81a
commit b415208a90
No known key found for this signature in database
GPG Key ID: C646B23C9E3245F1
2 changed files with 18 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/index.md
View File

@ -13,6 +13,7 @@ The documentation is available alongside all the project documentation at
- [Getting started](getting_started.md)
- [Installation](installation.md)
- [Agent Mode](prometheus_agent.md)
- [Configuration](configuration/configuration.md)
- [Querying](querying/basics.md)
- [Storage](storage.md)

23
docs/prometheus_agent.md
View File

@ -1,8 +1,11 @@
---
# todo: internal
title: Prometheus Agent Mode
nav_title: Agent Mode
sort_rank: 4
---
## Prometheus Agent
## Prometheus Agent Mode
The Prometheus Agent is an operational mode built into the Prometheus binary with the same scraping APIs, semantics, configuration, and discovery mechanism; this agent mode disables some of Prometheus' usual features(TSDB, alerting, and rule evaluations) and optimizes the binary for scraping and remote writing to remote locations.
The Prometheus Remote Write protocol forwards(streams) all or a subset of metrics collected by Prometheus to a remote location; you can configure Prometheus to forward some metrics (if you want, with all metadata and exemplars!) to one or more locations that support the Remote Write API.
@ -15,11 +18,19 @@ The Agent mode optimizes Prometheus for the remote write use case. It disables q
In essence, it looks like this:
![Prometheus Agent Remote Write](./images/prometheus_agent.png)
### Benefits of The Prometheus Agent
- First of all, efficiency; The customized Agent TSDB WAL removes the data immediately after successful writes. If it cannot reach the remote endpoint, it persists the data temporarily on the disk until the remote endpoint is back online. This is currently limited to a two-hour buffer only, similar to non-agent Prometheus. This means that we don't need to build chunks of data in memory. We don't need to maintain a full index for querying purposes. Essentially the Agent mode uses a fraction of the resources that a normal Prometheus server would use in a similar situation.
- Secondly, the benefit of the Agent mode is that it enables easier [horizontal scalability for ingestion](https://prometheus.io/blog/2021/11/16/agent/#the-dream-auto-scalable-metric-ingestion).
### Benefits of agent mode
- Improved efficency. The customized Agent TSDB WAL removes the data immediately after successful writes. If it cannot reach the remote endpoint, it persists the data temporarily on the disk until the remote endpoint is back online. This is currently limited to a two-hour buffer only, similar to non-agent Prometheus. This means that there is no need to build chunks of data in memory or maintain a full index for querying purposes. Essentially the Agent mode uses a fraction of the resources that a normal Prometheus server would use in a similar situation.
- Agent mode eables easier [horizontal scalability for ingestion](https://prometheus.io/blog/2021/11/16/agent/#the-dream-auto-scalable-metric-ingestion).
### Downsides of agent mode
- No local queries. You can not query the local Prometheus instance.
- Recording rules are not possible. You can not pre-summarize data for sending to remote write. Rules must be done remotely.
- No alerting. All alerting must be done by the remote system.
### How to Use Agent Mode in Detail
If you show the help output of Prometheus (--help flag), you should see more or less the following:
```
@ -40,4 +51,4 @@ Flags:
Use the `--agent` flag to run Prometheus in the Agent mode. The rest of the flags are either for both server and Agent or only for a specific mode. You can see which flag is for which mode by checking the last sentence of a flag's help string. "Use with server mode only" means it's only for server mode. If you don't see any mention like this, it means the flag is shared.
The Agent mode accepts the same scrape configuration with the same discovery options and remote write options. It also exposes a web UI on port 9095 with disabled query capabilities but shows build info, configuration, targets, and service discovery information as in a normal Prometheus server.
The Agent mode accepts the same scrape configuration with the same discovery options and remote write options. It also exposes a web UI on port 9095 with disabled query capabilities but shows build info, configuration, targets, and service discovery information as in a normal Prometheus server.