[receiver/apache] Add opt-in migration to new metric and attribute names behind feature gates

.chloggen/fix_47327.yaml

@@ -0,0 +1,42 @@
+# 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: receiver/apache
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add an opt-in migration to new, more consistent metric and attribute names behind feature gates
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [47327]
+
+# (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 original metric and attribute names remain the default. Enable
+  `receiver.apache.enableNewFormatMetrics` to also emit the new names, and
+  additionally enable `receiver.apache.disableOldFormatMetrics` to emit only the
+  new names. See the receiver's README for the migration guide and full mapping.
+  Renamed metrics:
+    - `apache.current_connections` -> `apache.connection.active`
+    - `apache.connections.async` -> `apache.connections`
+    - `apache.requests` -> `apache.request.count`
+    - `apache.scoreboard` -> `apache.worker.status`
+    - `apache.workers` -> replaced by `apache.worker.active` and `apache.worker.idle`
+  Renamed attributes:
+    - `connection_state` -> `apache.connection.state`
+    - `state` (on the scoreboard metric) -> `apache.worker.state`
+    - `level` (on `apache.cpu.time`) -> `apache.process.level`
+    - `mode` (on `apache.cpu.time`) -> `cpu.mode`
+
+# 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: [user]

receiver/apachereceiver/README.md

