[processor/transform] Create extract percentile transform function by alexcams · Pull Request #45518 · open-telemetry/opentelemetry-collector-contrib

alexcams · 2026-01-20T10:37:33Z

Description

The extract_percentile_metric function creates a new Gauge metric from a Histogram or ExponentialHistogram by calculating the specified percentile value from the bucket counts. A metric will only be created if there is at least one data point.

percentile is a float64 value between 0 and 100 representing the desired percentile to extract (e.g., 50 for median, 95 for p95, 99 for p99).

suffix is an optional string that defines the suffix for the metric name. By default, it is set to _p{percentile} (e.g., _p50, _p95, _p99).

Link to tracking issue

Closes #44316

Testing

Included unit tests and tested manually with this configuration:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  debug:
    verbosity: detailed
    sampling_initial: 10000
    sampling_thereafter: 10000

processors:
  transform:
    error_mode: ignore
    metric_statements:
      - context: metric
        statements:
          - extract_percentile_metric(50.0)
          - extract_percentile_metric(95.0)
          - extract_percentile_metric(99.0, "_p99_custom")

service:
  telemetry:
    metrics:
      level: none
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [transform]
      exporters:
        - debug

tested with telemetrygen tool with params to generate regular histogram metrics:

./bin/telemetrygen_darwin_arm64 metrics \                    ok | 14:34:29 
  --otlp-insecure \
  --otlp-endpoint localhost:4317 \
  --metrics 1 \
  --otlp-attributes 'service.name="histogram-service"' \
  --metric-type Histogram \
  --otlp-metric-name "http.server.duration"

Obtained output:

Metric #1
Descriptor:
     -> Name: http.server.duration_p50
     -> Description:  (p50)
     -> Unit: 
     -> DataType: Gauge
NumberDataPoints #0
StartTimestamp: 2026-01-20 13:34:29.409727 +0000 UTC
Timestamp: 2026-01-20 13:34:29.409727 +0000 UTC
Value: 137.500000
Metric #2
Descriptor:
     -> Name: http.server.duration_p95
     -> Description:  (p95)
     -> Unit: 
     -> DataType: Gauge
NumberDataPoints #0
StartTimestamp: 2026-01-20 13:34:29.409727 +0000 UTC
Timestamp: 2026-01-20 13:34:29.409727 +0000 UTC
Value: 750.000000
Metric #3
Descriptor:
     -> Name: http.server.duration_p99_custom
     -> Description:  (p99)
     -> Unit: 
     -> DataType: Gauge
NumberDataPoints #0
StartTimestamp: 2026-01-20 13:34:29.409727 +0000 UTC
Timestamp: 2026-01-20 13:34:29.409727 +0000 UTC
Value: 750.000000 # p99 is placed in last bucket which is [bucket_lower_bound, + Inf ]. Cannot interpolate with Inf values so it is necessary to use lowerbound (750)

Tested with Exponential histogram as well:

./bin/telemetrygen_darwin_arm64 metrics \                    ok | 14:42:11 
  --otlp-insecure \
  --otlp-endpoint localhost:4317 \
  --metrics 1 \
  --otlp-attributes 'service.name="histogram-service"' \
  --metric-type ExponentialHistogram \
  --otlp-metric-name "http.server.duration"

and got the output:

Metric #1
Descriptor:
     -> Name: http.server.duration_p50
     -> Description:  (p50)
     -> Unit: 
     -> DataType: Gauge
NumberDataPoints #0
StartTimestamp: 2026-01-20 13:42:11.599314 +0000 UTC
Timestamp: 2026-01-20 13:42:11.599315 +0000 UTC
Value: 545.301038
Metric #2
Descriptor:
     -> Name: http.server.duration_p95
     -> Description:  (p95)
     -> Unit: 
     -> DataType: Gauge
NumberDataPoints #0
StartTimestamp: 2026-01-20 13:42:11.599314 +0000 UTC
Timestamp: 2026-01-20 13:42:11.599315 +0000 UTC
Value: 961.465253
Metric #3
Descriptor:
     -> Name: http.server.duration_p99_custom
     -> Description:  (p99)
     -> Unit: 
     -> DataType: Gauge
NumberDataPoints #0
StartTimestamp: 2026-01-20 13:42:11.599314 +0000 UTC
Timestamp: 2026-01-20 13:42:11.599315 +0000 UTC
Value: 1024.000000

Documentation

Added proper documentation to transform processor README.md.

alexcams · 2026-01-20T13:18:14Z

/rerun

atoulme

some nits, LGTM - needs a codeowner review.

alexcams · 2026-02-04T08:01:49Z

/rerun

edmocosta

Thank you for working on this @alexcams, I've to admit it's not so easy for me to review this PR as the logic is a bit complex! I've left a few questions/suggestions related to that, and I'm glad to discuss it further :)

alexcams · 2026-02-10T08:43:35Z

/rerun

github-actions · 2026-02-26T05:38:14Z

This PR was marked stale due to lack of activity. It will be closed in 14 days.

github-actions · 2026-04-01T05:52:24Z

