From 54b3ae7be7a29a992771bf17ba4f679a35855ebc Mon Sep 17 00:00:00 2001 From: Carlos Roman Date: Fri, 8 May 2026 09:46:53 +0100 Subject: [PATCH] feat: Adding initial integration assets for Datadog DogStatsD manifest, metadata, README, dashboard, and supporting asset files. Metrics are sourced from the client-side telemetry emitted by the official DogStatsD client libraries (Go, Python, Ruby, Java, PHP, .NET). --- .github/CODEOWNERS | 2 + .github/workflows/config/labeler.yml | 4 + datadog_dogstatsd/CHANGELOG.md | 7 + datadog_dogstatsd/README.md | 35 ++ .../assets/dashboards/dogstatsd_overview.json | 500 ++++++++++++++++++ datadog_dogstatsd/assets/dataflows.yaml | 5 + datadog_dogstatsd/assets/service_checks.json | 1 + datadog_dogstatsd/manifest.json | 47 ++ datadog_dogstatsd/metadata.csv | 16 + 9 files changed, 617 insertions(+) create mode 100644 datadog_dogstatsd/CHANGELOG.md create mode 100644 datadog_dogstatsd/README.md create mode 100644 datadog_dogstatsd/assets/dashboards/dogstatsd_overview.json create mode 100644 datadog_dogstatsd/assets/dataflows.yaml create mode 100644 datadog_dogstatsd/assets/service_checks.json create mode 100644 datadog_dogstatsd/manifest.json create mode 100644 datadog_dogstatsd/metadata.csv diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index dbba6f534c61e..d826a21d41081 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -46,6 +46,8 @@ manifest.json @DataDog/documentation @DataDog/agent-integrations /datadog_cluster_agent/*.md @DataDog/container-integrations @DataDog/agent-integrations @DataDog/documentation /datadog_csi_driver/ @DataDog/container-platform @DataDog/agent-integrations /datadog_csi_driver/*.md @DataDog/container-platform @DataDog/agent-integrations @DataDog/documentation +/datadog_dogstatsd/ @DataDog/agent-metric-pipelines @DataDog/agent-integrations +/datadog_dogstatsd/*.md @DataDog/agent-metric-pipelines @DataDog/agent-integrations @DataDog/documentation /datadog_operator/ @DataDog/container-ecosystems @DataDog/agent-integrations /datadog_operator/*.md @DataDog/container-ecosystems @DataDog/agent-integrations @DataDog/documentation /docker_daemon/ @DataDog/container-integrations @DataDog/agent-integrations diff --git a/.github/workflows/config/labeler.yml b/.github/workflows/config/labeler.yml index e440a28f2f028..694f736aa5942 100644 --- a/.github/workflows/config/labeler.yml +++ b/.github/workflows/config/labeler.yml @@ -422,6 +422,10 @@ integration/datadog_csi_driver: - changed-files: - any-glob-to-any-file: - datadog_csi_driver/**/* +integration/datadog_dogstatsd: +- changed-files: + - any-glob-to-any-file: + - datadog_dogstatsd/**/* integration/datadog_operator: - changed-files: - any-glob-to-any-file: diff --git a/datadog_dogstatsd/CHANGELOG.md b/datadog_dogstatsd/CHANGELOG.md new file mode 100644 index 0000000000000..2abe63caf5bb8 --- /dev/null +++ b/datadog_dogstatsd/CHANGELOG.md @@ -0,0 +1,7 @@ +# CHANGELOG - Datadog DogStatsD + +## 1.0.0 / 2026-05-01 + +***Added***: + +* Initial release of the Datadog DogStatsD integration. diff --git a/datadog_dogstatsd/README.md b/datadog_dogstatsd/README.md new file mode 100644 index 0000000000000..bfc49ef350366 --- /dev/null +++ b/datadog_dogstatsd/README.md @@ -0,0 +1,35 @@ +# Datadog DogStatsD + +## Overview + +This integration surfaces the [client-side telemetry][2] emitted by Datadog's official [DogStatsD][1] client libraries. The metrics are produced by the clients themselves, covering the full lifecycle of metric submission: how many metrics, events, and service checks were sent to the client by the application, how many payloads and bytes were successfully delivered to the Agent, and how many were dropped — whether due to a full sender queue or a writer error. When client-side aggregation is enabled, aggregation context counts are also reported. + +## Setup + +### Installation + +Please see the documentation for [DogStatsD][1]. + +## Data Collected + +### Metrics + +See [metadata.csv][3] for a list of metrics provided by this check. + +### Events + +The Datadog DogStatsD integration does not include any events. + +### Service Checks + +See [service_checks.json][4] for a list of service checks provided by this integration. + +## Troubleshooting + +Need help? Contact [Datadog support][5]. + +[1]: https://docs.datadoghq.com/developers/dogstatsd/ +[2]: https://docs.datadoghq.com/extend/dogstatsd/high_throughput/#client-side-telemetry +[3]: https://github.com/DataDog/integrations-core/blob/master/datadog_dogstatsd/metadata.csv +[4]: https://github.com/DataDog/integrations-core/blob/master/datadog_dogstatsd/assets/service_checks.json +[5]: https://docs.datadoghq.com/help/ diff --git a/datadog_dogstatsd/assets/dashboards/dogstatsd_overview.json b/datadog_dogstatsd/assets/dashboards/dogstatsd_overview.json new file mode 100644 index 0000000000000..7681bd2a62c52 --- /dev/null +++ b/datadog_dogstatsd/assets/dashboards/dogstatsd_overview.json @@ -0,0 +1,500 @@ +{ + "title": "Datadog DogStatsD", + "description": "Client-side telemetry emitted by Datadog's official DogStatsD client libraries (Go, Python, Ruby, Java, PHP, .NET).\n\nThis dashboard gives visibility into metric submission throughput, payload delivery health, drop causes, and client-side aggregation behavior.\n\nFor more information, see the [client-side telemetry documentation](https://docs.datadoghq.com/extend/dogstatsd/high_throughput/#client-side-telemetry).", + "widgets": [ + { + "id": 1001, + "definition": { + "type": "group", + "title": "Overview", + "background_color": "blue", + "show_title": true, + "layout_type": "ordered", + "widgets": [ + { + "id": 1002, + "definition": { + "type": "query_value", + "title": "Metrics Sent", + "title_size": "16", + "title_align": "left", + "autoscale": true, + "precision": 0, + "requests": [ + { + "formulas": [{"formula": "query1"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.metrics{$client,$client_transport}.as_count()", + "aggregator": "sum" + } + ], + "response_format": "scalar" + } + ] + }, + "layout": {"x": 0, "y": 0, "width": 3, "height": 2} + }, + { + "id": 1003, + "definition": { + "type": "query_value", + "title": "Bytes Sent", + "title_size": "16", + "title_align": "left", + "autoscale": true, + "precision": 0, + "requests": [ + { + "formulas": [{"formula": "query1"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.bytes_sent{$client,$client_transport}.as_count()", + "aggregator": "sum" + } + ], + "response_format": "scalar" + } + ] + }, + "layout": {"x": 3, "y": 0, "width": 3, "height": 2} + }, + { + "id": 1004, + "definition": { + "type": "query_value", + "title": "Packets Sent", + "title_size": "16", + "title_align": "left", + "autoscale": true, + "precision": 0, + "requests": [ + { + "formulas": [{"formula": "query1"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.packets_sent{$client,$client_transport}.as_count()", + "aggregator": "sum" + } + ], + "response_format": "scalar" + } + ] + }, + "layout": {"x": 6, "y": 0, "width": 3, "height": 2} + }, + { + "id": 1005, + "definition": { + "type": "query_value", + "title": "Packet Drop Rate", + "title_size": "16", + "title_align": "left", + "autoscale": false, + "precision": 2, + "custom_unit": "%", + "requests": [ + { + "formulas": [ + { + "formula": "query1 / (query1 + query2) * 100", + "conditional_formats": [ + {"palette": "white_on_green", "value": 1, "comparator": "<"}, + {"palette": "white_on_yellow", "value": 5, "comparator": "<"}, + {"palette": "white_on_red", "value": 5, "comparator": ">="} + ] + } + ], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.packets_dropped{$client,$client_transport}.as_count()", + "aggregator": "sum" + }, + { + "data_source": "metrics", + "name": "query2", + "query": "sum:datadog.dogstatsd.client.packets_sent{$client,$client_transport}.as_count()", + "aggregator": "sum" + } + ], + "response_format": "scalar" + } + ] + }, + "layout": {"x": 9, "y": 0, "width": 3, "height": 2} + } + ] + }, + "layout": {"x": 0, "y": 0, "width": 12, "height": 4} + }, + { + "id": 2001, + "definition": { + "type": "group", + "title": "Throughput", + "background_color": "green", + "show_title": true, + "layout_type": "ordered", + "widgets": [ + { + "id": 2002, + "definition": { + "type": "timeseries", + "title": "Metrics Sent by Type", + "title_size": "16", + "title_align": "left", + "show_legend": true, + "legend_layout": "horizontal", + "legend_columns": ["avg", "min", "max", "value", "sum"], + "requests": [ + { + "formulas": [{"formula": "query1", "alias": "Metrics"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.metrics_by_type{$client,$client_transport} by {metrics_type}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "bars", + "style": {"palette": "dog_classic", "line_type": "solid", "line_width": "normal"} + } + ], + "yaxis": {"include_zero": true, "scale": "linear", "min": "auto", "max": "auto"}, + "markers": [] + }, + "layout": {"x": 0, "y": 0, "width": 12, "height": 3} + }, + { + "id": 2003, + "definition": { + "type": "timeseries", + "title": "Events & Service Checks Sent", + "title_size": "16", + "title_align": "left", + "show_legend": true, + "legend_layout": "horizontal", + "legend_columns": ["avg", "min", "max", "value", "sum"], + "requests": [ + { + "formulas": [{"formula": "query1", "alias": "Events"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.events{$client,$client_transport}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "bars", + "style": {"palette": "dog_classic", "line_type": "solid", "line_width": "normal"} + }, + { + "formulas": [{"formula": "query1", "alias": "Service Checks"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.service_checks{$client,$client_transport}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "bars", + "style": {"palette": "cool", "line_type": "solid", "line_width": "normal"} + } + ], + "yaxis": {"include_zero": true, "scale": "linear", "min": "auto", "max": "auto"}, + "markers": [] + }, + "layout": {"x": 0, "y": 3, "width": 6, "height": 3} + }, + { + "id": 2004, + "definition": { + "type": "timeseries", + "title": "Bytes Sent", + "title_size": "16", + "title_align": "left", + "show_legend": true, + "legend_layout": "horizontal", + "legend_columns": ["avg", "min", "max", "value", "sum"], + "requests": [ + { + "formulas": [{"formula": "query1", "alias": "Bytes Sent"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.bytes_sent{$client,$client_transport}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "area", + "style": {"palette": "dog_classic", "line_type": "solid", "line_width": "normal"} + } + ], + "yaxis": {"include_zero": true, "scale": "linear", "min": "auto", "max": "auto"}, + "markers": [] + }, + "layout": {"x": 6, "y": 3, "width": 6, "height": 3} + }, + { + "id": 2005, + "definition": { + "type": "timeseries", + "title": "Packets Sent", + "title_size": "16", + "title_align": "left", + "show_legend": true, + "legend_layout": "horizontal", + "legend_columns": ["avg", "min", "max", "value", "sum"], + "requests": [ + { + "formulas": [{"formula": "query1", "alias": "Packets Sent"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.packets_sent{$client,$client_transport}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "bars", + "style": {"palette": "dog_classic", "line_type": "solid", "line_width": "normal"} + } + ], + "yaxis": {"include_zero": true, "scale": "linear", "min": "auto", "max": "auto"}, + "markers": [] + }, + "layout": {"x": 0, "y": 6, "width": 12, "height": 3} + } + ] + }, + "layout": {"x": 0, "y": 4, "width": 12, "height": 13} + }, + { + "id": 3001, + "definition": { + "type": "group", + "title": "Drops & Errors", + "background_color": "red", + "show_title": true, + "layout_type": "ordered", + "widgets": [ + { + "id": 3002, + "definition": { + "type": "timeseries", + "title": "Metrics Dropped on Receive (ChannelMode)", + "title_size": "16", + "title_align": "left", + "show_legend": true, + "legend_layout": "horizontal", + "legend_columns": ["avg", "min", "max", "value", "sum"], + "requests": [ + { + "formulas": [{"formula": "query1", "alias": "Dropped on Receive"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.metric_dropped_on_receive{$client,$client_transport}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "bars", + "style": {"palette": "warm", "line_type": "solid", "line_width": "normal"} + } + ], + "yaxis": {"include_zero": true, "scale": "linear", "min": "auto", "max": "auto"}, + "markers": [] + }, + "layout": {"x": 0, "y": 0, "width": 12, "height": 3} + }, + { + "id": 3003, + "definition": { + "type": "timeseries", + "title": "Packets Dropped by Cause", + "title_size": "16", + "title_align": "left", + "show_legend": true, + "legend_layout": "horizontal", + "legend_columns": ["avg", "min", "max", "value", "sum"], + "requests": [ + { + "formulas": [{"formula": "query1", "alias": "Queue Full"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.packets_dropped_queue{$client,$client_transport}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "bars", + "style": {"palette": "warm", "line_type": "solid", "line_width": "normal"} + }, + { + "formulas": [{"formula": "query1", "alias": "Writer Error"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.packets_dropped_writer{$client,$client_transport}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "bars", + "style": {"palette": "orange", "line_type": "solid", "line_width": "normal"} + } + ], + "yaxis": {"include_zero": true, "scale": "linear", "min": "auto", "max": "auto"}, + "markers": [] + }, + "layout": {"x": 0, "y": 3, "width": 6, "height": 3} + }, + { + "id": 3004, + "definition": { + "type": "timeseries", + "title": "Bytes Dropped by Cause", + "title_size": "16", + "title_align": "left", + "show_legend": true, + "legend_layout": "horizontal", + "legend_columns": ["avg", "min", "max", "value", "sum"], + "requests": [ + { + "formulas": [{"formula": "query1", "alias": "Queue Full"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.bytes_dropped_queue{$client,$client_transport}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "bars", + "style": {"palette": "warm", "line_type": "solid", "line_width": "normal"} + }, + { + "formulas": [{"formula": "query1", "alias": "Writer Error"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.bytes_dropped_writer{$client,$client_transport}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "bars", + "style": {"palette": "orange", "line_type": "solid", "line_width": "normal"} + } + ], + "yaxis": {"include_zero": true, "scale": "linear", "min": "auto", "max": "auto"}, + "markers": [] + }, + "layout": {"x": 6, "y": 3, "width": 6, "height": 3} + } + ] + }, + "layout": {"x": 0, "y": 17, "width": 12, "height": 9} + }, + { + "id": 4001, + "definition": { + "type": "group", + "title": "Client-Side Aggregation", + "background_color": "purple", + "show_title": true, + "layout_type": "ordered", + "widgets": [ + { + "id": 4002, + "definition": { + "type": "query_value", + "title": "Aggregated Contexts", + "title_size": "16", + "title_align": "left", + "autoscale": true, + "precision": 0, + "requests": [ + { + "formulas": [{"formula": "query1"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.aggregated_context{$client,$client_transport}.as_count()", + "aggregator": "sum" + } + ], + "response_format": "scalar" + } + ] + }, + "layout": {"x": 0, "y": 0, "width": 3, "height": 3} + }, + { + "id": 4003, + "definition": { + "type": "timeseries", + "title": "Aggregated Contexts by Type", + "title_size": "16", + "title_align": "left", + "show_legend": true, + "legend_layout": "horizontal", + "legend_columns": ["avg", "min", "max", "value", "sum"], + "requests": [ + { + "formulas": [{"formula": "query1", "alias": "Contexts"}], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "sum:datadog.dogstatsd.client.aggregated_context_by_type{$client,$client_transport} by {metrics_type}.as_count()" + } + ], + "response_format": "timeseries", + "display_type": "bars", + "style": {"palette": "dog_classic", "line_type": "solid", "line_width": "normal"} + } + ], + "yaxis": {"include_zero": true, "scale": "linear", "min": "auto", "max": "auto"}, + "markers": [] + }, + "layout": {"x": 3, "y": 0, "width": 9, "height": 3} + } + ] + }, + "layout": {"x": 0, "y": 26, "width": 12, "height": 5} + } + ], + "template_variables": [ + { + "name": "client", + "prefix": "client", + "available_values": [], + "default": "*" + }, + { + "name": "client_transport", + "prefix": "client_transport", + "available_values": [], + "default": "*" + } + ], + "layout_type": "ordered", + "is_read_only": false, + "notify_list": [] +} diff --git a/datadog_dogstatsd/assets/dataflows.yaml b/datadog_dogstatsd/assets/dataflows.yaml new file mode 100644 index 0000000000000..8534936083d2d --- /dev/null +++ b/datadog_dogstatsd/assets/dataflows.yaml @@ -0,0 +1,5 @@ +provides: + - id: datadog-dogstatsd-metrics + always_on: true + data_type: metrics + direction: inbound diff --git a/datadog_dogstatsd/assets/service_checks.json b/datadog_dogstatsd/assets/service_checks.json new file mode 100644 index 0000000000000..fe51488c7066f --- /dev/null +++ b/datadog_dogstatsd/assets/service_checks.json @@ -0,0 +1 @@ +[] diff --git a/datadog_dogstatsd/manifest.json b/datadog_dogstatsd/manifest.json new file mode 100644 index 0000000000000..b1fde96c7e6de --- /dev/null +++ b/datadog_dogstatsd/manifest.json @@ -0,0 +1,47 @@ +{ + "manifest_version": "2.0.0", + "app_uuid": "185e4205-b486-463f-a33b-55af8d4ffd3a", + "app_id": "datadog-dogstatsd", + "owner": "agent-onboarding", + "display_on_public_website": false, + "tile": { + "overview": "README.md#Overview", + "configuration": "README.md#Setup", + "support": "README.md#Support", + "changelog": "CHANGELOG.md", + "description": "Monitor DogStatsD", + "title": "Datadog DogStatsD", + "media": [], + "classifier_tags": [ + "Category::Metrics", + "Supported OS::Linux", + "Supported OS::Windows", + "Supported OS::macOS", + "Offering::Integration" + ] + }, + "assets": { + "dashboards": { + "Datadog DogStatsD Overview": "assets/dashboards/dogstatsd_overview.json" + }, + "integration": { + "source_type_name": "Datadog DogStatsD", + "metrics": { + "prefix": "datadog.dogstatsd.client.", + "check": "datadog.dogstatsd.client.metrics", + "metadata_path": "metadata.csv" + }, + "service_checks": { + "metadata_path": "assets/service_checks.json" + }, + "source_type_id": 10342, + "auto_install": true + } + }, + "author": { + "support_email": "help@datadoghq.com", + "name": "Datadog", + "homepage": "https://www.datadoghq.com", + "sales_email": "info@datadoghq.com" + } +} diff --git a/datadog_dogstatsd/metadata.csv b/datadog_dogstatsd/metadata.csv new file mode 100644 index 0000000000000..95cfa32e3e857 --- /dev/null +++ b/datadog_dogstatsd/metadata.csv @@ -0,0 +1,16 @@ +metric_name,metric_type,interval,unit_name,per_unit_name,description,orientation,integration,short_name,curated_metric +datadog.dogstatsd.client.metrics,count,,metric,,Total number of metrics sent by the client before aggregation and sampling,0,datadog_dogstatsd,client_metrics, +datadog.dogstatsd.client.metrics_by_type,count,,metric,,Number of metrics sent by the client before aggregation and sampling broken down by metric type (tag: metrics_type),0,datadog_dogstatsd,client_metrics_by_type, +datadog.dogstatsd.client.events,count,,event,,Total number of events sent by the client before aggregation and sampling,0,datadog_dogstatsd,client_events, +datadog.dogstatsd.client.service_checks,count,,,,Total number of service checks sent by the client before aggregation and sampling,0,datadog_dogstatsd,client_service_checks, +datadog.dogstatsd.client.metric_dropped_on_receive,count,,metric,,Total number of metrics/events/service checks dropped when using ChannelMode,-1,datadog_dogstatsd,client_metric_dropped_on_receive, +datadog.dogstatsd.client.packets_sent,count,,packet,,Total number of payloads successfully sent by the client,0,datadog_dogstatsd,client_packets_sent, +datadog.dogstatsd.client.packets_dropped,count,,packet,,Total number of payloads dropped by the client (sum of queue-full and writer drops),-1,datadog_dogstatsd,client_packets_dropped, +datadog.dogstatsd.client.packets_dropped_queue,count,,packet,,Total number of payloads dropped because the sender queue was full,-1,datadog_dogstatsd,client_packets_dropped_queue, +datadog.dogstatsd.client.packets_dropped_writer,count,,packet,,Total number of payloads dropped by the writer due to network timeout or error,-1,datadog_dogstatsd,client_packets_dropped_writer, +datadog.dogstatsd.client.bytes_sent,count,,byte,,Total number of bytes successfully sent by the client,0,datadog_dogstatsd,client_bytes_sent, +datadog.dogstatsd.client.bytes_dropped,count,,byte,,Total number of bytes dropped by the client (sum of queue-full and writer drops),-1,datadog_dogstatsd,client_bytes_dropped, +datadog.dogstatsd.client.bytes_dropped_queue,count,,byte,,Total number of bytes dropped because the sender queue was full,-1,datadog_dogstatsd,client_bytes_dropped_queue, +datadog.dogstatsd.client.bytes_dropped_writer,count,,byte,,Total number of bytes dropped by the writer due to network timeout or error,-1,datadog_dogstatsd,client_bytes_dropped_writer, +datadog.dogstatsd.client.aggregated_context,count,,,,Total number of contexts flushed by the aggregator when client-side aggregation is enabled,0,datadog_dogstatsd,client_aggregated_context, +datadog.dogstatsd.client.aggregated_context_by_type,count,,,,Number of contexts flushed by the aggregator broken down by metric type (tag: metrics_type),0,datadog_dogstatsd,client_aggregated_context_by_type,