docs(collector): update internal telemetry RPC metrics

[dol]

• I have read and followed the Contributing docs, especially the "First-time contributing?" section.
• This PR has content that I did not fully write myself.
  • I used AI and I have read and followed the Generative AI Contribution Policy.
• I have the experience and knowledge necessary to understand, review, and validate all content in this PR.¹

---

This PR updates the Collector internal telemetry docs to match the RPC metrics emitted by newer Collector builds.

It makes three concrete documentation corrections in content/en/docs/collector/internal-telemetry.md:

• rename the documented RPC duration metrics from rpc.client.duration / rpc.server.duration to rpc.client.call.duration / rpc.server.call.duration
• remove the deprecated rpc.*.requests_per_rpc and rpc.*.responses_per_rpc entries from the detailed metrics table
• add version-context explaining that older Collector releases may still expose the legacy rpc.client.duration and rpc.server.duration names

The reason for this change is a dependency chain across the semantic conventions, the generated Go semconv packages, the gRPC instrumentation used by the Collector, and finally the Collector docs.

The upstream source of truth is the semantic-conventions repo:

• In open-telemetry/semantic-conventions commit 9f213161a9bb24225da7a318365b24d497f8d466 (Deprecate rpc.*.requests_per_rpc and rpc.*.responses_per_rpc metrics semantic-conventions#2846), the RPC requests_per_rpc and responses_per_rpc metrics were deprecated and moved out of the active RPC metric model from model/rpc/metrics.yaml into model/rpc/deprecated/metrics-deprecated.yaml.
• In open-telemetry/semantic-conventions commit 494eb91991c877fcd82b6f17817c343f3dc600fd (Rename rpc.client|server.duration to rpc.client|server.call.duratio, change unit from ms to sec, clarify duration in case of streaming semantic-conventions#2961), rpc.client.duration and rpc.server.duration were renamed to rpc.client.call.duration and rpc.server.call.duration, and the duration unit changed from milliseconds to seconds.

Those semantic-convention changes then flowed into the generated Go semconv packages:

• In open-telemetry/opentelemetry-go commit 6af2f2ff6724b5d4a806d945a7224fa723718c39 (Generate semconv/v1.38.0 opentelemetry-go#7648, Generate semconv/v1.38.0), the generated Go RPC semconv package no longer includes rpc.server.responses_per_rpc and the corresponding *_per_rpc helpers.
• In open-telemetry/opentelemetry-go commit f809f7d7134d97d13bbf60bc8ddcc54f13ac6c07 (Generate semconv/v1.39.0 opentelemetry-go#7783, Generate semconv/v1.39.0), the generated Go RPC semconv package switches from rpc.server.duration to rpc.server.call.duration and from rpc.client.duration to rpc.client.call.duration.

That matters for the Collector because its gRPC internal telemetry is not hand-authored under Collector-specific metric names. Collector core wires the gRPC server and client through otelgrpc in config/configgrpc/configgrpc.go, and otelgrpc constructs its instruments from the generated rpcconv helpers. In current Go module versions that means:

• otelgrpc.NewServerHandler(...) uses rpcconv.NewServerCallDuration(...)
• otelgrpc.NewClientHandler(...) uses rpcconv.NewClientCallDuration(...)

So once Collector core upgraded its OpenTelemetry Go dependencies, the emitted internal RPC duration metrics changed as a consequence of that dependency update, even though the Collector’s own gRPC instrumentation wiring stayed conceptually the same.

This is the important part of the reasoning for the documentation change:

1. The docs page lists internal metrics for detailed verbosity.
2. The RPC metrics on that page come from instrumentation libraries, not from first-party Collector component metric definitions.
3. The semantic-conventions project deprecated the *_per_rpc metrics and renamed the duration metrics.
4. opentelemetry-go regenerated its semconv packages from those newer semantic conventions.
5. otelgrpc uses those regenerated semconv helpers to define the actual instrument names.
6. Collector core uses otelgrpc for internal gRPC client/server instrumentation.
7. Therefore newer Collector releases emit the new *.call.duration names and no longer expose the deprecated *_per_rpc metrics through the current Go-based internal RPC instrumentation path.

That is why the previous documentation became stale:

• it still listed rpc.client.duration and rpc.server.duration as if they were the current names
• it still listed rpc.*.requests_per_rpc and rpc.*.responses_per_rpc as if they were still part of the current generated Go instrumentation surface

This PR updates the page to reflect the current state while still noting that older Collector releases may show the legacy duration names. I kept that compatibility note because users may be comparing different Collector versions and the page should make the version boundary understandable instead of presenting the current names as timeless.

Validation:

• formatted the updated doc with Prettier
• attempted the repository quality gate via npm run check
• the full check does not currently pass because of pre-existing check:i18n drift in many unrelated translated files, not because of this doc change

Relevant upstream references:

• Deprecate rpc.*.requests_per_rpc and rpc.*.responses_per_rpc metrics semantic-conventions#2846
• Rename rpc.client|server.duration to rpc.client|server.call.duratio, change unit from ms to sec, clarify duration in case of streaming semantic-conventions#2961
• Generate semconv/v1.38.0 opentelemetry-go#7648
• Generate semconv/v1.39.0 opentelemetry-go#7783

Repo commit for this docs change:

• 37feaa1 docs(collector): update internal telemetry RPC metrics

Footnotes

1. Yes, I can answer maintainer questions about the content of this PR, without using AI. ↩

[jade-guiton-dd]

Looks mostly good to me, just a few notes.

(I guess the review request from collector-approvers was removed, but the bot is still tagging missing:sig-approval? Not sure how that works 🤔)

[tiffany76]

Thanks very much, @dol! I made a couple suggestions to integrate the information into the page.

[odubajDT]

AFAIK, only the .call. metrics are available in the latest version of collector and semconv https://opentelemetry.io/docs/specs/semconv/rpc/rpc-metrics/

Suggested change

	| `rpc.client.call.duration` | Measures the duration of outbound remote procedure calls (RPC). | Histogram |
	| `rpc.client.request.size` | Measures the size of RPC request messages (uncompressed). | Histogram |
	| `rpc.client.response.size` | Measures the size of RPC response messages (uncompressed). | Histogram |
	| `rpc.server.call.duration` | Measures the duration of inbound remote procedure calls (RPC). | Histogram |
	| `rpc.server.request.size` | Measures the size of RPC request messages (uncompressed). | Histogram |
	| `rpc.server.response.size` | Measures the size of RPC response messages (uncompressed). | Histogram |
	| `rpc.client.call.duration` | Measures the duration of outbound remote procedure calls (RPC). | Histogram |
	| `rpc.server.call.duration` | Measures the duration of inbound remote procedure calls (RPC). | Histogram |

[jade-guiton-dd]

Indeed, I've just confirmed experimentally that:

• in 0.147.0, the RPC metrics changed to the ones currently in the PR;
• in 0.148.0, the size metrics were disabled.

Not sure why that happened in two steps, or whether there is any replacement for the size metrics?

[tiffany76]

I dug into this with AI's help, and the short answer is no, there is no replacement. The Semantic Conventions SIG deprecated the rpc size metrics because they had "ambiguous definitions and inconsistent implementation".

So we'll need to update this page with a little more guidance.

Thanks for pointing this out, @odubajDT!

[tiffany76]

Since the RPC section was getting a little long, I suggest we eliminate the callout and create a new section about metric ownership. Very open to feedback on this idea.

Suggested change

	#### Ownership of emitted metrics
	Some metrics are not owned by the Collector SIG and some are limited to certain components.
	**`http*`and `rpc` metrics**
	These metrics are not under the Collector SIG's control, and as such, are not covered by the maturity levels below.
	**`rpc` metrics**
	The Collector's internal RPC metrics come from the upstream
	[`otelgrpc`](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation/google.golang.org/grpc/otelgrpc)
	instrumentation, which tracks the [OpenTelemetry RPC semantic conventions](/docs/specs/semconv/rpc/rpc-metrics/). The set of RPC
	metrics emitted by the Collector has changed across releases:
	| Collector version | Emitted RPC metrics |
	| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
	| v0.146.x and earlier | `rpc.client.duration`, `rpc.server.duration`, `rpc.*.request.size`, `rpc.*.response.size`, `rpc.*.requests_per_rpc`, `rpc.*.responses_per_rpc` |
	| v0.147.0 | `rpc.client.call.duration`, `rpc.server.call.duration`, `rpc.*.request.size`, `rpc.*.response.size` (the `*_per_rpc` metrics are deprecated and no longer emitted) |
	| v0.148.0 and later | `rpc.client.call.duration`, `rpc.server.call.duration` only |
	RPC size metrics are not emitted by
	Collector v0.148.0 or later. The [RPC semantic conventions v1.40.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.40.0)
	deprecated them due to ambiguous definitions and inconsistent implementation.
	**`otelcol_processor_batch_*` metrics**
	These metrics are unique to the `batchprocessor`.
	**`helper` package metrics**
	The `otelcol_receiver_`, `otelcol_scraper_`, `otelcol_processor_`, and `otelcol_exporter_` metrics come from their respective `helper` packages. As such, some components not using those packages might not emit them.