From b94f12fa076779927dda02f04bb1c99588095e59 Mon Sep 17 00:00:00 2001 From: Antoine Toulme Date: Fri, 20 Dec 2024 13:02:57 -0800 Subject: [PATCH] Add an example showing how to use the collector with collectd (#5738) --- examples/collectd/README.md | 57 +++++++++++++++++++++ examples/collectd/collectd/Dockerfile | 5 ++ examples/collectd/collectd/http.conf | 13 +++++ examples/collectd/collectd/metrics.conf | 8 +++ examples/collectd/docker-compose.yml | 17 ++++++ examples/collectd/otel-collector-config.yml | 13 +++++ 6 files changed, 113 insertions(+) create mode 100644 examples/collectd/README.md create mode 100644 examples/collectd/collectd/Dockerfile create mode 100644 examples/collectd/collectd/http.conf create mode 100644 examples/collectd/collectd/metrics.conf create mode 100644 examples/collectd/docker-compose.yml create mode 100644 examples/collectd/otel-collector-config.yml diff --git a/examples/collectd/README.md b/examples/collectd/README.md new file mode 100644 index 0000000000..715c3cdbc8 --- /dev/null +++ b/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"} +``` \ No newline at end of file diff --git a/examples/collectd/collectd/Dockerfile b/examples/collectd/collectd/Dockerfile new file mode 100644 index 0000000000..9063d08e9d --- /dev/null +++ b/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"] \ No newline at end of file diff --git a/examples/collectd/collectd/http.conf b/examples/collectd/collectd/http.conf new file mode 100644 index 0000000000..a433cdedcb --- /dev/null +++ b/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 + + + URL "http://otelcollector:8081" + Format JSON + VerifyPeer false + VerifyHost false + + + diff --git a/examples/collectd/collectd/metrics.conf b/examples/collectd/collectd/metrics.conf new file mode 100644 index 0000000000..38905e2630 --- /dev/null +++ b/examples/collectd/collectd/metrics.conf @@ -0,0 +1,8 @@ +# An example of collectd plugin configuration reporting free disk space on the host. + + + Interval 3600 + + + ValuesPercentage true + diff --git a/examples/collectd/docker-compose.yml b/examples/collectd/docker-compose.yml new file mode 100644 index 0000000000..06129ba5a3 --- /dev/null +++ b/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 diff --git a/examples/collectd/otel-collector-config.yml b/examples/collectd/otel-collector-config.yml new file mode 100644 index 0000000000..cd5cb40500 --- /dev/null +++ b/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]