feat: Add Rage instrumentation by rsamoilov · Pull Request #1904 · open-telemetry/opentelemetry-ruby-contrib

rsamoilov · 2026-01-05T00:11:31Z

Summary

This PR adds OpenTelemetry instrumentation for Rage, a fiber-based Ruby web framework.

The instrumentation leverages Rage's built-in Telemetry interface to instrument:

HTTP requests - Enriches Rack spans with controller/action information and route patterns
WebSocket connections - Traces connections, channel subscriptions, and broadcasts with span linking
Event bus - Instruments event publishing and subscriber processing with context propagation
Background jobs - Traces job enqueuing and execution with context propagation and retry tracking
Fiber context propagation - Ensures OpenTelemetry context flows correctly across application-level fibers

Implementation Details:

Uses Semantic Conventions v1.36+
Implements span linking to tie WebSocket connections back to initial handshakes
Adds trace/span IDs to Rage logs

Note: The Rage version compatible with this instrumentation (1.20.0+) has not been released yet. This PR is intended to be merged before the Rage release so that the instrumentation is available immediately when users upgrade.

linux-foundation-easycla · 2026-01-05T00:11:39Z

The committers listed above are authorized under a signed CLA.

✅ login: rsamoilov / name: Roman Samoilov (3aa7b80, 72d16c7, 8389502, 99fd596, cd73fc1, e3e5df8)

arielvalentin · 2026-01-05T15:58:41Z

Thank you @rsamoilov for your contribution. I see that you are a core contributor of rage-rb so I am pleased that you all have taken the time to instrument the framework using OpenTelemetry!

Our preference would eventually be for library maintainers to maintain first party instrumentations in their respective repositories as opposed to the contrib package. In other words, have the rage-rb-otel instrumentation be included in your library and we work with you to publish it in the OTel registry.

This would give you the flexibility to maintain the instrumentation as a part of your organization and reduce friction trying to get changes merged into the contrib repo. We have limited resources and lack the expertise in the framework so it will be difficult for us to provide you with a thorough review.

The areas where I think that we will be able to help with code-reviews or unblock you when faced with incompatibilities with the SDK.

Is this something you would be amenable to?

rsamoilov · 2026-01-05T23:06:17Z

Hi @arielvalentin

This makes sense to me. I will create a repo and get back to you. Thanks!

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/cable.rb

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/deferred.rb

thompson-tomo · 2026-01-07T13:54:47Z

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/deferred.rb

