top
import { Aside } from ‘@astrojs/starlight/components’;
The top command finds the most common values (or combinations of values) for the specified fields. It automatically counts occurrences and returns results sorted from most to least frequent. An optional by clause groups the results so you can find the top values within each group.
top is a fast way to profile your data and answer questions like “which services produce the most logs?” or “what are the most common error messages?”
Syntax
Section titled “Syntax”top [<N>] [top-options] <field-list> [by <group-field>]Arguments
Section titled “Arguments”| Argument | Required | Type | Default | Description |
|---|---|---|---|---|
<N> | No | Integer | 10 | The number of most-frequent values to return. |
<field-list> | Yes | Comma-delimited field names | — | The fields to find top values for. When multiple fields are specified, top finds the most common combinations. |
by <group-field> | No | Field name(s) | — | One or more fields to group the results by. Top values are computed separately within each group. |
showcount | No | Boolean | true | When true, includes a count column showing the frequency of each value. Set to false for cleaner output when counts are not needed. |
countfield | No | String | count | The name of the count column in the output. Only applies when showcount=true. |
Usage notes
Section titled “Usage notes”- Fast data profiling.
topis the quickest way to understand the distribution of values in a field. Use it early in an investigation to orient yourself. showcount=falsefor clean output. When you only need the values and not the frequencies, useshowcount=falseto remove the count column.- Multiple fields find top combinations. Specifying more than one field returns the most common value tuples. For example,
top service, severityreturns the most frequent (service, severity) pairs. - Use
byclause for per-group analysis. Thebyclause is powerful for comparative profiling, such as finding the top error message for each service. countfieldrenames the count column. Usecountfield='frequency'or similar to give the count column a descriptive name for downstream processing.
Examples
Section titled “Examples”Top services by log volume
Section titled “Top services by log volume”Find the services producing the most logs:
| top `resource.attributes.service.name`Top 5 severity levels
Section titled “Top 5 severity levels”Return only the 5 most common severity levels:
| top 5 severityTextTop severity by service
Section titled “Top severity by service”Find the most common severity level for each service:
| top 1 showcount=false severityText by `resource.attributes.service.name`Hide the count column
Section titled “Hide the count column”Return just the values without frequency counts:
| top showcount=false severityTextRename the count column
Section titled “Rename the count column”Use a custom name for the count field:
| top countfield='frequency' `resource.attributes.service.name`Extended examples
Section titled “Extended examples”Top service-severity combinations in OTel logs
Section titled “Top service-severity combinations in OTel logs”Find the most common combinations of service and severity. This reveals which services are noisiest and at what severity level:
| top 10 `resource.attributes.service.name`, severityTextTop span operations per OTel service
Section titled “Top span operations per OTel service”Find the most frequently executed operations in each service from trace data:
source = otel-v1-apm-span-*| top 3 name by serviceNameThis helps identify hot paths in your microservices architecture — the operations that execute most frequently are often the best candidates for optimization.
See also
Section titled “See also”- rare - The inverse of
top: find the least common values - stats - For more complex aggregations beyond simple frequency counts
- dedup - Deduplicate to get unique values with sample documents
- head - Limit the number of results returned
- PPL Command Reference - All PPL commands