stats: add a Nanoseconds histogram unit

[bpalermo]

Commit Message

stats: add a Nanoseconds histogram unit

Additional Description

Stats::Histogram::Unit stops at microseconds. The motivating consumer is
Nighthawk, Envoy's load generator, which records request
latencies in nanoseconds and is adding export of those histograms through Envoy's own statsd and
DogStatsD sinks (envoyproxy/nighthawk#1617). Today it has to either quantize to microseconds at
recording time, losing sub-microsecond resolution on the loopback and same-host latencies it exists
to measure, or register the histogram without a unit, in which case the statsd sinks relabel the raw
nanosecond value as milliseconds and report a 3.9 ms latency as about 65 minutes. The same applies to
any embedder or extension measuring sub-microsecond durations.

This adds Unit::Nanoseconds and wires it through the three places that switch on the unit:

• HistogramCompletableTimespanImpl records the elapsed nanoseconds for such a histogram.
• The statsd, DogStatsD and Graphite statsd sinks scale nanosecond samples to milliseconds when
  scale_histogram_units_to_milliseconds (stat_sinks: scale statsd histogram samples to milliseconds by unit #47505) is enabled; with it disabled the sample passes
  through unchanged as for every other unit.
• The Lua filter accepts "nanoseconds" as a histogram unit.

The unit is opt-in by construction: nothing in Envoy creates a nanosecond histogram, so no existing
metric, value or bucket boundary changes. Storage is unaffected: circllhist bins values to two
significant digits, so scaling samples by 1000 shifts exponents without adding populated bins.

Not included: the stats access logger's own proto unit enum, which is an API change and has no
sub-microsecond source values; and unit-aware default Prometheus/OTel buckets, which would be a
behavior change for existing output. The changelog notes that nanosecond histograms need explicit
histogram_bucket_settings for those exporters.

Risk Level

Low. Additive enum value; no default behavior change.

Testing

New ElapsedAndCompleteNanoseconds timespan test; nanosecond samples added to the SiSuffix and
HistogramUnitScalingOffByDefault tests of both statsd sinks; Lua HistogramUnits test extended.

Docs Changes

Lua filter docs list the new unit string.

Release Notes

Added a new feature fragment.

Platform Specific Features

N/A

[repokitteh-read-only]

As a reminder, PRs marked as draft will not be automatically assigned reviewers,
or be handled by maintainer-oncall triage.

Please mark your PR as ready when you want it to be reviewed!

🐱

Caused by: #47737 was opened by bpalermo.

see: more, trace.

[bpalermo]

/retest

[bpalermo]

@mathetake this is the follow-up to #47505 you reviewed last week: it adds a Nanoseconds histogram unit so the opt-in scale_histogram_units_to_milliseconds field also covers histograms recorded in nanoseconds. The motivating consumer is Nighthawk (envoyproxy/nighthawk#1617), which records latencies in nanoseconds and is routing them through Envoy's statsd sinks. It is additive, no Envoy histogram uses the unit, and CI is green. Would you mind taking a look when you have a moment?