# monitor\_agent The `in_monitor_agent` Input plugin exports Fluentd's internal metrics via REST API. It is included in Fluentd's core. ## Example Configuration ``` @type monitor_agent bind 0.0.0.0 port 24220 ``` This configuration launches HTTP server with 24220 port and get metrics: ``` $ curl http://host:24220/api/plugins.json ``` Also you can fetch the same data in LTSV format: ``` $ curl http://host:24220/api/plugins ``` Refer to the [Configuration File](https://docs.fluentd.org/configuration/config-file) article for the basic structure and syntax of the configuration file. ## Parameters See [Common Parameters](https://docs.fluentd.org/configuration/plugin-common-parameters). ### `@type` (required) The value must be `monitor_agent`. ### `port` | type | default | version | | ------- | ------- | ------- | | integer | 24220 | 0.14.0 | The port to listen to. ### `bind` | type | default | version | | ------ | ----------------------- | ------- | | string | 0.0.0.0 (all addresses) | 0.14.0 | The bind address to listen to. ### `tag` | type | default | version | | ------ | ------- | ------- | | string | nil | 0.14.0 | If you set this parameter, this plugin emits metrics as records. See "Reuse plugins" section. ### `emit_interval` | type | default | version | | ------- | ------- | ------- | | integer | 60 | 0.14.0 | The interval time between event emits. This will be used when `tag` is configured. ### `include_config` | type | default | version | | ---- | ------- | ------- | | bool | true | 0.14.0 | You can set this option to false to remove the `config` field from the response. ### `include_retry` | type | default | version | | ---- | ------- | ------- | | bool | true | 0.14.11 | You can set this option to false to remove the `retry` field from the response. ## Configuration Example Here is a configuration example using `in_monitor_agent`: ``` @type monitor_agent @id in_monitor_agent include_config false @type forward @id in_forward @type elasticsearch @id out_es ``` When using this plugin, we strongly recommend setting `@id` on **each** plugin in use. This makes the task to identify which record corresponds to which plugin much easier. Without `@id`, Fluentd uses `object_id` as the unique identifier, so you cannot identify a record just by looking at its `plugin_id` field. ## Output Example Here is how the output looks like in JSON: ``` { "plugins": [ { "plugin_id": "in_monitor_agent", "plugin_category": "input", "type": "monitor_agent", "output_plugin": false, "retry_count": null, "emit_records": 0, "emit_size": 0 }, { "plugin_id": "in_forward", "plugin_category": "input", "type": "forward", "output_plugin": false, "retry_count": null, "emit_records": 0, "emit_size": 0 }, { "plugin_id": "out_es", "plugin_category": "output", "type": "elasticsearch", "output_plugin": true, "buffer_queue_length": 0, "buffer_timekeys": [], "buffer_total_queued_size": 0, "retry_count": 0, "emit_records": 0, "emit_size": 0, "emit_count": 0, "write_count": 0, "write_secondary_count": 0, "rollback_count": 0, "slow_flush_count": 0, "flush_time_count": 0, "drop_oldest_chunk_count": 0, "buffer_stage_length": 0, "buffer_stage_byte_size": 0, "buffer_queue_byte_size": 0, "buffer_available_buffer_space_ratios": 100.0, "retry": {} } ] } ``` If the plugin is an output plugin with the buffer settings, the metrics include the buffer related fields. ### `retry` If the output plugin is in retry status, additional fields are added to `retry`. For example, if the Elasticsearch plugin fails to flush the buffer. Here is the response: ``` { "plugin_id": "out_es", "plugin_category": "output", "type": "elasticsearch", "output_plugin": true, "buffer_queue_length": 1, "buffer_timekeys": [], "buffer_total_queued_size": 117, "retry_count": 4, "emit_records": 1, "emit_size": 0, "emit_count": 1, "write_count": 4, "write_secondary_count": 0, "rollback_count": 4, "slow_flush_count": 0, "flush_time_count": 0, "drop_oldest_chunk_count": 0, "buffer_stage_length": 0, "buffer_stage_byte_size": 0, "buffer_queue_byte_size": 117, "buffer_available_buffer_space_ratios": 100.0, "retry": { "start": "2025-05-29 16:05:36 +0900", "steps": 3, "next_time": "2025-05-29 16:05:52 +0900" } } ``` `steps` field in `retry` show the number of flush failures, so next is the third try. `retry_count` is the total number of flush failures. This value is cleared when `fluentd` restarts, not when retry succeeds. ## Tips and Tricks ### How to use query parameters to tune outputs This plugin supports a number of query parameters with which you can customize the output format of HTTP responses. For example, you can append `debug=1` to the request URL to get the verbose internal metrics: ``` $ curl http://localhost:24220/api/plugins.json?debug=1 ``` The following list shows the available query parameters: | Parameter | Value | Explanation | | ------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `debug` | Constant | Expose additional internal metrics. Note that sensitive configuration value (password and so on) will be shown without obfuscating | | `with_ivars` | Variable names | Expose the specified instance variables of each plugin | | `with_config` | Boolean | Override the configuration option with\_config | | `with_retry` | Boolean | Override the configuration option with\_retry | | `tag` | Event tag | Only show plugins that matches the specified tag | | `@id` | Plugin id | Filter plugins by plugin id | | `@type` | Plugin type | Filter plugins by plugin type | ### How to emit metrics as events You can emit the internal metrics as events by setting the `tag`. For example: ``` @type monitor_agent tag debug.monitor emit_interval 60 port 24230 ``` Note that `in_monitor_agent` produces separate records for each plugin. Thus, using this configuration, you will receive events like below once per minute: ``` 2018-01-30 22:53:29.591560000 +0900 debug.monitor: { "plugin_id":"object:3ffd9988bea0","plugin_category":"input","type":"monitor_agent","output_plugin":false,"retry_count":null} 2018-01-30 22:53:29.591560000 +0900 debug.monitor: { "plugin_id":"in_forward","plugin_category":"input","type":"forward","output_plugin":false,"retry_count":null} 2018-01-30 22:53:29.591560000 +0900 debug.monitor: { "plugin_id":"out_out","plugin_category":"output","type":"stdout","output_plugin":true,"retry_count":0} ``` ### Multi-Process Environment If you use this plugin under the multi-process environment, the HTTP server will be launched in each worker. Port is assigned sequentially. For example, with this configuration: ``` workers 3 @type monitor_agent port 24230 ``` Three (3) HTTP servers will be launched with: * port 24230 for worker 0 * port 24231 for worker 1 * port 24232 for worker 2 Note that you may need to set `worker_id` to `@id` parameter. See [config article](https://docs.fluentd.org/configuration/config-file#embedded-ruby-code). If this article is incorrect or outdated, or omits critical information, please [let us know](https://github.com/fluent/fluentd-docs-gitbook/issues?state=open). [Fluentd](http://www.fluentd.org/) is an open-source project under [Cloud Native Computing Foundation (CNCF)](https://cncf.io/). All components are available under the Apache 2 License. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.fluentd.org/input/monitor_agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.