@@ -47,3 +47,80 @@ The full list of settings exposed for this receiver are documented in [config.go
 ## Metrics
 
 Details about the metrics produced by this receiver can be found in [metadata.yaml](./metadata.yaml)
+
+## Metric and Attribute Name Migration
+
+The receiver's metric and attribute names are being migrated to a new, more
+consistent naming scheme (tracked in
+[#47327](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/47327)).
+Because this component is in beta, the change is being rolled out gradually,
+behind feature gates, so that existing dashboards, alerts, OTTL statements and
+routing rules keep working while you migrate.
+
+### Rollout
+
+Two feature gates control the migration:
+
+| Feature gate | Default | Effect when enabled |
+| --- | --- | --- |
+| `receiver.apache.enableNewFormatMetrics` | disabled | Emit the new metric/attribute names. On its own, the new names are emitted **alongside** the original ones. |
+| `receiver.apache.disableOldFormatMetrics` | disabled | Stop emitting the original metric/attribute names. Requires `receiver.apache.enableNewFormatMetrics` to also be enabled. |
+
+This gives three phases you can move through at your own pace:
+
+1. **Default (both gates disabled):** only the original names are emitted. A
+   warning is logged at startup pointing to this guide.
+2. **Transition (`enableNewFormatMetrics` only):** both the original and the new
+   names are emitted at the same time, so you can update your dashboards, alerts,
+   OTTL statements and routing to the new names without gaps.
+3. **New only (both gates enabled):** only the new names are emitted.
+
+Enable a gate with the `--feature-gates` flag, for example:
+
+```shell
+otelcol --feature-gates=receiver.apache.enableNewFormatMetrics
+# once everything has been migrated to the new names:
+otelcol --feature-gates=receiver.apache.enableNewFormatMetrics,receiver.apache.disableOldFormatMetrics
+```
+
+The gates start at `alpha` (disabled by default). Following the
+[collector's stability guidelines](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md),
+the new names will later become the default (`beta`), and eventually the old
+names and gates will be removed (`stable`).
+
+### What changed
+
+Renamed metrics:
+
+| Original name | New name |
+| --- | --- |
+| `apache.current_connections` | `apache.connection.active` |
+| `apache.connections.async` | `apache.connections` |
+| `apache.requests` | `apache.request.count` |
+| `apache.scoreboard` | `apache.worker.status` |
+| `apache.workers` | split into `apache.worker.active` (busy) and `apache.worker.idle` (idle) |
+
+Renamed attributes:
+
+| Metric | Original attribute | New attribute |
+| --- | --- | --- |
+| `apache.connections` (was `apache.connections.async`) | `connection_state` | `apache.connection.state` |
+| `apache.worker.status` (was `apache.scoreboard`) | `state` | `apache.worker.state` |
+| `apache.cpu.time` | `level` | `apache.process.level` |
+| `apache.cpu.time` | `mode` | `cpu.mode` |
+
+> [!NOTE]
+> The `apache.cpu.time` metric keeps its name; only its `level` and `mode`
+> attribute keys are renamed. The original `apache.workers` metric (busy/idle
+> counts) is replaced by the separate `apache.worker.active` and
+> `apache.worker.idle` metrics, which have no state attribute.
+
+### What to update
+
+Before enabling `receiver.apache.disableOldFormatMetrics`, review anything that
+references the original names, including:
+
+- Dashboards and visualizations.
+- Alerting and recording rules.
+- OTTL statements (e.g. in the `transform` or `filter` processors).
+- Routing and pipeline configuration that matches on metric or attribute names.

receiver/apachereceiver/documentation.md

@@ -12,6 +12,28 @@ metrics:
     enabled: false
 ```
 
+### apache.connection.active
+
+The number of active connections currently attached to the HTTP server.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| {connection} | Sum | Int | Cumulative | false | Development |
+
+### apache.connections
+
+The number of connections in different asynchronous states reported by Apache's server-status.
+
+| Unit | Metric Type | Value Type | Stability |
+| ---- | ----------- | ---------- | --------- |
+| {connection} | Gauge | Int | Development |
+
+#### Attributes
+
+| Name | Description | Values | Requirement Level | Semantic Convention |
+| ---- | ----------- | ------ | ----------------- | ------------------- |
+| apache.connection.state | The asynchronous connection state reported by Apache's server-status. | Str: ``writing``, ``keepalive``, ``closing`` | Recommended | - |
+
 ### apache.connections.async
 
 The number of connections in different asynchronous states reported by Apache's server-status.
@@ -81,6 +103,14 @@ The average server load during the last 5 minutes.
 | ---- | ----------- | ---------- | --------- |
 | % | Gauge | Double | Development |
 
+### apache.request.count
+
+The number of requests serviced by the HTTP server.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| {request} | Sum | Int | Cumulative | true | Development |
+
 ### apache.request.time
 
 Total time spent on handling requests.
@@ -129,6 +159,38 @@ The amount of time that the server has been running in seconds.
 | ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
 | s | Sum | Int | Cumulative | true | Development |
 
+### apache.worker.active
+
+The number of busy workers currently attached to the HTTP server.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| {worker} | Sum | Int | Cumulative | false | Development |
+
+### apache.worker.idle
+
+The number of idle workers currently attached to the HTTP server.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| {worker} | Sum | Int | Cumulative | false | Development |
+
+### apache.worker.status
+
+The number of workers in each state.
+
+The [apache scoreboard](https://metacpan.org/pod/Apache::Scoreboard#DESCRIPTION) is an encoded representation of the state of all the server's workers. This metric decodes the scoreboard and presents a count of workers in each state.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| {worker} | Sum | Int | Cumulative | false | Development |
+
+#### Attributes
+
+| Name | Description | Values | Requirement Level | Semantic Convention |
+| ---- | ----------- | ------ | ----------------- | ------------------- |
+| apache.worker.state | The state of a worker. | Str: ``open``, ``waiting``, ``starting``, ``reading``, ``sending``, ``keepalive``, ``dnslookup``, ``closing``, ``logging``, ``finishing``, ``idle_cleanup``, ``unknown`` | Recommended | - |
+
 ### apache.workers
 
 The number of workers currently attached to the HTTP server.
@@ -149,3 +211,14 @@ The number of workers currently attached to the HTTP server.
 | ---- | ----------- | ------ | ------- | ------------------- | --------- |
 | apache.server.name | The name of the Apache HTTP server. | Any Str | true | - | - |
 | apache.server.port | The port of the Apache HTTP server. | Any Str | true | - | - |
+
+## Feature Gates
+
+This component has the following feature gates:
+
+| Feature Gate | Stage | Description | From Version | To Version | Reference |
+| ------------ | ----- | ----------- | ------------ | ---------- | --------- |
+| `receiver.apache.disableOldFormatMetrics` | alpha | When enabled, the receiver no longer emits the original metric and attribute names (e.g. apache.requests, apache.scoreboard, and the mode/level/state attributes). Requires receiver.apache.enableNewFormatMetrics to also be enabled. | v0.157.0 | N/A | [Link](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/47327) |
+| `receiver.apache.enableNewFormatMetrics` | alpha | When enabled, the receiver emits the new, consistently named metrics and attributes (e.g. apache.request.count, apache.worker.status, cpu.mode) alongside the original ones. See the migration guide linked from the component README for the full mapping. | v0.157.0 | N/A | [Link](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/47327) |
+
+For more information about feature gates, see the [Feature Gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md) documentation.

receiver/apachereceiver/factory.go

@@ -5,6 +5,7 @@ package apachereceiver // import "github.com/open-telemetry/opentelemetry-collec
 
 import (
 	"context"
+	"errors"
 	"net/url"
 	"time"
 
@@ -74,6 +75,12 @@ func createMetricsReceiver(
 	consumer consumer.Metrics,
 ) (receiver.Metrics, error) {
 	cfg := rConf.(*Config)
+
+	if metadata.ReceiverApacheDisableOldFormatMetricsFeatureGate.IsEnabled() &&
+		!metadata.ReceiverApacheEnableNewFormatMetricsFeatureGate.IsEnabled() {
+		return nil, errors.New("the receiver.apache.disableOldFormatMetrics feature gate requires receiver.apache.enableNewFormatMetrics to also be enabled")
+	}
+
 	serverName, port, err := parseResourceAttributes(cfg.Endpoint)
 	if err != nil {
 		return nil, err

receiver/apachereceiver/factory_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/stretchr/testify/require"
 	"go.opentelemetry.io/collector/confmap/xconfmap"
 	"go.opentelemetry.io/collector/consumer/consumertest"
+	"go.opentelemetry.io/collector/featuregate"
 	"go.opentelemetry.io/collector/receiver/receivertest"
 	"go.opentelemetry.io/collector/scraper/scraperhelper"
 
@@ -43,6 +44,25 @@ func TestCreateMetrics(t *testing.T) {
 	require.NotNil(t, metricsReceiver)
 }
 
+func TestCreateMetricsRejectsDisableOldWithoutEnableNew(t *testing.T) {
+	require.NoError(t, featuregate.GlobalRegistry().Set(metadata.ReceiverApacheDisableOldFormatMetricsFeatureGate.ID(), true))
+	defer func() {
+		require.NoError(t, featuregate.GlobalRegistry().Set(metadata.ReceiverApacheDisableOldFormatMetricsFeatureGate.ID(), false))
+	}()
+
+	_, err := NewFactory().CreateMetrics(
+		t.Context(),
+		receivertest.NewNopSettings(metadata.Type),
+		&Config{
+			ControllerConfig: scraperhelper.ControllerConfig{
+				CollectionInterval: 10 * time.Second,
+			},
+		},
+		consumertest.NewNop(),
+	)
+	require.ErrorContains(t, err, "receiver.apache.disableOldFormatMetrics feature gate requires receiver.apache.enableNewFormatMetrics")
+}
+
 func TestPortValidate(t *testing.T) {
 	testCases := []struct {
 		desc         string

receiver/apachereceiver/go.mod

@@ -16,6 +16,7 @@ require (
 	go.opentelemetry.io/collector/confmap/xconfmap v0.156.1-0.20260709230849-fe96e04e8916
 	go.opentelemetry.io/collector/consumer v1.62.1-0.20260709230849-fe96e04e8916
 	go.opentelemetry.io/collector/consumer/consumertest v0.156.1-0.20260709230849-fe96e04e8916
+	go.opentelemetry.io/collector/featuregate v1.62.1-0.20260709230849-fe96e04e8916
 	go.opentelemetry.io/collector/filter v0.156.1-0.20260709230849-fe96e04e8916
 	go.opentelemetry.io/collector/pdata v1.62.1-0.20260709230849-fe96e04e8916
 	go.opentelemetry.io/collector/receiver v1.62.1-0.20260709230849-fe96e04e8916
@@ -99,7 +100,6 @@ require (
 	go.opentelemetry.io/collector/consumer/xconsumer v0.156.1-0.20260709230849-fe96e04e8916 // indirect
 	go.opentelemetry.io/collector/extension/extensionauth v1.62.1-0.20260709230849-fe96e04e8916 // indirect
 	go.opentelemetry.io/collector/extension/extensionmiddleware v0.156.1-0.20260709230849-fe96e04e8916 // indirect
-	go.opentelemetry.io/collector/featuregate v1.62.1-0.20260709230849-fe96e04e8916 // indirect
 	go.opentelemetry.io/collector/internal/componentalias v0.156.1-0.20260709230849-fe96e04e8916 // indirect
 	go.opentelemetry.io/collector/pdata/pprofile v0.156.1-0.20260709230849-fe96e04e8916 // indirect
 	go.opentelemetry.io/collector/pdata/xpdata v0.156.1-0.20260709230849-fe96e04e8916 // indirect