[receiver/dockerstats] support pids_stats metrics (#21111)

pids_stats metrics were introduced in docker engine API v1.23 and that's the reason why docker's API default version has been bumped to 1.23. However, the minimum supported version has not been updated because the metrics are optional and reported only when pids cgroup is supported and the kernel is >= 4.3. On top of that, pids_stats may be reported even if the API request is performed using previous versions.

.chloggen/include-pids-stats.yaml

@@ -0,0 +1,16 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: dockerstatsreceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "docker container's `pids_stats` metrics are reported when available"
+
+# One or more tracking issues related to the change
+issues: [21041]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

receiver/dockerstatsreceiver/documentation.md

@@ -674,6 +674,26 @@ Packets sent.
 | ---- | ----------- | ------ |
 | interface | Network interface. | Any Str |
 
+### container.pids.count
+
+Number of pids in the container's cgroup.
+
+It requires docker API 1.23 or higher and kernel version >= 4.3 with pids cgroup supported. [More docs](https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt)
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
+| ---- | ----------- | ---------- | ----------------------- | --------- |
+| {pids} | Sum | Int | Cumulative | false |
+
+### container.pids.limit
+
+Maximum number of pids in the container's cgroup.
+
+It requires docker API 1.23 or higher and kernel version >= 4.3 with pids cgroup supported. [More docs](https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt)
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
+| ---- | ----------- | ---------- | ----------------------- | --------- |
+| {pids} | Sum | Int | Cumulative | false |
+
 ## Resource Attributes
 
 | Name | Description | Values | Enabled |

receiver/dockerstatsreceiver/internal/metadata/testdata/config.yaml

@@ -127,6 +127,10 @@ all_set:
       enabled: true
     container.network.io.usage.tx_packets:
       enabled: true
+    container.pids.count:
+      enabled: true
+    container.pids.limit:
+      enabled: true
   resource_attributes:
     container.hostname:
       enabled: true
@@ -266,6 +270,10 @@ none_set:
       enabled: false
     container.network.io.usage.tx_packets:
       enabled: false
+    container.pids.count:
+      enabled: false
+    container.pids.limit:
+      enabled: false
   resource_attributes:
     container.hostname:
       enabled: false

receiver/dockerstatsreceiver/metadata.yaml

@@ -628,3 +628,24 @@ metrics:
       aggregation: cumulative
     attributes:
       - interface
+
+  # Pids
+  container.pids.count:
+    enabled: false
+    description: "Number of pids in the container's cgroup."
+    extended_documentation: "It requires docker API 1.23 or higher and kernel version >= 4.3 with pids cgroup supported. [More docs](https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt)"
+    unit: "{pids}"
+    sum:
+      value_type: int
+      aggregation: cumulative
+      monotonic: false
+
+  container.pids.limit:
+    enabled: false
+    description: "Maximum number of pids in the container's cgroup."
+    extended_documentation: "It requires docker API 1.23 or higher and kernel version >= 4.3 with pids cgroup supported. [More docs](https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt)"
+    unit: "{pids}"
+    sum:
+      value_type: int
+      aggregation: cumulative
+      monotonic: false

receiver/dockerstatsreceiver/receiver.go

@@ -26,7 +26,7 @@ import (
 const defaultResourcesLen = 5
 
 const (
-	defaultDockerAPIVersion         = 1.22
+	defaultDockerAPIVersion         = 1.23
 	minimalRequiredDockerAPIVersion = 1.22
 )
 
@@ -115,6 +115,7 @@ func (r *receiver) recordContainerStats(now pcommon.Timestamp, containerStats *d
 	r.recordMemoryMetrics(now, &containerStats.MemoryStats)
 	r.recordBlkioMetrics(now, &containerStats.BlkioStats)
 	r.recordNetworkMetrics(now, &containerStats.Networks)
+	r.recordPidsMetrics(now, &containerStats.PidsStats)
 
 	// Always-present resource attrs + the user-configured resource attrs
 	resourceCapacity := defaultResourcesLen + len(r.config.EnvVarsToMetricLabels) + len(r.config.ContainerLabelsToMetricLabels)
@@ -255,3 +256,13 @@ func (r *receiver) recordCPUMetrics(now pcommon.Timestamp, cpuStats *dtypes.CPUS
 		r.mb.RecordContainerCPUUsagePercpuDataPoint(now, int64(v), fmt.Sprintf("cpu%s", strconv.Itoa(coreNum)))
 	}
 }
+
+func (r *receiver) recordPidsMetrics(now pcommon.Timestamp, pidsStats *dtypes.PidsStats) {
+	// pidsStats are available when kernel version is >= 4.3 and pids_cgroup is supported, it is empty otherwise.
+	if pidsStats.Current != 0 {
+		r.mb.RecordContainerPidsCountDataPoint(now, int64(pidsStats.Current))
+		if pidsStats.Limit != 0 {
+			r.mb.RecordContainerPidsLimitDataPoint(now, int64(pidsStats.Limit))
+		}
+	}
+}