Update Metrics to latest specification.

[jsuereth]

Here's the task list for taking the prototyped ideas in #3333 and piecemeal submitting them into main branch.

• Update data model
  • Attributes Migrate Metrics SDK "data' package to Attributes #3352
  • Exemplars Wire Exemplars into the metrics.data package #3353
• Update API Swap old Metrics API for currently specified Metrics API #3423
• Update SDK
  • Views
    • Per-metric-storage vs. instrument Overhaul sdk.metrics package for new SDK: Decouple Instrument + Storage per-metric. #3455
    • Select by InstrumentationLibraryInfo View API additons #3491
    • Enable metric renaming / redescription Update View-wiring to match SDK specificaiton #3510
    • Do not crash (by default) when a metric name conflict is detected, instead issue an error. Allow multiple views per instrument #3541
    • Allow multiple views per-instrument as long as there are no name conflicts Allow multiple views per instrument #3541
    • Improve error message + provenance of metric-name clashes. Add diagnostic messages for metric registration conflicts. #3808
    • Move aggregator package to internal, only expose necessary public interfaces Reduce public aggregator API to match latest specification. #3557
    • Rework LabelsProcessor, allow Baggage attribute additions. Rework LabelsProcessor to have access to context - Update View SDK API #3562
    • Allow wildcard matching (Metrics Views API: Wildcard Support #3642)
    • Remove AggregationTemporality from aggregator config (spec update)
  • Exemplars
    • Implement ExemplarFilter + wire into correct paths Wire in Exemplar Pre-Filters #3591
    • Implement ExemplarReservoir + wire into aggregator Wire Exemplar Reservoir into Metrics SDK #3583
    • Implement simple + histogram reservoirs Implementations of Exemplar Reservoirs #3592
    • Implement mechanism to use aggregation configuration to instantiate exemplar reservoirs Finish wiring exemplars into metrics SDK #3599
  • Multi-Exporter
    • Initial specification implementation MetricReader and Multi-export features #3578
    • allow multiple reader "within interval" to avoid re-collecting synchronous metrics. Fix Clock usage in Metrics SDK and slight optimisation to synchronous collection #3689

Cleanups

• Exemplar data class names Exemplar data classes should match convention. #3688
• Multi-registration of instrument errors [spec compliance] Metrics SDK does not fail on duplicate name/different instrument metrics. #3809
• PeriodicMetricReader environment variables Autoconfigure interval metric reader not aligned with spec  #3746
• Environment variable configuration for OTLP exporter aggregation temporality

(Optional) Follow-ons

• Optimise MetricDescriptor exports Add MetricDescriptor to SDK for exporting #3534
• Optimise Async instruments to only collect once per-collection vs. once-per-metric-per-collection.
• pre-allocate delta storage and limit its size. That should be hidden in this class and would be per-metric.
• join multiple MetricExporters into a single MetricReader if they all use periodic metric reader.

[jamesmoessis]

Exponential histogram coming later I suppose?

[jsuereth]

Yeah, this is not a complete list. As things get better specified, they'll be added.

For exponential histograms, I'd highly recommend doing a parallel experiment right now. While I expect the Aggregator package to undergo some refactorings (and hopefully simplifications) you should be able to prototype an exponential hsitogram today.

I opened a bug around that here: #3550

[breedx-splk]

related to #3724

[jack-berg]

An additional problem I've noticed is that you can use the metric API / SDK to produce metrics streams that violate their monotonic properties.

For example, take the following async counter:

AtomicLong count = new AtomicLong(100);
    meter
        .counterBuilder("async-counter")
        .buildWithCallback(
            measurement ->
                measurement.observe(count.decrementAndGet()));

For both cumulative and metric exporters, this will product monotonic sums that violate their monotonicity. In the delta case, the values will be negative, which is a violation. In the cumulative case, the values will be decreases, which is a violation.

The same thing is true a a sync counter:

    AtomicLong count = new AtomicLong(100);

    LongCounter counter = meter.counterBuilder("sync-counter").build();
    counter.add(count.decrementAndGet());
    // .. await export
    counter.add(count.decrementAndGet());
    // .. await export
    counter.add(count.decrementAndGet());

The question is what should the SDK do in these cases where the recorded value violates the assumptions of the instrument.

[jsuereth]

I'm not sure I understand the sync counter bit? The counter should be adding all those non-negative measurments together.

For the first problem, we assume good-faith on the callback functions, and we should carefully document expectations on those. (Similar to requirements on these about good thread-management, blocking calls, etc.). I'm not convinced the SDK needs to do something in its production pathway, but I do think a testing-SDK that highlights issues like this should issue exceptions.

[jack-berg]

I'm not sure I understand the sync counter bit? The counter should be adding all those non-negative measurments together.

Right right, something got crossed in my brain.

I'm not convinced the SDK needs to do something in its production pathway,

I'm not sure I do either. At least not without a convincing argument of what the SDK should do from an export perspective when these scenarios occur.

It's worth noting that counters (SdkLongCounter, SdkDoubleCounter) throw exceptions if you try to report a negative number. Maybe we could do the same with async instruments?

[jsuereth]

It's worth noting that counters (SdkLongCounter, SdkDoubleCounter) throw exceptions if you try to report a negative number. Maybe we could do the same with async instruments?

Just making sure it's non-negative? Yeah. I do think it's worth having a "test" or "verify" mode for the sdk where more of these assertions come into play for folks writing instrumentation, so it's not just a "log and ask end-users to fix" thing (although we also shouldn't punish end-users if library-instrumentation is bad, we SHOULD log and ask-to-fix if they see it in production).

For the purposes of tracking here, it should be added. Do you have edit access to update TOOOs/link other issues? If so, please feel free to update any "stable-release" blocking things you think we need to do. If not, let me know what you want added here and I'll make sure this represents our "known TODOs prior to stable" and check with @anuraaga and @jkwatson for their list as well.

[jkwatson]

For the purposes of tracking here, it should be added. Do you have edit access to update TOOOs/link other issues? If so, please feel free to update any "stable-release" blocking things you think we need to do. If not, let me know what you want added here and I'll make sure this represents our "known TODOs prior to stable" and check with @anuraaga and @jkwatson for their list as well.

Thou shalt create an issue if you want it to be remembered. ;)

[jsuereth]

Moving remaining tracking items to: https://github.com/open-telemetry/opentelemetry-java/projects/3

[jack-berg]

Created a new issue from my comment here.