This PR was marked stale due to lack of activity. It will be closed in 14 days.

Co-authored-by: Edmo Vamerlatti Costa <11836452+edmocosta@users.noreply.github.com>

…r easier understanding

edmocosta

LGTM! Great work, @alexcams! 👏

edmocosta · 2026-04-13T16:03:54Z

@evan-bradley @TylerHelmuth @bogdandrutu I'm planning to merge it by Friday, please let me know if you want to review it, or if you need more time for that. Thank you!

otelbot · 2026-04-17T14:37:01Z

Thank you for your contribution @alexcams! 🎉 We would like to hear from you about your experience contributing to OpenTelemetry by taking a few minutes to fill out this survey. If you are getting started contributing, you can also join the CNCF Slack channel #opentelemetry-new-contributors to ask for guidance and get help.

…pen-telemetry#45518)  #### Description The `extract_percentile_metric` function creates a new Gauge metric from a Histogram or ExponentialHistogram by calculating the specified percentile value from the bucket counts. A metric will only be created if there is at least one data point. `percentile` is a float64 value between 0 and 100 representing the desired percentile to extract (e.g., 50 for median, 95 for p95, 99 for p99). `suffix` is an optional string that defines the suffix for the metric name. By default, it is set to `_p{percentile}` (e.g., `_p50`, `_p95`, `_p99`).  #### Link to tracking issue Closes open-telemetry#44316  #### Testing Included unit tests and tested manually with this configuration: ``` yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 exporters: debug: verbosity: detailed sampling_initial: 10000 sampling_thereafter: 10000 processors: transform: error_mode: ignore metric_statements: - context: metric statements: - extract_percentile_metric(50.0) - extract_percentile_metric(95.0) - extract_percentile_metric(99.0, "_p99_custom") service: telemetry: metrics: level: none pipelines: metrics: receivers: [otlp] processors: [transform] exporters: - debug ``` tested with `telemetrygen` tool with params to generate regular histogram metrics: ``` ./bin/telemetrygen_darwin_arm64 metrics \ ok | 14:34:29 --otlp-insecure \ --otlp-endpoint localhost:4317 \ --metrics 1 \ --otlp-attributes 'service.name="histogram-service"' \ --metric-type Histogram \ --otlp-metric-name "http.server.duration" ``` Obtained output: ``` Metric open-telemetry#1 Descriptor: -> Name: http.server.duration_p50 -> Description: (p50) -> Unit: -> DataType: Gauge NumberDataPoints #0 StartTimestamp: 2026-01-20 13:34:29.409727 +0000 UTC Timestamp: 2026-01-20 13:34:29.409727 +0000 UTC Value: 137.500000 Metric open-telemetry#2 Descriptor: -> Name: http.server.duration_p95 -> Description: (p95) -> Unit: -> DataType: Gauge NumberDataPoints #0 StartTimestamp: 2026-01-20 13:34:29.409727 +0000 UTC Timestamp: 2026-01-20 13:34:29.409727 +0000 UTC Value: 750.000000 Metric open-telemetry#3 Descriptor: -> Name: http.server.duration_p99_custom -> Description: (p99) -> Unit: -> DataType: Gauge NumberDataPoints #0 StartTimestamp: 2026-01-20 13:34:29.409727 +0000 UTC Timestamp: 2026-01-20 13:34:29.409727 +0000 UTC Value: 750.000000 # p99 is placed in last bucket which is [bucket_lower_bound, + Inf ]. Cannot interpolate with Inf values so it is necessary to use lowerbound (750) ``` Tested with Exponential histogram as well: ``` ./bin/telemetrygen_darwin_arm64 metrics \ ok | 14:42:11 --otlp-insecure \ --otlp-endpoint localhost:4317 \ --metrics 1 \ --otlp-attributes 'service.name="histogram-service"' \ --metric-type ExponentialHistogram \ --otlp-metric-name "http.server.duration" ``` and got the output: ``` Metric open-telemetry#1 Descriptor: -> Name: http.server.duration_p50 -> Description: (p50) -> Unit: -> DataType: Gauge NumberDataPoints #0 StartTimestamp: 2026-01-20 13:42:11.599314 +0000 UTC Timestamp: 2026-01-20 13:42:11.599315 +0000 UTC Value: 545.301038 Metric open-telemetry#2 Descriptor: -> Name: http.server.duration_p95 -> Description: (p95) -> Unit: -> DataType: Gauge NumberDataPoints #0 StartTimestamp: 2026-01-20 13:42:11.599314 +0000 UTC Timestamp: 2026-01-20 13:42:11.599315 +0000 UTC Value: 961.465253 Metric open-telemetry#3 Descriptor: -> Name: http.server.duration_p99_custom -> Description: (p99) -> Unit: -> DataType: Gauge NumberDataPoints #0 StartTimestamp: 2026-01-20 13:42:11.599314 +0000 UTC Timestamp: 2026-01-20 13:42:11.599315 +0000 UTC Value: 1024.000000 ```  #### Documentation Added proper documentation to transform processor `README.md`.  --------- Co-authored-by: Edmo Vamerlatti Costa <11836452+edmocosta@users.noreply.github.com>

