[exporter/splunkhec] Define heartbeat metrics in metadata.yaml

.chloggen/splunkhec-telemetry-metadata.yaml

@@ -0,0 +1,31 @@
+# Use this changelog template to create an entry for release notes.
+
+# 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. receiver/filelog)
+component: exporter/splunk_hec
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Define the exporter's heartbeat metrics in metadata.yaml and generate them via mdatagen.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [49009]
+
+# (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: |
+  The `otelcol_exporter_splunkhec_heartbeats_sent` and `otelcol_exporter_splunkhec_heartbeats_failed`
+  metrics are now defined in `metadata.yaml`. This is a no-op for users: the emitted metric names,
+  and the existing `telemetry.enabled`, `telemetry.override_metrics_names`, and
+  `telemetry.extra_attributes` options, are unchanged.
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

exporter/splunkhecexporter/client.go

@@ -62,6 +62,7 @@ type client struct {
 	bufferPool        bufferPool
 	exporterName      string
 	meter             metric.Meter
+	telemetryBuilder  *metadata.TelemetryBuilder
 }
 
 func newClient(set exporter.Settings, cfg *Config, maxContentLength uint) *client {
@@ -746,6 +747,9 @@ func (c *client) stop(context.Context) error {
 	if c.heartbeater != nil {
 		c.heartbeater.shutdown()
 	}
+	if c.telemetryBuilder != nil {
+		c.telemetryBuilder.Shutdown()
+	}
 	return nil
 }
 
@@ -764,7 +768,12 @@ func (c *client) start(ctx context.Context, host component.Host) (err error) {
 	}
 	url, _ := c.config.getURL()
 	c.hecWorker = &defaultHecWorker{url, httpClient, buildHTTPHeaders(c.config, c.buildInfo), c.logger}
-	c.heartbeater = newHeartbeater(c.config, c.buildInfo, getPushLogFn(c), c.meter)
+	telemetryBuilder, tbErr := metadata.NewTelemetryBuilder(c.telemetrySettings)
+	if tbErr != nil {
+		return tbErr
+	}
+	c.telemetryBuilder = telemetryBuilder
+	c.heartbeater = newHeartbeater(c.config, c.buildInfo, getPushLogFn(c), c.telemetryBuilder, c.meter)
 	if c.config.Heartbeat.Startup {
 		if err := c.heartbeater.sendHeartbeat(c.config, c.buildInfo, getPushLogFn(c)); err != nil {
 			return fmt.Errorf("%s: heartbeat on startup failed: %w", c.exporterName, err)

exporter/splunkhecexporter/documentation.md

@@ -0,0 +1,23 @@
+[comment]: <> (Code generated by mdatagen. DO NOT EDIT.)
+
+# splunk_hec
+
+## Internal Telemetry
+
+The following telemetry is emitted by this component.
+
+### otelcol_exporter_splunkhec_heartbeats_failed
+
+Number of heartbeats failed by the Splunk HEC exporter.
+
+| Unit | Metric Type | Value Type | Monotonic | Stability |
+| ---- | ----------- | ---------- | --------- | --------- |
+| 1 | Sum | Int | true | Development |
+
+### otelcol_exporter_splunkhec_heartbeats_sent
+
+Number of heartbeats sent by the Splunk HEC exporter.
+
+| Unit | Metric Type | Value Type | Monotonic | Stability |
+| ---- | ----------- | ---------- | --------- | --------- |
+| 1 | Sum | Int | true | Development |

exporter/splunkhecexporter/heartbeat.go

@@ -15,6 +15,7 @@ import (
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/metric"
 
+	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/splunkhecexporter/internal/metadata"
 	translator "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/translator/splunk"
 )
 
@@ -35,7 +36,23 @@ func getMetricsName(overrides map[string]string, metricName string) string {
 	return metricName
 }
 
-func newHeartbeater(config *Config, buildInfo component.BuildInfo, pushLogFn func(ctx context.Context, ld plog.Logs) error, meter metric.Meter) *heartbeater {
+// heartbeatCounter returns the counter defined in metadata.yaml unless the user
+// configured a custom name for it through telemetry.override_metrics_names, in
+// which case a counter with the overridden name is created on the meter. The
+// override mechanism is retained for backwards compatibility and is expected to
+// be removed together with telemetry.enabled.
+func heartbeatCounter(meter metric.Meter, defaultCounter metric.Int64Counter, overrides map[string]string, defaultName, description string) (metric.Int64Counter, error) {
+	if name := getMetricsName(overrides, defaultName); name != defaultName {
+		return meter.Int64Counter(
+			name,
+			metric.WithDescription(description),
+			metric.WithUnit("1"),
+		)
+	}
+	return defaultCounter, nil
+}
+
+func newHeartbeater(config *Config, buildInfo component.BuildInfo, pushLogFn func(ctx context.Context, ld plog.Logs) error, telemetryBuilder *metadata.TelemetryBuilder, meter metric.Meter) *heartbeater {
 	interval := config.Heartbeat.Interval
 	if interval == 0 {
 		return nil
@@ -52,20 +69,12 @@ func newHeartbeater(config *Config, buildInfo component.BuildInfo, pushLogFn fun
 		}
 		attrs = attribute.NewSet(tags...)
 		var err error
-		heartbeatsSent, err = meter.Int64Counter(
-			getMetricsName(overrides, defaultHBSentMetricsName),
-			metric.WithDescription("number of heartbeats sent"),
-			metric.WithUnit("1"),
-		)
+		heartbeatsSent, err = heartbeatCounter(meter, telemetryBuilder.ExporterSplunkhecHeartbeatsSent, overrides, defaultHBSentMetricsName, "number of heartbeats sent")
 		if err != nil {
 			return nil
 		}
 
-		heartbeatsFailed, err = meter.Int64Counter(
-			getMetricsName(overrides, defaultHBFailedMetricsName),
-			metric.WithDescription("number of heartbeats failed"),
-			metric.WithUnit("1"),
-		)
+		heartbeatsFailed, err = heartbeatCounter(meter, telemetryBuilder.ExporterSplunkhecHeartbeatsFailed, overrides, defaultHBFailedMetricsName, "number of heartbeats failed")
 		if err != nil {
 			return nil
 		}

exporter/splunkhecexporter/heartbeat_test.go

@@ -17,6 +17,8 @@ import (
 	metricnoop "go.opentelemetry.io/otel/metric/noop"
 	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
 	"go.opentelemetry.io/otel/sdk/metric/metricdata"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/splunkhecexporter/internal/metadata"
 )
 
 const (
@@ -41,7 +43,9 @@ func createTestConfig(metricsOverrides map[string]string, enableMetrics bool) *C
 
 func initHeartbeater(t *testing.T, metricsOverrides map[string]string, enableMetrics bool, consumeFn func(ctx context.Context, ld plog.Logs) error, mp *sdkmetric.MeterProvider) {
 	config := createTestConfig(metricsOverrides, enableMetrics)
-	hbter := newHeartbeater(config, component.NewDefaultBuildInfo(), consumeFn, mp.Meter("test"))
+	tb, err := metadata.NewTelemetryBuilder(component.TelemetrySettings{MeterProvider: mp})
+	require.NoError(t, err)
+	hbter := newHeartbeater(config, component.NewDefaultBuildInfo(), consumeFn, tb, mp.Meter("test"))
 	t.Cleanup(func() {
 		hbter.shutdown()
 	})
@@ -85,9 +89,11 @@ func getAttributes(reader *sdkmetric.ManualReader, name string) ([]attribute.Set
 func Test_newHeartbeater_disabled(t *testing.T) {
 	config := createTestConfig(map[string]string{}, false)
 	config.Heartbeat.Interval = 0
+	tb, err := metadata.NewTelemetryBuilder(component.TelemetrySettings{MeterProvider: metricnoop.NewMeterProvider()})
+	require.NoError(t, err)
 	hb := newHeartbeater(config, component.NewDefaultBuildInfo(), func(_ context.Context, _ plog.Logs) error {
 		return nil
-	}, metricnoop.NewMeterProvider().Meter("test"))
+	}, tb, metricnoop.NewMeterProvider().Meter("test"))
 	assert.Nil(t, hb)
 }
 
@@ -110,6 +116,11 @@ func Test_Heartbeat_success(t *testing.T) {
 			metricsOverrides: map[string]string{},
 			enableMetrics:    false,
 		},
+		{
+			// No overrides: the metric defined in metadata.yaml is used.
+			metricsOverrides: map[string]string{},
+			enableMetrics:    true,
+		},
 	}
 
 	for _, tt := range tests {

exporter/splunkhecexporter/metadata.yaml

@@ -9,6 +9,26 @@ status:
   distributions: [contrib]
   codeowners:
     active: [atoulme, dmitryax]
+
+telemetry:
+  metrics:
+    exporter_splunkhec_heartbeats_failed:
+      enabled: true
+      stability: development
+      description: Number of heartbeats failed by the Splunk HEC exporter.
+      unit: "1"
+      sum:
+        value_type: int
+        monotonic: true
+    exporter_splunkhec_heartbeats_sent:
+      enabled: true
+      stability: development
+      description: Number of heartbeats sent by the Splunk HEC exporter.
+      unit: "1"
+      sum:
+        value_type: int
+        monotonic: true
+
 tests:
   config:
     token: "my_fake_token"