Add an example showing how to use the collector with collectd (#5738)

Author: atoulme

examples/collectd/README.md

@@ -0,0 +1,57 @@
+# CollectD example
+
+This example shows how to connect a CollectD daemon running on a host to an OpenTelemetry Collector.
+
+For the purpose of this example, the host is represented by a Ubuntu 24.04 docker image.
+
+On this image, we install collectd as a Debian package, using stock instructions.
+
+We proceed to add configuration to CollectD to instruct it to have an active behavior:
+* We give it directions to ingest free disk related metrics through `collectd/metrics.conf`
+* We instruct CollectD to send data over HTTP using `collectd/http.conf`
+
+We also set up a collector to listen over HTTP for traffic from the collectD daemon.
+
+To do so, we set up the [collectd receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/collectdreceiver):
+
+```yaml
+    collectd:
+      endpoint: "0.0.0.0:8081"
+```
+
+Note we use `0.0.0.0` to make sure we expose the 8081 port over the Docker network interface so the 2 Docker containers may interact.
+
+We run the example with the instruction to start the docker-compose setup, building the collectd container:
+
+```bash
+$> docker compose up --build
+```
+
+We check that the collector is indeed receiving metrics and logging them to stdout via the debug exporter:
+
+```bash
+$> docker logs otelcollector
+```
+
+A typical example of output is:
+```
+StartTimestamp: 1970-01-01 00:00:00 +0000 UTC
+Timestamp: 2024-12-20 19:55:44.006000128 +0000 UTC
+Value: 38.976566
+Metric #17
+Descriptor:
+     -> Name: percent_bytes.reserved
+     -> Description: 
+     -> Unit: 
+     -> DataType: Gauge
+NumberDataPoints #0
+Data point attributes:
+     -> plugin: Str(df)
+     -> plugin_instance: Str(etc-hosts)
+     -> host: Str(ea1d62c7a229)
+     -> dsname: Str(value)
+StartTimestamp: 1970-01-01 00:00:00 +0000 UTC
+Timestamp: 2024-12-20 19:55:44.006000128 +0000 UTC
+Value: 5.102245
+        {"kind": "exporter", "data_type": "metrics", "name": "debug"}
+```

examples/collectd/collectd/Dockerfile

@@ -0,0 +1,5 @@
+FROM ubuntu:24.04
+
+RUN apt-get update && apt-get install -y collectd && apt-get clean
+
+CMD ["/usr/sbin/collectd", "-f"]

examples/collectd/collectd/http.conf

@@ -0,0 +1,13 @@
+# The minimal configuration required to have collectd send data to an OpenTelemetry Collector
+# with a collectdreceiver deployed on port 8081.
+
+LoadPlugin write_http
+<Plugin "write_http">
+   <Node "collector">
+     URL "http://otelcollector:8081"
+     Format JSON
+     VerifyPeer false
+     VerifyHost false
+   </Node>
+</Plugin>
+

examples/collectd/collectd/metrics.conf

@@ -0,0 +1,8 @@
+# An example of collectd plugin configuration reporting free disk space on the host.
+
+<LoadPlugin df>
+  Interval 3600
+</LoadPlugin>
+<Plugin df>
+  ValuesPercentage true
+</Plugin>

examples/collectd/docker-compose.yml

@@ -0,0 +1,17 @@
+version: "3"
+services:
+  collectd:
+    build: collectd
+    container_name: collectd
+    depends_on:
+      - otelcollector
+    volumes:
+      - ./collectd/http.conf:/etc/collectd/collectd.conf.d/http.conf
+      - ./collectd/metrics.conf:/etc/collectd/collectd.conf.d/metrics.conf
+  # OpenTelemetry Collector
+  otelcollector:
+    image:  quay.io/signalfx/splunk-otel-collector:latest
+    container_name: otelcollector
+    command: ["--config=/etc/otel-collector-config.yml", "--set=service.telemetry.logs.level=debug"]
+    volumes:
+      - ./otel-collector-config.yml:/etc/otel-collector-config.yml

examples/collectd/otel-collector-config.yml

@@ -0,0 +1,13 @@
+receivers:
+    collectd:
+      endpoint: "0.0.0.0:8081"
+
+exporters:
+    debug:
+      verbosity: detailed
+
+service:
+    pipelines:
+      metrics:
+        receivers: [collectd]
+        exporters: [debug]