Enable self-adjusting (native) histogram buckets for all duration metrics

[Soumya8898]

Summary

Closes #1274

This PR enables Prometheus native histogram collection on all duration-based histogram metrics across the Token SDK. Native histograms use exponentially-spaced buckets that self-adjust at scrape time, providing significantly better percentile accuracy (especially p99/p999) without requiring operators to hand-tune bucket boundaries.

What was done

• Defined a defaultNativeHistogramBucketFactor constant (1.1) representing schema=3 exponential bucketing (~9% growth between bucket boundaries).
• Set NativeHistogramBucketFactor: 1.1 and NativeHistogramMaxBucketNumber: 100 on every duration-based HistogramOpts across all SDK services:
  • TTX service (endorsement, audit approval, ordering durations)
  • TTX finality (on-status duration)
  • Auditor (audit duration, append duration)
  • Certifier (certification request duration)
  • Sherdlock selector (selection duration)
  • Fabricx finality queue (processing duration)
  • ZKATDLog (ZK issue and transfer proof durations)
• Intentionally excluded ImmediateRetries histogram since it tracks a discrete integer distribution (0–5) where native histograms provide no benefit.
• The configuration runs in dual mode: both classic fixed buckets and native exponential buckets are emitted simultaneously, so existing dashboards and alerts continue working without any changes.

Why native histograms

Fixed buckets (e.g., [0.005, 0.01, 0.025, ...]) create blind spots. If a real p99 sits at 7.3s but the nearest bucket boundaries are 5s and 10s, Prometheus can only report something between 5–10s. Native histograms eliminate this by using fine-grained exponential boundaries that cover the full value range without configuration.

[Soumya8898]

Hi @adecaro
I’ve raised the PR with the changes, but it depends on a PR raised in FSC. Once that is reviewed and released in the next version, we’ll be able to use it.

For local testing with the FSC changes, I made some temporary modifications, which is why there are merge conflicts. Should we wait for the FSC PR to be released before proceeding?

I’ve also added steps outlining what to follow after the FSC release. In the meantime, would you prefer that we remove the local changes and keep only the required updates, then merge once the release is available? Or is there another approach you’d suggest?

[adecaro]

Hi @Soumya8898 , thanks for the effort 🙏
I have reviewed and approved the PR on the smart client. Let's wait @mbrandenburger for a second checks and then we should good to go 😄

[adecaro]

Hi @Soumya8898 , hyperledger-labs/fabric-smart-client#1398 has been merged.
Please, update the PR. Many many thanks 🙏

[Soumya8898]

Yah it's merged, will update the pr. Thanks

[Soumya8898]

HI @adecaro I have a small doubt regarding how things work here between FSC and token-sdk, So as there is no tagged-release from FSC side for the merged PR hyperledger-labs/fabric-smart-client#1398 in FSC repo, So I tried the FSC dependency is pinned to a pseudo-version by targeting the exact commit. So is this the correct approach or I need to change it.

[adecaro]

HI @adecaro I have a small doubt regarding how things work here between FSC and token-sdk, So as there is no tagged-release from FSC side for the merged PR hyperledger-labs/fabric-smart-client#1398 in FSC repo, So I tried the FSC dependency is pinned to a pseudo-version by targeting the exact commit. So is this the correct approach or I need to change it.

Targeting the exact commit is fine. When a new tag appears in FSC, we will update again the token-sdk and cut a tag too 😄

[adecaro]

Hi @Soumya8898 , great work. Thanks a lot for the effort 🙏

I'm wondering if, in another PR, we could offer the developer a way to customize these numbers. Just wondering 😅

[adecaro]

I think, there are other packages we can update:

Please, have a look 🙏

[Soumya8898]

Hi @Soumya8898 , great work. Thanks a lot for the effort 🙏

I'm wondering if, in another PR, we could offer the developer a way to customize these numbers. Just wondering 😅

@adecaro That's a nice idea 😊 Let me work on that. One thing I'm thinking is that developers need to have some understanding of how things work in the Native Histograms case. So I'm considering adding a small amount of context around it, along with customization options for choosing the variables. I'll create another PR after implementing that.

[Soumya8898]

I think, there are other packages we can update:

Please, have a look 🙏

token/core/common/metrics - This is just a type alias file. It re-exports HistogramOpts from FSC. No actual histogram definitions/instances here. Nothing to change.

token/services/selector/sherdlock/mocks - These are auto-generated mock/fake files (counterfeiter). They reference HistogramOpts type in function signatures but don't define any histograms. The mocks will automatically pick up the new fields since HistogramOpts is a type alias. Nothing to change.

For all others I updated the packages

[adecaro]

LGTM

[adecaro]

Thanks much @Soumya8898 for double checking. I'll merge as soon as the PR gives the okay 🙏