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

[singhvibhanshu]

Description

This PR offers an opt-in, non-breaking migration to new, more consistent metric and attribute names for the Apache receiver.
NOTE: It's a naming consistency cleanup, not conformance to a published Apache semantic conventions (as it doesn't' exist as of today).

Metrics are renamed as follows (and are emitted only when enableNewFormatMetrics is on):

• apache.current_connections -> apache.connection.active
• apache.connections.async -> apache.connection.status
• apache.requests -> apache.request.count
• apache.scoreboard -> apache.worker.status
• apache.workers -> split into apache.worker.active (busy) + apache.worker.idle(idle)

Attributes are renamed as:

• connection_state -> apache.connection.state
• scoreboard_state -> apache.worker.state
• level -> apache.process.level
• mode -> cpu.mode
• workers_state -> removed (bec old apache.workers split into attribute-less metrics)

Link to tracking issue

Fixes #47327

Testing

Added.

Documentation

Added.

Authorship

• I, a human, wrote this pull request description myself.

[singhvibhanshu]

Hi there!
This PR is now ready to get reviewed.
@edmocosta, @colelaven, @ishleenk17, kindly take a look at it when you get a chance.
Thank you!

[singhvibhanshu]

This PR got merge conflicts.
I'll fix them soon as well as address the feedback too.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 14 days.

[edmocosta]

Let's please close #47367 (review) before merging.

[singhvibhanshu]

Understood, @edmocosta.

But before proceeding let me confirm everything one more time.

Do you mean introducing feature gates here?

I have a few questions to ask:

1. We need to keep old metric names as default behavior?
2. When the feature gate is disabled (which is by default is disabled), we will emit old metrics but log a WARNING MESSAGE now?
3. When the gate is enabled, we need to emit new metrics?

[edmocosta]

Do you mean introducing feature gates here?

Normally yes. There are other strategies components can take like emitting both metrics old and new during the transition time, but that's up to the code-owners @colelaven & @ishleenk17 to decide, we just need to ensure it's not breaking existing users independently of the strategy.

We need to keep old metric names as default behavior?

Yes, the old metrics and attributes names should be the default ones while the FF is still in alpha. The new names should be opt-in on this phase.

When the feature gate is disabled (which is by default is disabled), we will emit old metrics but log a WARNING MESSAGE now?

The warning message should be logged when the component starts and the FG is disable (default). It should link to the migration's docs, explaining how users can make this transition, what they should look at (OTTL statements, dashboards, alerts, routing, etc), and what exactly changed.

When the gate is enabled, we need to emit new metrics?

Yes. Please also take into consideration the FG lifecycle described on the guidelines, and the versions timline recommendations:

the option MUST be kept for at least N+1 version and MAY be hidden behind a feature gate in N+2
the option and the WARN level message MUST NOT be removed earlier than N+2 or 6 months, whichever comes later

[ChrsMark]

FWIWI, here is the RFC that describes the migration mechanism for when there are breaking changes and we aim to move to stable semconv: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/rfcs/semconv-feature-gates.md

I would suggest that such discussions, specially when breaking changes are involved, should happen first at the respective issue (#47327) and involve approvers/maintainers for sponsoring these breaking changes if there is a specific plan.

@singhvibhanshu few questions from side that should be discussed/answered back at the issue. Is there a specific goal for this change? Have code-owners agreed on this change and what is the specific goal? This kind of updates/changes are not trivial since they introduce breaking changes on components that are already in use and even if the stability level of the component is not at stable we should be careful and with specific reasoning on how and when we apply them.
Also the PR's description should list the specific changes the PR suggests (I had to look into the changelog to find them). We need to track which of those are actually breaking and if they affect attributes or metrics' names, or both. Then code-owners should work on deciding the migration plan for those and consult maintainers/approvers on the impact of these breaking change and how it should best be handled. An example of such approach can be found at #43869 or #44589.

[singhvibhanshu]

I would suggest that such discussions, specially when breaking changes are involved, should happen first at the respective issue (#47327) and involve approvers/maintainers for sponsoring these breaking changes if there is a specific plan.

Understood.

Is there a specific goal for this change? Have code-owners agreed on this change and what is the specific goal?

The goal of this issue is to align the metric names with the established semantic conventions. Regarding the code owner approval, Cole has already approved this PR. If anything seems off to him, I think he would let me know.

Also the PR's description should list the specific changes the PR suggests (I had to look into the changelog to find them).

Duly noted. I'll keep in mind that this won't happen again. Also, I'm updating the description of this PR.

[ChrsMark]

Is there a specific goal for this change? Have code-owners agreed on this change and what is the specific goal?

The goal of this issue is to align the metric names with the established semantic conventions. Regarding the code owner approval, Cole has already approved this PR. If anything seems off to him, I think he would let me know.

Something that needs to be clarified is the level of confidence for these "established" semantic conventions and what are the plans of stabilising those. Ideally we want to have breaking changes only once for components, so we should ensure that semantic conventions we move to are actually there to stay and won't change again. I would suggest we move the discussion back to the issue to work on the plan first before doing any implementation.

[colelaven]

Apologies for my original oversight when approving this PR, I agree with the above concerns about this breaking change. I'm marking as changes requested for now and am moving discussion to #47327.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 14 days.

[thompson-tomo]

Suggested change

	apache.connections: # (new)
	apache.connection.status: # (new)

As per semconv guidance.

[singhvibhanshu]

I donot agree with this. Please see: #47367 (comment)

[thompson-tomo]

Take a look at https://opentelemetry.io/docs/specs/semconv/how-to-write-conventions/status-metrics/, the key thing is the presence of the state attribute.

It also becomes awkward that we have a connection namespace however the count of connections based on state is not in that namespace.

[singhvibhanshu]

Agreed, thanks for the reference. Let's not proceed further and wait for the code-owner to have a look too.
@colelaven, please take a look.

[colelaven]

Thanks for the reference Thompson, I am in favor of renaming back to apache.connection.status after reading that document 👍

[opentelemetry-pr-dashboard]

Pull request dashboard status

Status last refreshed: 2026-07-27 13:30:13 UTC.

• Waiting on: Author
• Next step: Move out of draft to request review.

This automated status or its linked feedback items may be incorrect. If something looks wrong, please report it with the result you expected.

[singhvibhanshu]

/rerun

[singhvibhanshu]

@thompson-tomo, @colelaven
This PR is marked as a draft but feel free to give a look. I've addressed your feedbacks.
Thank you in advance.