docs: administration: monitoring: on-demand-flush: Add on-demand flush to the HTTP server

SUMMARY.md

@@ -64,6 +64,7 @@
 * [Monitoring](administration/monitoring.md)
 * [Multithreading](administration/multithreading.md)
 * [Networking](administration/networking.md)
+* [On-demand flush](administration/on-demand-flush.md)
 * [Performance tips](administration/performance.md)
 * [Scheduling and retries](administration/scheduling-and-retries.md)
 * [TLS](administration/transport-security.md)

administration/monitoring.md

@@ -124,6 +124,7 @@ Fluent Bit exposes the following endpoints for monitoring.
 | `/api/v2/metrics/prometheus` | Display internal metrics per loaded plugin ready in Prometheus Server format. | Prometheus Text 0.0.4 |
 | `/api/v2/health`             | Returns Fluent Bit health status as JSON. HTTP 200 when healthy, HTTP 500 when unhealthy. Response fields: `status` (`ok` or `error`), `errors`, `retries_failed`, `error_limit`, `retry_failure_limit`, `period_limit`. | JSON |
 | `/api/v2/reload`             | Execute hot reloading (`POST`, `PUT`) or get the status of hot reloading (`GET`). Unsupported methods return `405 Method Not Allowed` with an `Allow: GET, POST, PUT` header. See the [hot-reloading documentation](hot-reload.md). | JSON |
+| `/api/v2/flush`              | Trigger an on-demand flush of currently buffered records (`POST`, `PUT`) or get the current flush count (`GET`). Unsupported methods return `405 Method Not Allowed` with an `Allow: GET, POST, PUT` header. See the [on-demand flush documentation](on-demand-flush.md). | JSON |
 
 ### V1 metrics
 

administration/on-demand-flush.md

@@ -0,0 +1,79 @@
+---
+description: Trigger an immediate flush over HTTP, independent of the periodic Flush interval
+---
+
+# On-demand flush
+
+Fluent Bit supports triggering a flush of currently buffered records on demand, over the HTTP server, independent of the configured periodic `Flush` interval.
+
+## Enable the HTTP server
+
+To get started with on-demand flush over HTTP, enable the HTTP Server in the configuration file:
+
+{% tabs %}
+{% tab title="fluent-bit.yaml" %}
+
+```yaml
+service:
+  http_server: on
+  http_listen: 0.0.0.0
+  http_port: 2020
+```
+
+{% endtab %}
+{% tab title="fluent-bit.conf" %}
+
+```text
+[SERVICE]
+  HTTP_Server  On
+  HTTP_Listen  0.0.0.0
+  HTTP_PORT    2020
+```
+
+{% endtab %}
+{% endtabs %}
+
+## How to flush
+
+After enabling the HTTP server, use one of the following methods to trigger an on-demand flush:
+
+### HTTP
+
+Use the following HTTP endpoints to trigger an on-demand flush:
+
+- `PUT /api/v2/flush`
+- `POST /api/v2/flush`
+
+For using curl to trigger a flush, users must specify an empty request body as:
+
+```shell
+curl -X POST -d '{}' localhost:2020/api/v2/flush
+```
+
+Obtain a count of on-demand flushes using the HTTP endpoint:
+
+- `GET /api/v2/flush`
+
+The endpoint returns `flush_now_count` as follows:
+
+```json
+{"flush_now_count":3}
+```
+
+The default value of the counter is `0`.
+
+## Confirm a flush
+
+A successful request returns HTTP status `200` with the incremented counter:
+
+```json
+{"flush":"done","flush_now_count":3}
+```
+
+`flush_now_count` is a process-wide counter incremented once per on-demand flush processed by the engine. It's incremented when buffered chunks are dispatched to the output plugins. A `200` only guarantees the engine is processing chunks, not that they got pushed out or received by the outputs. Because the counter is global, it can't be used to correlate a response with a specific request when several flushes are issued concurrently.
+
+If the engine doesn't acknowledge the request within 2 seconds, the endpoint responds with HTTP status `503` and the counter unchanged:
+
+```json
+{"flush":"timeout","flush_now_count":0}
+```