[receiver/apache]: Add optional apache.server.name resource attribute (…

…#14926)

* feat: add feature gate with default path

.chloggen/apache-server-name-feature-gate.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: apachereceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Extract server name as resource attribute
+
+# One or more tracking issues related to the change
+issues: [14791]
+
+# (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 feature is enabled through a feature gate and will be enabled by default in v0.65.

receiver/apachereceiver/README.md

@@ -41,3 +41,17 @@ Details about the metrics produced by this receiver can be found in [metadata.ya
 
 [beta]: https://github.com/open-telemetry/opentelemetry-collector#beta
 [contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
+
+## Feature gate configurations
+
+See the [Collector feature gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md#collector-feature-gates) for an overview of feature gates in the collector.
+
+**ALPHA**: `receiver.apache.emitServerNameAsResourceAttribute`
+
+The feature gate `receiver.apache.emitServerNameAsResourceAttribute` once enabled starts emitting the metrics with a resource attribute `apache.server.name`. When the feature gate is disabled, the metrics are emitted with a `server_name` metric-level attribute instead.
+
+This is considered a breaking change for existing users of this receiver, and it is recommended to migrate to the new implementation when possible. Any new users planning to adopt this receiver should enable this feature gate to avoid having to migrate any visualisations or alerts.
+
+This feature gate will eventually be enabled by default, and eventually the old implementation will be removed. It aims
+to give users time to migrate to the new implementation. The target release for this featuregate to be enabled by default
+is 0.66.0.

receiver/apachereceiver/documentation.md

@@ -8,18 +8,18 @@ These are the metrics available for this scraper.
 
 | Name | Description | Unit | Type | Attributes |
 | ---- | ----------- | ---- | ---- | ---------- |
-| **apache.cpu.load** | Current load of the CPU. | % | Gauge(Double) | <ul> <li>server_name</li> </ul> |
-| **apache.cpu.time** | Jiffs used by processes of given category. | {jiff} | Sum(Double) | <ul> <li>server_name</li> <li>cpu_level</li> <li>cpu_mode</li> </ul> |
-| **apache.current_connections** | The number of active connections currently attached to the HTTP server. | {connections} | Sum(Int) | <ul> <li>server_name</li> </ul> |
-| **apache.load.1** | The average server load during the last minute. | % | Gauge(Double) | <ul> <li>server_name</li> </ul> |
-| **apache.load.15** | The average server load during the last 15 minutes. | % | Gauge(Double) | <ul> <li>server_name</li> </ul> |
-| **apache.load.5** | The average server load during the last 5 minutes. | % | Gauge(Double) | <ul> <li>server_name</li> </ul> |
-| **apache.request.time** | Total time spent on handling requests. | ms | Sum(Int) | <ul> <li>server_name</li> </ul> |
-| **apache.requests** | The number of requests serviced by the HTTP server per second. | {requests} | Sum(Int) | <ul> <li>server_name</li> </ul> |
-| **apache.scoreboard** | The number of workers in each state. The apache scoreboard 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. Additional details can be found [here](https://metacpan.org/pod/Apache::Scoreboard#DESCRIPTION). | {workers} | Sum(Int) | <ul> <li>server_name</li> <li>scoreboard_state</li> </ul> |
-| **apache.traffic** | Total HTTP server traffic. | By | Sum(Int) | <ul> <li>server_name</li> </ul> |
-| **apache.uptime** | The amount of time that the server has been running in seconds. | s | Sum(Int) | <ul> <li>server_name</li> </ul> |
-| **apache.workers** | The number of workers currently attached to the HTTP server. | {workers} | Sum(Int) | <ul> <li>server_name</li> <li>workers_state</li> </ul> |
+| **apache.cpu.load** | Current load of the CPU. | % | Gauge(Double) | <ul> </ul> |
+| **apache.cpu.time** | Jiffs used by processes of given category. | {jiff} | Sum(Double) | <ul> <li>cpu_level</li> <li>cpu_mode</li> </ul> |
+| **apache.current_connections** | The number of active connections currently attached to the HTTP server. | {connections} | Sum(Int) | <ul> </ul> |
+| **apache.load.1** | The average server load during the last minute. | % | Gauge(Double) | <ul> </ul> |
+| **apache.load.15** | The average server load during the last 15 minutes. | % | Gauge(Double) | <ul> </ul> |
+| **apache.load.5** | The average server load during the last 5 minutes. | % | Gauge(Double) | <ul> </ul> |
+| **apache.request.time** | Total time spent on handling requests. | ms | Sum(Int) | <ul> </ul> |
+| **apache.requests** | The number of requests serviced by the HTTP server per second. | {requests} | Sum(Int) | <ul> </ul> |
+| **apache.scoreboard** | The number of workers in each state. The apache scoreboard 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. Additional details can be found [here](https://metacpan.org/pod/Apache::Scoreboard#DESCRIPTION). | {workers} | Sum(Int) | <ul> <li>scoreboard_state</li> </ul> |
+| **apache.traffic** | Total HTTP server traffic. | By | Sum(Int) | <ul> </ul> |
+| **apache.uptime** | The amount of time that the server has been running in seconds. | s | Sum(Int) | <ul> </ul> |
+| **apache.workers** | The number of workers currently attached to the HTTP server. | {workers} | Sum(Int) | <ul> <li>workers_state</li> </ul> |
 
 **Highlighted metrics** are emitted by default. Other metrics are optional and not emitted by default.
 Any metric can be enabled or disabled with the following scraper configuration:
@@ -30,12 +30,17 @@ metrics:
     enabled: <true|false>
 ```
 
+## Resource attributes
+
+| Name | Description | Type |
+| ---- | ----------- | ---- |
+| apache.server.name | The name of the Apache HTTP server. | Str |
+
 ## Metric attributes
 
 | Name | Description | Values |
 | ---- | ----------- | ------ |
 | cpu_level (level) | Level of processes. | self, children |
 | cpu_mode (mode) | Mode of processes. | system, user |
 | scoreboard_state (state) | The state of a connection. | open, waiting, starting, reading, sending, keepalive, dnslookup, closing, logging, finishing, idle_cleanup, unknown |
-| server_name | The name of the Apache HTTP server. |  |
 | workers_state (state) | The state of workers. | busy, idle |