feat: advisory parameters for metrics instruments #1801
Conversation
zvkemp
requested review from
fbogsany,
mwear,
robertlaurin,
dazuma,
ericmustin,
arielvalentin,
ahayworth,
plantfansam,
robbkidd and
kaylareopelle
as code owners
zvkemp
force-pushed
the
metrics-kwargs
branch
from
c2cb6cf to
eade680
Compare
zvkemp
force-pushed
the
metrics-kwargs
branch
from
eade680 to
8811940
Compare
|
Example of this in use in the Redis PR |
There was a problem hiding this comment.
Thanks, @zvkemp! This looks great. 🎉 I have a few testing/documentation recommendations, but the logic is sound and aligns with the spec.
When we make changes to the API/SDK, I also think about whether any changes need to be made to the OTLP exporter. In this case, it seems like the OTLP exporter should accept these attributes without any changes. A test might be helpful down the line to confirm explicit bucket boundaries are passed along, but that can be handled in a separate unit of work.
| @@ -30,4 +30,30 @@ | |||
| _(last_snapshot[0].data_points[0].attributes).must_equal('foo' => 'bar') | |||
| _(last_snapshot[0].aggregation_temporality).must_equal(:delta) | |||
| end | |||
|
|
|||
| describe 'with advisory parameters' do | |||
| let(:random_key) { "a#{SecureRandom.hex}" } | |||
There was a problem hiding this comment.
The tests on 3.0 are failing with a missing SecureRandom require: https://github.com/open-telemetry/opentelemetry-ruby/actions/runs/13058885253/job/36668636949?pr=1801#step:6:185
There was a problem hiding this comment.
Also, similar question to the API -- what do you think about adding advisory parameters/attributes for the other instruments?
| ) | ||
| end | ||
|
|
||
| let(:random_attribute) { "a#{SecureRandom.hex}" } |
There was a problem hiding this comment.
Same comment as above -- tests are failing with a missing SecureRandom require: https://github.com/open-telemetry/opentelemetry-ruby/actions/runs/13058885253/job/36668636949?pr=1801#step:6:185
| @@ -43,8 +43,8 @@ def initialize | |||
| # @param description [optional String] an optional free-form text provided by user. | |||
| # | |||
| # @return [nil] after creation of counter, it will be stored in instrument_registry | |||
| def create_counter(name, unit: nil, description: nil) | |||
| create_instrument(:counter, name, unit, description, nil) { COUNTER } | |||
| def create_counter(name, unit: nil, description: nil, **advisory_parameters) | |||
There was a problem hiding this comment.
Could you add some documentation to each of the instruments about the relevant **advisory_parameters named keyword args?
| @@ -24,11 +24,21 @@ | |||
| _(counter.class).must_equal(OpenTelemetry::Metrics::Instrument::Counter) | |||
| end | |||
|
|
|||
| it 'test create_counter with advisory parameters' do | |||
There was a problem hiding this comment.
Considering tests as documentation, I think it would be helpful to add assertions for the other instruments with their permitted advisory parameters.
| @@ -35,7 +35,21 @@ def record(amount, attributes: {}) | |||
| private | |||
|
|
|||
| def default_aggregation | |||
| OpenTelemetry::SDK::Metrics::Aggregation::ExplicitBucketHistogram.new | |||
| # This hash is assembled to avoid implicitly passing `boundaries: nil`, | |||
| # which should be valid explicit call according to ExplicitBucketHistogram#initialize | |||
There was a problem hiding this comment.
| # which should be valid explicit call according to ExplicitBucketHistogram#initialize | |
| # which should be a valid explicit call according to ExplicitBucketHistogram#initialize |
| advisory_parameters.each_key do |parameter_name| | ||
| OpenTelemetry.logger.warn "Advisory parameter `#{parameter_name}` is not valid for instrument kind `#{instrument_kind}`; ignoring" | ||
| end |
There was a problem hiding this comment.
Would you mind adding a test that covers this scenario?
According to the metrics API, instrument creation should support advisory parameters.
The two current parameters are
attributesandexplicit_bucket_boundaries.attributes(status: development), apply to every instrument.explicit_bucket_boundariesonly apply to histograms.The advisory parameters are accepted at instrument creation, validated that they apply to that instrument type, and then are cached on the instrument. New instances of their configured aggregations receive these parameters at
#initialize.