receiver/dockerstatsreceiver: add container.uptime metric (open-telemetry#22851)

* receiver/dockerstatsreceiver: add container.uptime metric

This change adds the `container.uptime` metric which indicates time
elapsed (in seconds) since the container started.

* Add scraper error for invalid time format

* Disable by default

* empty

Author: gbbr

.chloggen/gbbr_dockerstats-container.uptime.yaml

@@ -0,0 +1,20 @@
+# Use this changelog template to create an entry for release notes.
+# If your change doesn't affect end users, such as a test fix or a tooling change,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+
+# 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: Add container.uptime metric, indicating time elapsed since the start of the container.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [22037]
+
+# (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

@@ -686,6 +686,14 @@ It requires docker API 1.23 or higher and kernel version >= 4.3 with pids cgroup
 | ---- | ----------- | ---------- | ----------------------- | --------- |
 | {pids} | Sum | Int | Cumulative | false |
 
+### container.uptime
+
+Time elapsed since container start time.
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| s | Gauge | Double |
+
 ## Resource Attributes
 
 | Name | Description | Values | Enabled |

receiver/dockerstatsreceiver/internal/metadata/generated_config.go

@@ -129,6 +129,8 @@ all_set:
       enabled: true
     container.pids.limit:
       enabled: true
+    container.uptime:
+      enabled: true
   resource_attributes:
     container.hostname:
       enabled: true
@@ -270,6 +272,8 @@ none_set:
       enabled: false
     container.pids.limit:
       enabled: false
+    container.uptime:
+      enabled: false
   resource_attributes:
     container.hostname:
       enabled: false

receiver/dockerstatsreceiver/internal/metadata/generated_config_test.go

@@ -649,3 +649,11 @@ metrics:
       value_type: int
       aggregation: cumulative
       monotonic: false
+
+  # Base
+  container.uptime:
+    enabled: false
+    description: "Time elapsed since container start time."
+    unit: s
+    gauge:
+      value_type: double

receiver/dockerstatsreceiver/internal/metadata/generated_metrics.go

@@ -11,6 +11,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/docker/docker/api/types"
 	dtypes "github.com/docker/docker/api/types"
 	"go.opentelemetry.io/collector/component"
 	"go.opentelemetry.io/collector/pdata/pcommon"
@@ -104,18 +105,24 @@ func (r *receiver) scrapeV2(ctx context.Context) (pmetric.Metrics, error) {
 			errs = multierr.Append(errs, scrapererror.NewPartialScrapeError(res.err, 0))
 			continue
 		}
-		r.recordContainerStats(now, res.stats, res.container)
+		if err := r.recordContainerStats(now, res.stats, res.container); err != nil {
+			errs = multierr.Append(errs, err)
+		}
 	}
 
 	return r.mb.Emit(), errs
 }
 
-func (r *receiver) recordContainerStats(now pcommon.Timestamp, containerStats *dtypes.StatsJSON, container *docker.Container) {
+func (r *receiver) recordContainerStats(now pcommon.Timestamp, containerStats *dtypes.StatsJSON, container *docker.Container) error {
+	var errs error
 	r.recordCPUMetrics(now, &containerStats.CPUStats, &containerStats.PreCPUStats)
 	r.recordMemoryMetrics(now, &containerStats.MemoryStats)
 	r.recordBlkioMetrics(now, &containerStats.BlkioStats)
 	r.recordNetworkMetrics(now, &containerStats.Networks)
 	r.recordPidsMetrics(now, &containerStats.PidsStats)
+	if err := r.recordBaseMetrics(now, container.ContainerJSONBase); err != nil {
+		errs = multierr.Append(errs, err)
+	}
 
 	// Always-present resource attrs + the user-configured resource attrs
 	resourceCapacity := defaultResourcesLen + len(r.config.EnvVarsToMetricLabels) + len(r.config.ContainerLabelsToMetricLabels)
@@ -145,6 +152,7 @@ func (r *receiver) recordContainerStats(now pcommon.Timestamp, containerStats *d
 	}
 
 	r.mb.EmitForResource(resourceMetricsOptions...)
+	return errs
 }
 
 func (r *receiver) recordMemoryMetrics(now pcommon.Timestamp, memoryStats *dtypes.MemoryStats) {
@@ -265,3 +273,15 @@ func (r *receiver) recordPidsMetrics(now pcommon.Timestamp, pidsStats *dtypes.Pi
 		}
 	}
 }
+
+func (r *receiver) recordBaseMetrics(now pcommon.Timestamp, base *types.ContainerJSONBase) error {
+	t, err := time.Parse(time.RFC3339, base.State.StartedAt)
+	if err != nil {
+		// value not available or invalid
+		return scrapererror.NewPartialScrapeError(fmt.Errorf("error retrieving container.uptime from Container.State.StartedAt: %w", err), 1)
+	}
+	if v := now.AsTime().Sub(t); v > 0 {
+		r.mb.RecordContainerUptimeDataPoint(now, v.Seconds())
+	}
+	return nil
+}

