Announcing the RPC Semantic Conventions stabilization project

The Semantic Conventions SIG is excited to kick off the RPC stabilization effort!

Following the stabilization of the database conventions in May 2025, we’re continuing our work to stabilize key areas—and RPC is next.

It takes a village to define a solid convention, especially for a space as diverse as RPC technologies, which include gRPC, JSON-RPC, Apache Dubbo, and many others. If you work on one of these frameworks, use them extensively, or are simply interested in learning more, come join us—we’d love your help!

Towards reliable telemetry conventions

Reliable, well-defined conventions are the runway for richer telemetry experiences. When signal and attribute names stay consistent, everyone can spend their time building alerts, dashboards, and visualizations - not firefighting breaking changes.

Existing experimental conventions have been in use for quite a while, and we understand that introducing any breaking changes in the corresponding instrumentations will be disruptive.

We firmly believe that these changes are essential in the long run to deliver high-quality instrumentation that produces actionable, useful telemetry.

To ensure a smooth transition, we are planning to follow a graceful migration plan. Instrumentation libraries will:

  • Ship the new semantic conventions behind an opt-in flag, side-by-side with the existing ones,
  • Maintain both versions of conventions for an extended period,
  • Provide detailed migration guide.

How does semantic convention stabilization work?

During the stabilization phase, we review existing conventions to ensure they offer meaningful insights for most applications using the technology. We check that the conventions enable generic instrumentation with reasonable performance overhead, while also accounting for privacy, telemetry volume, consistency, and correlation with higher-level application and lower-level transport telemetry.

We aim for conventions that are useful, usable, and extensible.

For RPC, we’re focusing on the following major areas:

  • Essential signals: We aim to define a core set of telemetry signals, such as client/server spans and call duration histograms, that can be recorded consistently across frameworks. These support common debugging workflows and RED (rate, errors, duration) metrics. We’ll review existing conventions, identify core attributes, and document both their generic definitions and framework-specific applications.

  • Framework-specific telemetry: We encourage frameworks to extend the generic conventions with additional attributes, spans, or metrics that reflect their specific features. We’ll review these extensions, including community-maintained ones like gRPC metrics.

  • Scope: Bi-directional streaming inherently comes with limited observability. We’ll evaluate which useful signals can realistically be captured.

  • Consistency and guidelines: Over the years, we’ve developed better practices for naming, and recording peer details or errors. RPC conventions will be updated to align with these latest guidelines.

  • Prototyping: A key requirement for stabilization is having real-world instrumentations and prototypes that follow the conventions. These implementations provide critical feedback on clarity, feasibility, and practical value, and help validate that the approach works across different libraries and protocols.

How to get involved?

We’re looking for contributors with experience in any popular RPC frameworks, as well as anyone interested in building instrumentation prototypes. If you’d like to participate, please join us by commenting on the RPC stabilization project proposal.

Last modified June 2, 2025: RPC stabilization blog (#6992) (05b96b8f)