+
+            OpenTelemetry::Context.with_current(otel_context) do
+              attributes = {
+                SemConv::Incubating::MESSAGING::MESSAGING_SYSTEM => 'rage.deferred',


instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/events.rb

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/request.rb

thompson-tomo · 2026-01-07T13:59:25Z

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/request.rb

+            http_route = request.route_uri_pattern
+            span.name = "#{request.method} #{http_route}"
+
+            attributes = {


Is there any additional semconv attributes that could be added?

Not that I can think of - these are pretty much the same attributes Action Pack adds to requests. Any recommendations?

Take a look at https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client-span

You're referring to a client span for outbound connections. handlers/request.rb processes inbound connections.

In that case look at the server span.

Most of those attribute are already being added to the span inside the Rack instrumentation:

http.request.method

server.address

url.scheme

url.path

url.query

user_agent.original

http.route

http.response.status_code

Are you saying that those attributes are being added to this span elsewhere or are they on different spans?

They are added by the Rack instrumentation.

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/deferred.rb

rsamoilov · 2026-01-07T17:46:45Z

@arielvalentin I've created rage-rb/opentelemetry-instrumentation. Let me know how you'd like to proceed.

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/cable.rb

thompson-tomo · 2026-01-09T08:53:02Z

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/cable.rb

+            OpenTelemetry::Context.with_current(handshake_context) do
+              attributes = {
+                SemConv::Incubating::MESSAGING::MESSAGING_SYSTEM => 'rage.cable',
+                SemConv::Incubating::MESSAGING::MESSAGING_DESTINATION_NAME => channel.class.name,


Suggested change

SemConv::Incubating::MESSAGING::MESSAGING_DESTINATION_NAME => channel.class.name,

'rage.cable.stream.name' => connection.class.name,

thompson-tomo · 2026-01-09T08:55:04Z

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/cable.rb

+              attributes = {
+                SemConv::Incubating::MESSAGING::MESSAGING_SYSTEM => 'rage.cable',
+                SemConv::Incubating::MESSAGING::MESSAGING_DESTINATION_NAME => connection.class.name,
+                SemConv::Incubating::CODE::CODE_FUNCTION_NAME => "#{connection.class}##{action}"


Suggested change

SemConv::Incubating::CODE::CODE_FUNCTION_NAME => "#{connection.class}##{action}"

'rpc.operation.type' => "{action}"

Cable is a pub/sub (broadcast to subscribers) system, not RPC (call and wait for response). While channels can be triggered usin RPC actions, there's no return value. Using rpc.operation.type essentially misclassifies the system.

RPC also considers streaming which is not request and response.

It's a bit hard for me to reason about it without understanding what a messaging system is in the OpenTelemetry terms.

Anyway, the latest semantic conventions state that for streaming RPCs, the server span should cover the full lifetime of the request and/or response streams until they are closed or terminated.

This implies that:

RPC is considered request/response, which is not true for WebSockets.

The RPC span should cover the entire lifetime of the WebSocket connection. This is unrealistic for WebSockets as connections can be open for days and weeks.

Please let me know if I've misinterpreted it.

I agree that the defination of rpc covering the entire duration as one span makes it harder, hopefully it will be addressed as part of the rpc stabilisation effort. I do know streaming was initially out of scope.

It's a bit hard for me to reason about it without understanding what a messaging system is in the OpenTelemetry terms.

Agree that having the definition/requirements of things like messaging.system documented is important.

But you do recommend going with the RPC attributes, right?

thompson-tomo · 2026-01-09T08:55:51Z

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/cable.rb

+              attributes = {
+                SemConv::Incubating::MESSAGING::MESSAGING_SYSTEM => 'rage.cable',
+                SemConv::Incubating::MESSAGING::MESSAGING_DESTINATION_NAME => channel.class.name,
+                SemConv::Incubating::CODE::CODE_FUNCTION_NAME => "#{channel.class}##{action}"


Suggested change

SemConv::Incubating::CODE::CODE_FUNCTION_NAME => "#{channel.class}##{action}"

'rpc.operation.type' => "{action}"

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/cable.rb

thompson-tomo · 2026-01-09T09:09:52Z

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/cable.rb

+          def self.create_broadcast_span(stream:)
+            attributes = {
+              SemConv::Incubating::MESSAGING::MESSAGING_SYSTEM => 'rage.cable',
+              SemConv::Incubating::MESSAGING::MESSAGING_OPERATION_TYPE => 'publish',


Suggested change

SemConv::Incubating::MESSAGING::MESSAGING_OPERATION_TYPE => 'publish',

'rpc.operation.type' => 'publish',

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/deferred.rb

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/events.rb

thompson-tomo · 2026-01-09T09:19:53Z

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/request.rb

+            http_route = request.route_uri_pattern
+            span.name = "#{request.method} #{http_route}"
+
+            attributes = {


In that case look at the server span.

rsamoilov · 2026-01-09T20:33:40Z

Hey @thompson-tomo , thanks for the review!

'rage.cable.stream.name' => connection.class.name

Same as with Action Cable, streams aren't properties of connections - they are being created when the application code executes stream_from. A single client can be associated with zero or multiple streams, so using rage.cable.stream.name when accepting connections/subscriptions doesn't seem semantically correct.

Using messaging.destination.name with the connection/channel class name identifies the actual destination of the message.

'messaging.client.id' => subscriber.class

Looking at other implementations and OTel docs, messaging.client.id seems to be used to identify the instance that processes the message (process/host) rather than the code being executed.

'rpc.operation.type' => 'publish',

Cable is a pub/sub (broadcast to subscribers) system, not RPC (call and wait for response). While channels can be triggered usin RPC actions, there's no return value. Using rpc.operation.type essentially misclassifies the system.

The Workflow proposal should cater for this.

Background job queues have all attributes of messaging systems; since workflow conventions are still a proposal, I'd propose using established messaging conventions now and migrating to workflow once it's stable.

thompson-tomo · 2026-01-10T00:14:43Z

Have gone and transfered the above feedback to the review comments and responded accordingly

rsamoilov · 2026-01-15T23:09:06Z

@arielvalentin @thompson-tomo Just checking in on the PR - please let me know how we can proceed.

Currently, most disagreements are about the Cable instrumentation. I’m happy to delete it and tackle in another PR if you think it makes sense.

rsamoilov · 2026-01-26T18:41:57Z

@arielvalentin @thompson-tomo Hey folks, thank you for your feedback! I'll give the PR one more week for review. If there are no concerns, I'll then move forward with maintaining this under the Rage org.

@dazuma Would you be able to take a look at the instrumentation when you get a chance?

arielvalentin · 2026-01-26T23:51:45Z

@rsamoilov please proceed with releasing the code as a part of your repo!

Happy to help answer questions or provide feedback there as well.

the "what code rag" info is carried inside the span name; `code.*` is used for debugging, not primary semantic modeling;

rsamoilov · 2026-01-30T19:32:53Z

@thompson-tomo Made some updates:

Reverted to the server span kind for Cable channels
Removed code.* attributes
Updated Cable instrumentation to use custom websocket.* attributes - let me know if you think rpc.* or rage.cable.* attributes will work better
Updated Deferred instrumentation to use the workflow.* attributes

rsamoilov · 2026-02-01T19:55:19Z

Closed in favor of #1975.

feat: Add Rage instrumentation

e3e5df8

rsamoilov requested review from a team, ahayworth, arielvalentin, dazuma, ericmustin, fbogsany, kaylareopelle, mwear, plantfansam, robbkidd, robertlaurin, simi and xuan-cao-swi as code owners January 5, 2026 00:11

github-actions bot assigned rsamoilov Jan 5, 2026

thompson-tomo reviewed Jan 7, 2026

View reviewed changes

rsamoilov commented Jan 7, 2026

View reviewed changes

instrumentation/rage/lib/opentelemetry/instrumentation/rage/handlers/deferred.rb Outdated Show resolved Hide resolved

thompson-tomo reviewed Jan 9, 2026

View reviewed changes

feat: Update messaging operation attrs to follow conventions

72d16c7

Revert to server kind for cable channel spans

cd73fc1

rsamoilov added 3 commits January 30, 2026 18:04

Remove code attributes

99fd596

the "what code rag" info is carried inside the span name; `code.*` is used for debugging, not primary semantic modeling;

Use custom websocket.* attributes

8389502

Use workflow.* attributes

3aa7b80

rsamoilov closed this Feb 1, 2026

	SemConv::Incubating::MESSAGING::MESSAGING_DESTINATION_NAME => channel.class.name,
	'rage.cable.stream.name' => connection.class.name,

	SemConv::Incubating::CODE::CODE_FUNCTION_NAME => "#{connection.class}##{action}"
	'rpc.operation.type' => "{action}"

	SemConv::Incubating::MESSAGING::MESSAGING_OPERATION_TYPE => 'publish',
	'rpc.operation.type' => 'publish',

Conversation

rsamoilov commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

linux-foundation-easycla bot commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arielvalentin commented Jan 5, 2026

Uh oh!

rsamoilov commented Jan 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rsamoilov commented Jan 7, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thompson-tomo Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rsamoilov commented Jan 9, 2026

Uh oh!

thompson-tomo commented Jan 10, 2026

Uh oh!

rsamoilov commented Jan 15, 2026

Uh oh!

rsamoilov commented Jan 26, 2026

Uh oh!

arielvalentin commented Jan 26, 2026

Uh oh!

rsamoilov commented Jan 30, 2026

Uh oh!

rsamoilov commented Feb 1, 2026

Uh oh!

Reviewers

Assignees

rsamoilov commented Jan 5, 2026 •

edited

Loading

linux-foundation-easycla bot commented Jan 5, 2026 •

edited

Loading

thompson-tomo Jan 26, 2026 •

edited

Loading