receiver/dockerstatsreceiver/internal/metadata/generated_metrics_test.go

@@ -17,9 +17,11 @@ import (
 	"testing"
 	"time"
 
+	"github.com/docker/docker/api/types"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.opentelemetry.io/collector/component/componenttest"
+	"go.opentelemetry.io/collector/pdata/pcommon"
 	"go.opentelemetry.io/collector/receiver/receivertest"
 	"go.opentelemetry.io/collector/receiver/scraperhelper"
 
@@ -96,6 +98,7 @@ var (
 		ContainerNetworkIoUsageTxPackets:           metricEnabled,
 		ContainerPidsCount:                         metricEnabled,
 		ContainerPidsLimit:                         metricEnabled,
+		ContainerUptime:                            metricEnabled,
 	}
 )
 
@@ -254,11 +257,56 @@ func TestScrapeV2(t *testing.T) {
 			assert.NoError(t, err)
 			assert.NoError(t, pmetrictest.CompareMetrics(expectedMetrics, actualMetrics,
 				pmetrictest.IgnoreMetricDataPointsOrder(),
-				pmetrictest.IgnoreResourceMetricsOrder(), pmetrictest.IgnoreStartTimestamp(), pmetrictest.IgnoreTimestamp()))
+				pmetrictest.IgnoreResourceMetricsOrder(),
+				pmetrictest.IgnoreStartTimestamp(),
+				pmetrictest.IgnoreTimestamp(),
+				pmetrictest.IgnoreMetricValues(
+					"container.uptime", // value depends on time.Now(), making it unpredictable as far as tests go
+				),
+			))
 		})
 	}
 }
 
+func TestRecordBaseMetrics(t *testing.T) {
+	cfg := createDefaultConfig().(*Config)
+	cfg.MetricsBuilderConfig.Metrics = metadata.MetricsConfig{
+		ContainerUptime: metricEnabled,
+	}
+	r := newReceiver(receivertest.NewNopCreateSettings(), cfg)
+	now := time.Now()
+	started := now.Add(-2 * time.Second).Format(time.RFC3339)
+
+	t.Run("ok", func(t *testing.T) {
+		err := r.recordBaseMetrics(
+			pcommon.NewTimestampFromTime(now),
+			&types.ContainerJSONBase{
+				State: &types.ContainerState{
+					StartedAt: started,
+				},
+			},
+		)
+		require.NoError(t, err)
+		m := r.mb.Emit().ResourceMetrics().At(0).ScopeMetrics().At(0).Metrics().At(0)
+		assert.Equal(t, "container.uptime", m.Name())
+		dp := m.Gauge().DataPoints()
+		assert.Equal(t, 1, dp.Len())
+		assert.Equal(t, 2, int(dp.At(0).DoubleValue()))
+	})
+
+	t.Run("error", func(t *testing.T) {
+		err := r.recordBaseMetrics(
+			pcommon.NewTimestampFromTime(now),
+			&types.ContainerJSONBase{
+				State: &types.ContainerState{
+					StartedAt: "bad date",
+				},
+			},
+		)
+		require.Error(t, err)
+	})
+}
+
 func dockerMockServer(urlToFile *map[string]string) (*httptest.Server, error) {
 	urlToFileContents := make(map[string][]byte, len(*urlToFile))
 	for urlPath, filePath := range *urlToFile {

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

@@ -360,6 +360,13 @@ resourceMetrics:
                   startTimeUnixNano: "1682426015940992000"
                   timeUnixNano: "1682426015943175000"
             unit: '{pids}'
+          - description: Time elapsed since container start time.
+            name: container.uptime
+            gauge:
+              dataPoints:
+                - asDouble: 0.0002888012543185477
+                  timeUnixNano: "1657771705535206000"
+            unit: 's'
         scope:
           name: otelcol/dockerstatsreceiver
           version: latest

receiver/dockerstatsreceiver/metadata.yaml

@@ -779,6 +779,13 @@ resourceMetrics:
                   timeUnixNano: "1683723817613281000"
               isMonotonic: true
             unit: '{packets}'
+          - description: Time elapsed since container start time.
+            name: container.uptime
+            gauge:
+              dataPoints:
+                - asDouble: 0.0002888012543185477
+                  timeUnixNano: "1657771705535206000"
+            unit: 's'
         scope:
           name: otelcol/dockerstatsreceiver
           version: latest

receiver/dockerstatsreceiver/receiver.go

@@ -412,6 +412,13 @@ resourceMetrics:
                   startTimeUnixNano: "1683723781127718000"
                   timeUnixNano: "1683723781130612000"
             unit: '{pids}'
+          - description: Time elapsed since container start time.
+            name: container.uptime
+            gauge:
+              dataPoints:
+                - asDouble: 0.0002888012543185477
+                  timeUnixNano: "1657771705535206000"
+            unit: 's'
         scope:
           name: otelcol/dockerstatsreceiver
           version: latest