Merge branch 'main' into codeboten/mark-semconv-deprecated

Author: codeboten

.chloggen/pipeline-component-metrics.yaml

@@ -0,0 +1,32 @@
+# 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. otlpreceiver)
+component: service
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add item count metrics defined in Pipeline Component Telemetry RFC
+
+# One or more tracking issues or pull requests related to the change
+issues: [12812]
+
+# (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: |
+  See [Pipeline Component Telemetry RFC](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/rfcs/component-universal-telemetry.md) for more details:
+    - `otelcol.receiver.produced.items`
+    - `otelcol.processor.consumed.items`
+    - `otelcol.processor.produced.items`
+    - `otelcol.connector.consumed.items`
+    - `otelcol.connector.produced.items`
+    - `otelcol.exporter.consumed.items`
+
+# 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: []

cmd/mdatagen/internal/metric.go

@@ -59,6 +59,9 @@ type Metric struct {
 
 	// Attributes is the list of attributes that the metric emits.
 	Attributes []AttributeName `mapstructure:"attributes"`
+
+	// Override the default prefix for the metric name.
+	Prefix string `mapstructure:"prefix"`
 }
 
 type Stability struct {

cmd/mdatagen/internal/templates/documentation.md.tmpl

@@ -38,7 +38,7 @@
 {{- $metricName := . }}
 {{- $metric := $metricName | telemetryInfo -}}
 
-### otelcol_{{ $metricName }}
+### {{ if $metric.Prefix -}}{{ $metric.Prefix }}{{- else -}}otelcol_{{- end -}}{{ $metricName }}
 
 {{ $metric.Description }}{{ $metric.Stability }}
 

cmd/mdatagen/internal/templates/telemetry.go.tmpl

@@ -136,7 +136,11 @@ func NewTelemetryBuilder(settings component.TelemetrySettings, options ...Teleme
 
     {{- range $name, $metric := .Telemetry.Metrics }}
     builder.{{ $name.Render }}, err = builder.meter.{{ $metric.Data.Instrument }}(
+        {{ if $metric.Prefix -}}
+        "{{ $metric.Prefix }}{{ $name }}",
+        {{ else -}}
         "otelcol_{{ $name }}",
+        {{ end -}}
         metric.WithDescription("{{ $metric.Description }}{{ $metric.Stability }}"),
         metric.WithUnit("{{ $metric.Unit }}"),
         {{ if eq $metric.Data.Type "Histogram" -}}

cmd/mdatagen/internal/templates/telemetrytest.go.tmpl

@@ -32,7 +32,11 @@ return set
 
 func AssertEqual{{ $name.Render }}(t *testing.T, tt *componenttest.Telemetry, dps []metricdata.{{- if eq $metric.Data.Type "Histogram" }} {{$metric.Data.Type}} {{- end }}DataPoint[{{ $metric.Data.BasicType }}], opts ...metricdatatest.Option) {
 	want := metricdata.Metrics{
+		{{ if $metric.Prefix -}}
+		Name:        "{{ $metric.Prefix }}{{ $name }}",
+		{{ else -}}
 		Name:        "otelcol_{{ $name }}",
+		{{ end -}}
 		Description: "{{ $metric.Description }}{{ $metric.Stability }}",
 		Unit:        "{{ $metric.Unit }}",
 		Data:        metricdata.{{ $metric.Data.Type }}[{{ $metric.Data.BasicType }}]{
@@ -45,7 +49,11 @@ func AssertEqual{{ $name.Render }}(t *testing.T, tt *componenttest.Telemetry, dp
 			DataPoints: dps,
 		},
 	}
+	{{ if $metric.Prefix -}}
+	got, err := tt.GetMetric("{{ $metric.Prefix }}{{ $name }}")
+	{{ else -}}
 	got, err := tt.GetMetric("otelcol_{{ $name }}")
+	{{ end -}}
 	require.NoError(t, err)
 	metricdatatest.AssertEqual(t, want, got, opts...)
 }

docs/component-stability.md

@@ -89,13 +89,14 @@ components apply to stable when it comes to configuration changes.
 
 #### Testing requirements
 
-Stable components MUST have a test coverage that exceeds the highest between 80% coverage and the
-repository-wide minimum. The unit test suite SHOULD cover all configuration options. The coverage
-MUST be shown as part of the component documentation.
-
-Stable components SHOULD provide at least one example configuration that works for each stable
-signal, and have at least one lifecycle test that tests the component's initialization with a valid
-configuration. Said configuration should also be shown in the component documentation.
+Stable components MUST have a comprehensive test suite. In particular they MUST have:
+1. A **test coverage** that exceeds the highest between 80% coverage and the repository-wide
+minimum. The unit test suite SHOULD cover all configuration options. The coverage MUST be shown as
+part of the component documentation.
+2. At least one **lifecycle test** that tests the component's initialization with a valid
+   configuration and ensures proper context propagation if applicable.
+3. At least one **benchmark test** for each stable signal. The component's documentation MUST
+   include a link to the latest run of benchmark results.
 
 #### Documentation requirements
 
@@ -108,6 +109,9 @@ Stable components should have a complete set of documentation, including:
   what they provide.
 - Compatibility guarantees with external dependencies including the versions it is compatible with
   and under what conditions.
+- Guidance related to the component's usage in production environments, including how to scale a deployment of this component properly if it needs special considerations.
+- If stateful, how to configure the component to use persistent storage and how to gracefully
+  shutdown and restart the component.
 - Warnings about known limitations and ways to misuse the component.
 
 Receivers that produce a fixed set of telemetry should document the telemetry they produce,
@@ -300,6 +304,7 @@ To graduate any signal from alpha to beta on a component:
 
 To graduate any signal from beta to stable on a component:
 1. The component MUST have at least three active code owners.
+2. The component benchmark results MUST have been updated within the last 30 days and published in the component's README.
 3. Within the 60 days prior to the graduation request, the code owners MUST have reviewed and
    replied to at least 80% of the issues and pull requests opened against the component. This
    excludes general PRs or issues that are not specific to the component itself (e.g. repo-wide API

service/documentation.md

@@ -6,6 +6,30 @@
 
 The following telemetry is emitted by this component.
 
+### otelcol.connector.consumed.items
+
+Number of items passed to the connector.
+
+| Unit | Metric Type | Value Type | Monotonic |
+| ---- | ----------- | ---------- | --------- |
+| {item} | Sum | Int | true |
+
+### otelcol.connector.produced.items
+
+Number of items emitted from the connector.
+
+| Unit | Metric Type | Value Type | Monotonic |
+| ---- | ----------- | ---------- | --------- |
+| {item} | Sum | Int | true |
+
+### otelcol.exporter.consumed.items
+
+Number of items passed to the exporter.
+
+| Unit | Metric Type | Value Type | Monotonic |
+| ---- | ----------- | ---------- | --------- |
+| {item} | Sum | Int | true |
+
 ### otelcol_process_cpu_seconds
 
 Total CPU user and system time in seconds [alpha]
@@ -53,3 +77,27 @@ Uptime of the process [alpha]
 | Unit | Metric Type | Value Type | Monotonic |
 | ---- | ----------- | ---------- | --------- |
 | s | Sum | Double | true |
+
+### otelcol.processor.consumed.items
+
+Number of items passed to the processor.
+
+| Unit | Metric Type | Value Type | Monotonic |
+| ---- | ----------- | ---------- | --------- |
+| {item} | Sum | Int | true |
+
+### otelcol.processor.produced.items
+
+Number of items emitted from the processor.
+
+| Unit | Metric Type | Value Type | Monotonic |
+| ---- | ----------- | ---------- | --------- |
+| {item} | Sum | Int | true |
+
+### otelcol.receiver.produced.items
+
+Number of items emitted from the receiver.
+
+| Unit | Metric Type | Value Type | Monotonic |
+| ---- | ----------- | ---------- | --------- |
+| {item} | Sum | Int | true |