feat: preserve metric suffixes in OpenMetrics 2.0

[arnabnandy7]

Summary

Add an opt-in OpenMetrics 2.0 compatibility setting for applications migrating from the existing client_java naming behavior.

• Add io.prometheus.openmetrics2.suffixes.
• Keep suffixes=false as the default so OM2 preserves names exactly as registered.
• With suffixes=true, append missing unit suffixes and _total for counters.
• Avoid duplicating suffixes already present in metric names.
• Apply the selected naming behavior consistently to metadata and samples.
• Document the compatibility setting and migration path.

Fixes #2518.

Why

OpenMetrics 2.0 uses a "name in, name out" model. For example:

Counter.builder()
    .name("requests")
    .unit(Unit.BYTES)
    .build();

OM2 exposes this as requests by default. Existing client_java applications may rely on the OM1-style exposition name requests_bytes_total, so switching formats can otherwise rename series and affect queries, alerts, recording rules, and dashboards.

Applications that need a gradual migration can temporarily enable compatibility naming:

io.prometheus.openmetrics2.suffixes=true

This exposes requests_bytes_total while producers and downstream consumers migrate. Once registrations use the intended names explicitly, compatibility mode can be disabled without changing the exposed series.

Implementation

When compatibility naming is enabled, the writer reuses MetricMetadata.expositionBaseName, which contains the normalized unit suffix and preserves explicitly provided suffixes. Counter names receive _total only when it is missing.

The existing OpenMetrics 1.0 summary-writing flow is reused with the selected metric name so summary metadata and samples follow the same configuration.

Validation

All current GitHub Actions checks pass, including build, lint, API diff, Java compatibility, integration, native, and acceptance tests.

[zeitlinger]

Let's discuss the feature in #2518 first.

[github-actions]

⚠️ API changes detected — maintainer review required

This PR modifies the published API diff for the following module(s):

• prometheus-metrics-config

Please review the changes in docs/apidiffs/current_vs_latest/ carefully before approving.

[arnabnandy7]

Let's discuss the feature in #2518 first.

@zeitlinger sure thanks, I'll post in issue for further discussion.