alexcams requested review from a team, TylerHelmuth, bogdandrutu, edmocosta and evan-bradley as code owners January 20, 2026 10:37

github-actions Bot assigned dehaansa Jan 20, 2026

github-actions Bot added the processor/transform Transform processor label Jan 20, 2026

alexcams changed the title ~~Create extract percentile transform function~~ [processor/transform] Create extract percentile transform function Jan 20, 2026

alexcams mentioned this pull request Jan 20, 2026

[processor/transform] support extracting a percentile gauge from a histogram metric #44316

Closed

alexcams commented Jan 28, 2026

View reviewed changes

Comment thread processor/transformprocessor/internal/metrics/func_extract_percentile_metric.go

atoulme reviewed Jan 28, 2026

View reviewed changes

Comment thread processor/transformprocessor/internal/metrics/func_extract_percentile_metric.go Outdated

atoulme reviewed Jan 28, 2026

View reviewed changes

Comment thread processor/transformprocessor/internal/metrics/func_extract_percentile_metric.go

atoulme approved these changes Jan 28, 2026

View reviewed changes

atoulme added the waiting-for-code-owners label Jan 28, 2026

iblancasa approved these changes Feb 6, 2026

View reviewed changes

edmocosta reviewed Feb 6, 2026

View reviewed changes

edmocosta reviewed Feb 9, 2026

View reviewed changes

github-actions Bot added the Stale label Feb 26, 2026

edmocosta removed the Stale label Feb 26, 2026

edmocosta reviewed Mar 9, 2026

View reviewed changes

alexcams requested a review from edmocosta March 11, 2026 16:16

edmocosta reviewed Mar 16, 2026

View reviewed changes

Comment thread processor/transformprocessor/README.md Outdated

github-actions Bot added the Stale label Apr 1, 2026

edmocosta removed the Stale label Apr 1, 2026

edmocosta reviewed Apr 1, 2026

View reviewed changes

Comment thread processor/transformprocessor/internal/metrics/func_extract_percentile_metric.go

alexcams and others added 12 commits April 7, 2026 15:25

Merged zerobucket exclusive if statements into if else

1717fdf

Solved first round of comments

56bd65b

Rversed negative bucket iteration from most to least negative

6b0d698

Solve lint issue

2b8d3d4

Applied suggestions

380e8c7

Remove unneded generics

fbadba8

Added default case in test validation function

556bcc2

simplify negative bucket interpolation

529fd1f

skip empty histograms

40a5a36

Handle malformed histograms as errors

e74ec4f

Update processor/transformprocessor/README.md

9f38009

Co-authored-by: Edmo Vamerlatti Costa <11836452+edmocosta@users.noreply.github.com>

Handle single bucket histogram without explicit bounds

cf8766e

alexcams force-pushed the create-extract-percentile-transform-function branch from 1b646e3 to cf8766e Compare April 7, 2026 13:29

Merge branch 'main' into create-extract-percentile-transform-function

b8f3668

alexcams requested a review from edmocosta April 8, 2026 09:01

Merge branch 'main' into create-extract-percentile-transform-function

9c00404

edmocosta reviewed Apr 10, 2026

View reviewed changes

Comment thread processor/transformprocessor/internal/metrics/func_extract_percentile_metric.go

Comment thread processor/transformprocessor/internal/metrics/func_extract_percentile_metric.go Outdated

Comment thread processor/transformprocessor/internal/metrics/func_extract_percentile_metric.go

Added edge case documentation to README.md and modified code parts fo…

f33a54c

…r easier understanding

alexcams force-pushed the create-extract-percentile-transform-function branch from 4262fdd to f33a54c Compare April 13, 2026 07:59

alexcams requested a review from edmocosta April 13, 2026 14:01

edmocosta reviewed Apr 13, 2026

View reviewed changes

Comment thread processor/transformprocessor/README.md

Keep transformprocessor README metrics docs ordered alphabetically

a408ebc

alexcams requested a review from edmocosta April 13, 2026 15:17

edmocosta approved these changes Apr 13, 2026

View reviewed changes

edmocosta merged commit 42b10c2 into open-telemetry:main Apr 17, 2026
191 checks passed

alexcams mentioned this pull request Apr 22, 2026

REQUEST: New membership for alexcams open-telemetry/community#3379

Closed

6 tasks

Conversation

alexcams commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Link to tracking issue

Testing

Documentation

Uh oh!

alexcams commented Jan 20, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

atoulme left a comment

Choose a reason for hiding this comment

Uh oh!

alexcams commented Feb 4, 2026

Uh oh!

edmocosta left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexcams commented Feb 10, 2026

Uh oh!

github-actions Bot commented Feb 26, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edmocosta left a comment

Choose a reason for hiding this comment

Uh oh!

edmocosta commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

otelbot Bot commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

alexcams commented Jan 20, 2026 •

edited

Loading

edmocosta commented Apr 13, 2026 •

edited

Loading