From 57aacc006b892702e14e33a6bcdde37cbc5ab959 Mon Sep 17 00:00:00 2001 From: Stephen Wakely Date: Fri, 11 Jul 2025 10:26:17 +0100 Subject: [PATCH 1/2] Release 5.7 --- CHANGELOG.md | 7 ++++++ README.md | 42 +++++++++++++++++++++++++++++++++-- lib/datadog/statsd/version.rb | 2 +- 3 files changed, 48 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 480388ce..c16a5a54 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ [//]: # (comment: Don't forget to update lib/datadog/statsd/version.rb:DogStatsd::Statsd::VERSION when releasing a new version) +## 5.7.0 / 2025.07.11 + + * [FEATURE] Added origin detection via CGroups or `DD_EXTERNAL_ENV`. Cardinality can be specified + with a cardinality parameter. [#310][] by [@StephenWakely][] + ## 5.6.6 / 2025.03.19 * [OTHER] Rescue ThreadError when creating SenderThread. [#306][] by [@mperham][] @@ -493,6 +498,7 @@ Future versions are likely to introduce backward incompatibilities with < Ruby 1 [#301]: https://github.com/DataDog/dogstatsd-ruby/issues/301 [#303]: https://github.com/DataDog/dogstatsd-ruby/issues/303 [#306]: https://github.com/DataDog/dogstatsd-ruby/issues/306 +[#310]: https://github.com/DataDog/dogstatsd-ruby/issues/310 [@AMekss]: https://github.com/AMekss [@abicky]: https://github.com/abicky [@adimitrov]: https://github.com/adimitrov @@ -541,3 +547,4 @@ Future versions are likely to introduce backward incompatibilities with < Ruby 1 [@zachmccormick]: https://github.com/zachmccormick [@pudiva]: https://github.com/pudiva [@BlakeWilliams]: https://github.com/BlakeWilliams +[@StephenWakely]: https://github.com/StephenWakely diff --git a/README.md b/README.md index 5c7e3941..3a729f09 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,29 @@ statsd = Datadog::Statsd.new('localhost', 8125, single_thread: true) statsd.close() ``` -### Origin detection over UDP +### Origin detection in Kubernetes + +Origin detection is a method to detect the pod that DogStatsD packets are coming from and add the pod's tags to the tag list. + +#### Tag cardinality + +The tags that can be added to metrics can be found [here][tags]. The cardinality can be specified globally by setting the `DD_CARDINALITY` +environment or by passing a `'cardinality'` field to the constructor. Cardinality can also be specified per metric by passing the value +in the `cardinality:` option. Valid values for this parameter are `:none`, `:low`, `:orchestrator` or `:high`. If an invalid +value is passed, an `ArgumentError` is raised. + +Origin detection is achieved in a number of ways: + +#### CGroups + +On Linux the container ID can be extracted from `procfs` entries related to `cgroups`. The client reads from `/proc/self/cgroup` or +`/proc/self/mountinfo` to attempt to parse the container id. + +In cgroup v2, the container ID can be inferred by resolving the cgroup path from `/proc/self/cgroup`, combining it with the cgroup +mount point from `/proc/self/mountinfo]`. The resulting directory's inode is sent to the agent. Provided the agent is on the same +node as the client, this can be used to identify the pod's UID. + +### Over UDP Origin detection is a method to detect which pod DogStatsD packets are coming from, in order to add the pod's tags to the tag list. @@ -105,7 +127,20 @@ env: fieldPath: metadata.uid ``` -The DogStatsD client attaches an internal tag, `entity_id`. The value of this tag is the content of the `DD_ENTITY_ID` environment variable, which is the pod’s UID. +The DogStatsD client attaches an internal tag, `entity_id`. The value of this tag is the content of the `DD_ENTITY_ID` environment +variable, which is the pod’s UID. + +#### DD_EXTERNAL_ENV + +If the pod is annotated with the label: + +``` +admission.datadoghq.com/enabled: "true" +``` + +The [admissions controller] injects an environment variable `DD_EXTERNAL_ENV`. The value of this is sent in a field with the +metric which can be used by the agent to determine the metrics origin. + ## Usage @@ -235,3 +270,6 @@ dogstatsd-ruby is forked from Rein Henrichs' [original Statsd client](https://gi Copyright (c) 2011 Rein Henrichs. See LICENSE.txt for further details. + +[admissions controller]: https://docs.datadoghq.com/containers/cluster_agent/admission_controller/?tab=datadogoperator +[tags]: https://docs.datadoghq.com/containers/kubernetes/tag/?tab=datadogoperator diff --git a/lib/datadog/statsd/version.rb b/lib/datadog/statsd/version.rb index d38ce7dc..b475bb87 100644 --- a/lib/datadog/statsd/version.rb +++ b/lib/datadog/statsd/version.rb @@ -4,6 +4,6 @@ module Datadog class Statsd - VERSION = '5.6.6' + VERSION = '5.7.0' end end From 6e9d1c1a640c0136305d0eeb8a909160ae5c3cb5 Mon Sep 17 00:00:00 2001 From: Stephen Wakely Date: Fri, 11 Jul 2025 10:42:46 +0100 Subject: [PATCH 2/2] Set release date to unreleased --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c16a5a54..821035db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ [//]: # (comment: Don't forget to update lib/datadog/statsd/version.rb:DogStatsd::Statsd::VERSION when releasing a new version) -## 5.7.0 / 2025.07.11 +## 5.7.0 / Unreleased * [FEATURE] Added origin detection via CGroups or `DD_EXTERNAL_ENV`. Cardinality can be specified with a cardinality parameter. [#310][] by [@StephenWakely][]