avinal commented on code in PR #7188: URL: https://github.com/apache/apisix/pull/7188#discussion_r888615226
########## docs/en/latest/plugins/datadog.md: ########## @@ -23,62 +29,93 @@ title: datadog ## Description -`datadog` is a monitoring plugin built into Apache APISIX for seamless integration with [Datadog](https://www.datadoghq.com/), one of the most used monitoring and observability platform for cloud applications. If enabled, this plugin supports multiple powerful types of metrics capture for every request and response cycle that essentially reflects the behaviour and health of the system. +The `datadog` monitoring Plugin if for seamless integration of APISIX with [Datadog](https://www.datadoghq.com/), one of the most used monitoring and observability platform for cloud applications. -This plugin pushes its custom metrics to the DogStatsD server, comes bundled with Datadog agent (to learn more about how to install a datadog agent, please visit [here](https://docs.datadoghq.com/agent/) ), over the UDP protocol. DogStatsD basically is an implementation of StatsD protocol which collects the custom metrics for Apache APISIX agent, aggregates it into a single data point and sends it to the configured Datadog server. -To learn more about DogStatsD, please visit [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/?tab=hostagent) documentation. +When enabled, the Plugin supports multiple metric capture types for request and response cycles. -This plugin provides the ability to push metrics as a batch to the external Datadog agent, reusing the same datagram socket. In case if you did not receive the log data, don't worry give it some time. It will automatically send the logs after the timer function expires in our Batch Processor. +This Plugin, pushes its custom metrics to the [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/?tab=hostagent) server over UDP protocol and comes bundled with [Datadog agent](https://docs.datadoghq.com/agent/). -For more info on Batch-Processor in Apache APISIX please refer. -[Batch-Processor](../batch-processor.md) +DogStatsD is basically an implementation of the StatsD protocol which collects the custom metrics for Apache APISIX agent, aggregates it into a single data point, and sends it to the configured Datadog server. + +This Plugin provides the ability to push metrics as a batch to the external Datadog agent, reusing the same datagram socket. It might take some time to receive the log data. It will be automatically sent after the timer function in the [batch processor](../batch-processor.md) expires. ## Attributes -| Name | Type | Requirement | Default | Valid | Description | -| ----------- | ------ | ----------- | ------- | ----- | ------------------------------------------------------------ | -| prefer_name | boolean | optional | true | true/false | If set to `false`, would use route/service id instead of name(default) with metric tags. | +| Name | Type | Required | Default | Valid values | Description | +| ----------- | ------- | -------- | ------- | ------------ | ---------------------------------------------------------------------------------------- | +| prefer_name | boolean | False | true | true/false | When set to `false`, uses Route/Service ID instead of name (default) with metric tags. | -The plugin supports the use of batch processors to aggregate and process entries(logs/data) in a batch. This avoids frequent data submissions by the plugin, which by default the batch processor submits data every `5` seconds or when the data in the queue reaches `1000`. For information or custom batch processor parameter settings, see [Batch-Processor](../batch-processor.md#configuration) configuration section. +This Plugin supports using batch processors to aggregate and process entries (logs/data) in a batch. This avoids the need for frequently submitting the data. The batch processor submits data every `5` seconds or when the data in the queue reaches `1000`. See [Batch Processor](../batch-processor.md#configuration) for more information or setting your custom configuration. ## Metadata -| Name | Type | Requirement | Default | Valid | Description | -| ----------- | ------ | ----------- | ------- | ----- | ---------------------------------------------------------------------- | -| host | string | optional | "127.0.0.1" | | The DogStatsD server host address | -| port | integer | optional | 8125 | | The DogStatsD server host port | -| namespace | string | optional | "apisix" | | Prefix for all the custom metrics sent by APISIX agent. Useful for finding entities for metric graph. e.g. (apisix.request.counter) | -| constant_tags | array | optional | [ "source:apisix" ] | | Static tags embedded into generated metrics. Useful for grouping metric over certain signals. | +You can configure the Plugin through the Plugin metadata. + +| Name | Type | Required | Default | Description | +|---------------|---------|----------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| host | string | False | "127.0.0.1" | DogStatsD server host address. | +| port | integer | False | 8125 | DogStatsD server host port. | +| namespace | string | False | "apisix" | Prefix for all custom metrics sent by APISIX agent. Useful for finding entities for metrics graph. For example, `apisix.request.counter`. | +| constant_tags | array | False | [ "source:apisix" ] | Static tags to embed into generated metrics. Useful for grouping metrics over certain signals. | + +:::tip + +See [defining tags](https://docs.datadoghq.com/getting_started/tagging/#defining-tags) to know more about how to effectively use tags. + +::: + +By default, the Plugin expects the DogStatsD service to be available at `127.0.0.1:8125`. If you want to change this, you can update the Plugin metadata as shown below: + +```shell +curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/datadog -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "host": "172.168.45.29", + "port": 8126, + "constant_tags": [ + "source:apisix", + "service:custom" + ], + "namespace": "apisix" +}' +``` + +To reset to default configuration, make a PUT request with empty body: -To know more about how to effectively write tags, please visit [here](https://docs.datadoghq.com/getting_started/tagging/#defining-tags) +```shell +curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/datadog -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{}' +``` -## Exported Metrics +## Exported metrics -Apache APISIX agent, for every request response cycle, export the following metrics to DogStatsD server if the datadog plugin is enabled: +When the `datadog` Plugin is enabled, APISIX agent exports the following metrics to the DogStatsD server for each request/response cycle: Review Comment: ```suggestion When the `datadog` Plugin is enabled, the APISIX agent exports the following metrics to the DogStatsD server for each request/response cycle: ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
