feat: add basic support for metrics exemplar by xuan-cao-swi · Pull Request #1609 · open-telemetry/opentelemetry-ruby

xuan-cao-swi · 2024-02-27T19:03:35Z

Description

Exemplar is useful for trace-metric correlation and I'd like to make a contribute (based on otel ticket and otel spec).

Exemplars in Grafana and Tempo (trace)

Exemplars in Prometheus

…igher precedence

github-actions · 2024-04-02T01:47:02Z

👋 This pull request has been marked as stale because it has been open with no activity. You can: comment on the issue or remove the stale label to hold stale off for a while, add the keep label to hold stale off permanently, or do nothing. If you do nothing this pull request will be closed eventually by the stale bot

…o metrics-exemplar

kaylareopelle · 2026-03-17T22:59:49Z

Hi @xuan-cao-swi, this is a big PR and I'm about 40% of the way through it. I'm going to continue my review tomorrow, but I have one small request in the meantime.

Could you add documentation to the create_#{instrument} API methods for the new exemplar_filter and exemplar_reservoir arguments?

…o metrics-exemplar

xuan-cao-swi · 2026-03-18T14:45:28Z

@kaylareopelle Thanks! Sorry about this huge PR. I added the doc for exemplar-related params in api.

kaylareopelle · 2026-03-18T16:27:03Z

@kaylareopelle Thanks! Sorry about this huge PR. I added the doc for exemplar-related params in api.

@xuan-cao-swi Thanks for the updates! No problem about the size, just takes a little more time :) The upside to big PRs is that they're usually feature-complete, so you can see how everything fits together. Thanks for your patience!

kaylareopelle

Great job on this! I'm not finished with my review yet. I'm sharing some comments now so you can look at them. I need more time to understand the rest of the PR and run some tests. I will continue the review tomorrow. Thank you!

kaylareopelle · 2026-03-17T22:18:47Z

              bucket_counts: hdp.bucket_counts,
              explicit_bounds: hdp.explicit_bounds,
-              exemplars: hdp.exemplars,
+              exemplars: hdp.exemplars&.map { |ex| as_otlp_exemplar(ex) } || [],


I get a little worried sometimes about calling methods within argument assignments. It might throw off an entire export instead of just impacting that particular key. What do you think about moving the &.map { |ex| as_otlp_exemplar(ex) } || [] logic to a method and passing hdp.exemplars as an arg?

Refactored to a separate function as_otlp_exemplars.

kaylareopelle · 2026-03-17T22:25:56Z

              ndp.start_time_unix_nano = start_time
              ndp.time_unix_nano = end_time
+              reservoir = @exemplar_reservoir_storage[ndp.attributes]
+              ndp.exemplars = reservoir&.collect(attributes: ndp.attributes, aggregation_temporality: :delta)


Do we want to force the aggregation_temporality to be :delta here? Do we have access to @aggregation_temporality like in the sum aggregation?

I think we should force :delta here as last_value implements the gauge aggregation which has no aggregation temporality.

kaylareopelle · 2026-03-18T20:38:58Z

+        # Adds a new exemplar_filter to replace exist exemplar_filter
+        # Default to TraceBasedExemplarFilter
+        #
+        # @param exemplar_filter the new ExemplarFilter to be added.
+        def exemplar_filter_on(exemplar_filter: Exemplar::TraceBasedExemplarFilter)
+          @exemplar_filter = exemplar_filter
+        end


I'm a worried about naming this method exemplar_filter_on. Is that a name used in other implementations?

Just reading the method name, I assume it turns on the AlwaysOn filter.

What do you think about something like enable_exemplar_filter?

Updated the name to enable_exemplar_filter and disable_exemplar_filter

kaylareopelle · 2026-03-18T20:43:28Z

+    module Metrics
+      module Exemplar
+        # ExemplarFilter
+        class ExemplarFilter


Since the other exemplar filters inherit from this one, what do you think about changing the code structure to create a subdirectory within exemplar just for filters?

I'd like to keep them flat (e.g. no subdirectory) like other languages' file structure

kaylareopelle · 2026-03-18T20:44:11Z

+      module Exemplar
+        # ExemplarReservoir base class
+        # Subclasses must implement offer and collect methods
+        class ExemplarReservoir


Similar question as to what I had for filters -- should there be a subdirectory for the reservoirs that inherit from this one?

kaylareopelle · 2026-03-18T20:45:41Z

+        # TraceBasedExemplarFilter
+        class TraceBasedExemplarFilter < ExemplarFilter
+          def self.should_sample?(value, timestamp, attributes, context)
+            ::OpenTelemetry::Trace.current_span(context).context.trace_flags.sampled?


I'm a little worried that so many chained method calls could raise an error. Rather than adding safe nav operators to each one, what do you think about adding a rescue that would just catch any error and make the method return false?

Updated the function that separates the call chain and rescue

Co-authored-by: Kayla Reopelle <87386821+kaylareopelle@users.noreply.github.com>

kaylareopelle

@xuan-cao-swi - Thank you for all your updates!

kaylareopelle · 2026-03-19T19:43:48Z

+    end
+  end
+
+  # TODO: OpenTelemetry.meter_provider.add_view


Do we still need this TODO?

Sorry, I missed the review. No, we don't need it. I will create another pr to clean this up

No problem!

kaylareopelle · 2026-03-20T18:23:10Z

  OpenTelemetry.logger = original_logger
 end

+def create_meter


You know what, I think it's okay here. I was thinking about moving it to the test_helpers gem originally, but it doesn't seem very useful outside of this test environment on second thought.

