Metric hardening, bulk pre-bucketed histogram recording

[ladd]

Doing some backflips to get MetricKit data to fit into the Otel histogram model.

• Improved input validation for metrics and tracing
• A bulk record API for pre-bucketed histogram data
• Removal of the dead MetricKit subscriber.
• Other minor cleanup

@jparise
CC: @bachand

Claude commentary below:

Hardening

• Filter non-finite and negative values at metric record sites, so NaN can't land in a histogram's overflow bucket and poison sum.
• Fix a process abort when releasing a suspended FlushTimer.
• Re-arm the idle timeout after flushTrace.
• Assert Span.adjust cannot produce a negative duration. Negative durations are handled at the reporting site: reportAsDurationHistogramMetric drops the sample.

Bulk pre-bucketed histogram recording

Sources like MetricKit return measurements already aggregated into device-chosen buckets, which the one-value-at-a-time record can't accept. BucketedMeasurement pairs a representative value with an observation count; Histogram gains record(_:count:) and record(_ measurements:), the latter taking the mutex once for the whole batch.

let measurements = hangTime.bucketEnumerator.compactMap { bucket -> BucketedMeasurement<Double>? in
    guard let bucket = bucket as? MXHistogramBucket<UnitDuration> else { return nil }
    return BucketedMeasurement(
        lowerBound: bucket.bucketStart.converted(to: .seconds).value,
        upperBound: bucket.bucketEnd.converted(to: .seconds).value,
        count: UInt64(bucket.bucketCount)
    )
}
hangTimeHistogram.record(measurements)

Bounds are taken separately rather than as a ClosedRange, because forming lower...upper traps when the bounds are reversed — a guard inside an init(range:) could never fire. The initialiser is failable and rejects non-finite bounds, reversed bounds, and buckets below zero, asserting in debug and returning nil in release.

The source's buckets are expected to line up with the histogram's explicitBounds, and a bucket is recorded at its midpoint. Bucket assignment is insensitive to that choice — a midpoint and a bound select the same destination bucket when the bounds line up — but sum is not: the midpoint is the mean of a uniformly distributed bucket, so it keeps sum unbiased, whereas recording at a bound skews it by up to a bucket width per observation, and with it any rate or mean derived from sum. Not implemented for ExponentialHistogram.

MetricKitInstrument removal

It only dumped payloads to the log behind DEBUG && os(iOS); nothing consumed it. MetricKit-sample.json was a 2021 capture from an unrelated app.

Testing

swift test passes. Each rejection guard is covered by a macOS-only exit test expecting the child process to trap, matching TimeReferenceTests. Like that test, these only hold where assertions are compiled in, so they fail under -c release.

Also fixes a pre-existing flake in FlushTimerTests.testFlushTimerIntervalChange, which asserted an exact handler count on a live repeating timer.

Also moves MetricNumeric and isFiniteMetricValue out of Identifiers.swift into a new Numeric.swift, and applies swiftformat organizeDeclarations MARKs to TimeReference and Tracer+Metrics — the only two files that were failing lint on main.

Split into 8 logical commits, each of which builds on its own.

Rebased onto main after #67.

🤖 Generated with Claude Code

[bachand]

Thanks for tagging me for visibility, @ladd. I reviewed this at a high level to follow along, and I will generally defer to @jparise's review (thanks!).

My understanding is that this PR adds support for recording pre-bucketed data, such as data from MetricKit, into a histogram that may also contain individually recorded samples. Is that right? I wanted to confirm. 👍

[bachand]

👍

[ladd]

My understanding is that this PR adds support for recording pre-bucketed data, such as data from MetricKit, into a histogram that may also contain individually recorded samples. Is that right? I wanted to confirm. 👍

In this case it's not mixed with individual samples, but the OpenTelemetry APIs have an implicit assumption that you have access to the original samples to produce the sum:

https://opentelemetry.io/docs/specs/otel/metrics/data-model/#histogram-bucket-inclusivity:~:text=A%20sum%20(sum)%20of%20all%20the%20values%20in%20the%20histogram.

Since we don't have that here, we fake it with a calculated bucket midpoint value to produce an approximation.