percentiles_array
This page explains how to use the percentiles_array function in APL.
Use the percentiles_array aggregation function in APL to calculate multiple percentile values over a numeric expression in one pass. This function is useful when you want to understand the distribution of numeric data points, such as response times or durations, by summarizing them at several key percentiles like the 25th, 50th, and 95th.
You can use percentiles_array to:
- Analyze latency or duration metrics across requests or operations.
- Identify performance outliers.
- Visualize percentile distributions in dashboards.
Usage
Syntax
percentiles_array(Field, Percentile1, Percentile2, ...)Parameters
Fieldis the name of the field for which you want to compute percentile values.Percentile1,Percentile2,...are numeric percentile values between 0 and 100.
Returns
An array of numbers where each element is the value at the corresponding percentile.
Use case examples
Use percentiles_array to understand the spread of request durations per HTTP method, highlighting performance variability.
Query
['sample-http-logs']
| summarize percentiles_array(req_duration_ms, 25, 50, 95) by methodOutput
| method | P25 | P50 | P95 |
|---|---|---|---|
| GET | 0.3981 ms | 0.7352 ms | 1.981 ms |
| POST | 0.3261 ms | 0.7162 ms | 2.341 ms |
| PUT | 0.3324 ms | 0.7772 ms | 1.341 ms |
| DELETE | 0.2332 ms | 0.4652 ms | 1.121 ms |
This query calculates the 25th, 50th, and 95th percentiles of request durations for each HTTP method. It helps identify performance differences between different methods.
Use percentiles_array to analyze the distribution of span durations by service to detect potential bottlenecks.
Query
['otel-demo-traces']
| summarize percentiles_array(duration, 50, 90, 99) by ['service.name']Output
| service.name | P50 | P90 | P99 | P99 |
|---|---|---|---|---|
| recommendationservice | 1.96 ms | 2.965 ms | 3.477 ms | 3.477 ms |
| frontendproxy | 3.767 ms | 13.101 ms | 39.735 ms | 39.735 ms |
| shippingservice | 2.119 ms | 3.085 ms | 9.739 ms | 9.739 ms |
| checkoutservice | 1.454 ms | 12.342 ms | 29.542 ms | 29.542 ms |
This query shows latency patterns across services by computing the median, 90th, and 99th percentile of span durations.
Use percentiles_array to assess outlier response times per status code, which can reveal abnormal activity or service issues.
Query
['sample-http-logs']
| summarize percentiles_array(req_duration_ms, 50, 95, 99) by statusOutput
| status | P50 | P95 | P99 |
|---|---|---|---|
| 200 | 0.7352 ms | 1.981 ms | 2.612 ms |
| 201 | 0.7856 ms | 1.356 ms | 2.234 ms |
| 301 | 0.8956 ms | 1.547 ms | 2.546 ms |
| 500 | 0.6587 ms | 1.856 ms | 2.856 ms |
This query helps identify whether requests resulting in errors (like 500) are significantly slower than successful ones.
List of related functions
- avg: Returns the average value. Use it when a single central tendency is sufficient.
- percentile: Returns a single percentile value. Use it when you only need one percentile.
- percentile_if: Returns a single percentile value for the records that satisfy a condition.
- percentiles_arrayif: Returns an array of percentile values for the records that satisfy a condition.
- sum: Returns the sum of a numeric column.