And good to know! Thank you for clarifying!

kaylareopelle

Thanks for your patience and work on this feature, @xuan-cao-swi. This is a big PR and though I think I understand it now, I may have missed a few things. I'm comfortable getting this out into the wild and we can address any follow-ups after users test it out.

Added in open-telemetry/opentelemetry-ruby#1609

## Changes Ruby recently merged a PR adding support for Exemplars to our Metrics implementation. See: open-telemetry/opentelemetry-ruby#1609 This PR updates the spec compliance matrix to reflect the change. For non-trivial changes, follow the [change proposal process](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CONTRIBUTING.md#proposing-a-change). * [-] Related issues # * [-] Related [OTEP(s)](https://github.com/open-telemetry/oteps) # * [-] Links to the prototypes (when adding or changing features) * [-] [`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md) file updated for non-trivial changes * For trivial changes, include `[chore]` in the PR title to skip the changelog check * [X] [Spec compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix/template.yaml) updated if necessary

xuan-cao-swi added 5 commits December 19, 2023 11:55

feat: exemplar init commit

a69c62d

feat: add test case and use exemplar in all synchronous counter

2827952

feat: Environment variable OTEL_METRICS_EXEMPLAR_FILTER should have h…

ae2c636

…igher precedence

feat: merge to main

9c3b693

feat: exemplar add more test and lint

7800512

github-actions Bot added the stale label Apr 2, 2024

kaylareopelle added keep and removed stale labels Apr 4, 2024

kaylareopelle added the metrics label May 21, 2024

xuan-cao-swi added 7 commits October 1, 2024 11:29

merge

3e29f01

merge and resolve conflict

04bc7a6

merge

9d7b484

lint

ae5abdc

fix test case

f890dbf

lint on metrics api

4ba58fb

resolve merge conflict

bd7f848

xuan-cao-swi marked this pull request as ready for review June 30, 2025 15:19

xuan-cao-swi requested review from ahayworth, arielvalentin, dazuma, ericmustin, fbogsany, kaylareopelle, mwear, plantfansam, robbkidd and robertlaurin as code owners June 30, 2025 15:19

kaylareopelle moved this from In progress to Ready for Review in Ruby - Metrics Aug 15, 2025

resolve conflict

8839bf6

xuan-cao-swi added 10 commits December 11, 2025 12:57

add view support for exemplar

3f5c09d

refactor the exemplar structure

abf2897

init pass, need more later

354f4f0

update

8160ced

add unsaved sum

ea20b2e

Merge branch 'main' of github.com:xuan-cao-swi/opentelemetry-ruby int…

98882e8

…o metrics-exemplar

update test case

58f6fa5

avoid use gc for test case

ab665d0

add fix number of size of exemplar bucket for test

11ebc75

skip for now

34588a9

xuan-cao-swi marked this pull request as ready for review January 2, 2026 19:12

xuan-cao-swi added 3 commits January 13, 2026 14:24

merge

abf251e

Merge branch 'main' of github.com:xuan-cao-swi/opentelemetry-ruby int…

ef935c9

…o metrics-exemplar

merge and fix one typo on filtered_attributes for exemplar

d8e3c31

xuan-cao-swi added 2 commits March 18, 2026 10:21

Merge branch 'main' of github.com:xuan-cao-swi/opentelemetry-ruby int…

d27c89a

…o metrics-exemplar

update api doc

80b409a

kaylareopelle reviewed Mar 18, 2026

View reviewed changes

xuan-cao-swi and others added 2 commits March 20, 2026 13:33

Apply suggestions from code review

64107df

Co-authored-by: Kayla Reopelle <87386821+kaylareopelle@users.noreply.github.com>

revision

e270aef

kaylareopelle reviewed Apr 3, 2026

View reviewed changes

kaylareopelle approved these changes Apr 6, 2026

View reviewed changes

kaylareopelle merged commit f81fbee into open-telemetry:main Apr 7, 2026
63 checks passed

github-project-automation Bot moved this from Ready for Review to Done in Ruby - Metrics Apr 7, 2026

kaylareopelle added a commit to kaylareopelle/opentelemetry-specification that referenced this pull request Apr 7, 2026

chore: Add Ruby support for Exemplars spec matrix

7040f50

Added in open-telemetry/opentelemetry-ruby#1609

kaylareopelle mentioned this pull request Apr 7, 2026

chore: Add Ruby support for Exemplars spec matrix open-telemetry/opentelemetry-specification#5012

Merged

1 task

otelbot-ruby Bot mentioned this pull request Apr 7, 2026

release: Release 17 items #2078

Merged

Conversation

xuan-cao-swi commented Feb 27, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Exemplars in Grafana and Tempo (trace)

Exemplars in Prometheus

Uh oh!

github-actions Bot commented Apr 2, 2024

Uh oh!

kaylareopelle commented Mar 17, 2026

Uh oh!

xuan-cao-swi commented Mar 18, 2026

Uh oh!

kaylareopelle commented Mar 18, 2026

Uh oh!

kaylareopelle left a comment

Choose a reason for hiding this comment

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!

Uh oh!

Uh oh!

kaylareopelle Mar 18, 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!

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!

kaylareopelle Mar 18, 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!

kaylareopelle left a comment

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!

kaylareopelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

xuan-cao-swi commented Feb 27, 2024 •

edited

Loading

kaylareopelle Mar 18, 2026 •

edited

Loading

kaylareopelle Mar 18, 2026 •

edited

Loading