#61 Document histogram bucket bounds for the duration instrument

[matthewdevenny]

Closes #61.

nats.cache.operation.duration records seconds — the right OTel convention — but OpenTelemetry's default explicit bucket bounds (0, 5, 10, 25, … 10000) are millisecond-shaped. Left at the default, every realistic cache operation falls into the single (0, 5] bucket, and the README's own p99 example returns ~4.95s by interpolating inside it, three orders of magnitude off a real ~4ms latency.

Documentation-only; the package still takes no OpenTelemetry dependency and the View belongs in the consumer's registration.

• New Histogram buckets section ahead of the example queries: what goes wrong, an ExplicitBucketHistogramConfiguration View covering ~1ms–5s, and Base2ExponentialBucketHistogramConfiguration as the no-tuning alternative (with the caveat that it needs a pipeline carrying exponential histograms end to end, so the le-based queries below it assume explicit bounds).
• The p99 query now states the precondition inline, since that snippet gets copied on its own.
• Matching remark on NatsCacheTelemetryNames.OperationDurationInstrumentName, which is the name a consumer passes to AddView.

Also noted that sum/count-derived figures — hit ratio, operation rate, mean latency — are unaffected, so the existing hit-ratio query needs no bucket configuration.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the project documentation to prevent misleading latency quantiles for the nats.cache.operation.duration seconds-unit histogram by explaining why OpenTelemetry’s default explicit bucket bounds are inappropriate and showing consumer-side View configurations.

Changes:

• Adds a new README “Histogram buckets” section explaining the default-bounds pitfall and providing explicit-bounds and base-2 exponential View examples.
• Updates the README p99 PromQL snippet to state the explicit-bounds precondition inline.
• Adds an XML-doc <remarks> note on NatsCacheTelemetryNames.OperationDurationInstrumentName pointing consumers to AddView configuration.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/NatsDistributedCache/NatsCacheTelemetryNames.cs	Documents the histogram bucket-bound requirement directly on the instrument name constant for consumers configuring Views.
README.md	Adds a histogram bucket-configuration section and clarifies the p99 query’s prerequisite to avoid misleading quantile results.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.