From f50349d261b4c80377149e3c450b6292766c575d Mon Sep 17 00:00:00 2001
From: Markus <974709+Links2004@users.noreply.github.com>
Date: Thu, 5 Sep 2024 02:57:30 +0200
Subject: [PATCH] Add documentation for StatsD component (#3802)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu>
---
 components/statsd.rst | 53 +++++++++++++++++++++++++++++++++++++++++++
 index.rst             |  2 ++
 2 files changed, 55 insertions(+)
 create mode 100644 components/statsd.rst

diff --git a/components/statsd.rst b/components/statsd.rst
new file mode 100644
index 000000000..47881c92f
--- /dev/null
+++ b/components/statsd.rst
@@ -0,0 +1,53 @@
+.. _statsd:
+
+StatsD
+========
+
+.. seo::
+    :description: Instructions for setting up a StatsD
+    :keywords: StatsD, metrics
+
+StatsD is a `protocol <https://github.com/statsd/statsd/blob/master/docs/metric_types.md>`_ to send metrics to a Daemon to store and aggregate them.
+Today there are many monitoring solutions that support receiving metrics via the StatsD protocol.
+
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    statsd:
+      host: REPLACEME
+      sensors:
+        id: some_sensor
+        name: test1.sensor
+
+    sensor:
+      platform: ...
+      id: some_sensor
+
+
+This example will generate a metric named `test1.sensor` with the value of the `some_sensor` sensor.
+
+
+Configuration variables:
+------------------------
+
+- **host** (**Required**, ip): The Host IP of your StatsD Server.
+- **post** (*Optional*, uint16): The Port of your StatsD Server. Defaults to ``8125``.
+- **prefix** (*Optional*, string): The prefix to automatically prepend every metric with.  Defaults to ``""``.
+- **update_interval** (*Optional*, uint16): How often to send the metrics. Defaults to ``10s``.
+- **sensor** (*Optional*, :ref:`sensors`): A list of sensors to generate metrics for.
+- **binary_sensor** (*Optional*, :ref:`sensors`): A list of binary sensors to generate metrics for.
+
+.. _sensors:
+
+Sensor list
+-----------
+
+- **id** (**Required**, :ref:`config-id`): The ID of the sensor.
+- **name** (**Required**, name): The Name of the metric the sensor value is send as. (Prefix is added to this name).
+
+See Also
+--------
+
+- :apiref:`statsd/statsd.h`
+- :ghedit:`Edit`
diff --git a/index.rst b/index.rst
index ee5de2264..743bb24f6 100644
--- a/index.rst
+++ b/index.rst
@@ -204,6 +204,7 @@ Network Protocols
     HTTP Request, components/http_request, connection.svg, dark-invert
     mDNS, components/mdns, radio-tower.svg, dark-invert
     WireGuard, components/wireguard, wireguard_custom_logo.svg
+    StatsD, components/statsd, connection.svg
     UDP, components/udp, udp.svg
 
 Bluetooth/BLE
@@ -225,6 +226,7 @@ Management and Monitoring
     Debug, components/debug, bug-report.svg, dark-invert
     Logger, components/logger, file-document-box.svg, dark-invert
     Prometheus, components/prometheus, prometheus.svg
+    StatsD, components/statsd, connection.svg
     Safe Mode, components/safe_mode, restart-alert.svg
     Web Server, components/web_server, http.svg, dark-invert
     ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg, dark-invert