---
name: "lttng-periodtop"
section: "1"
platform: "linux"
package: "python3-lttnganalyses"
version: "0.6.1-3"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/lttng-periodtop"
---

# lttng-periodtop(1)

LTTng analyses period top

## NAME

lttng-periodtop - LTTng analyses period top

## DESCRIPTION

usage: lttng-periodtop \[-h\] \[-r REFRESH\] \[--gmt\] \[--skip-validation\]

- \[--begin BEGIN\] \[--end END\] \[--period PERIOD\]

  \[--period-captures PERIOD\_CAPTURES\] \[--period-begin PERIOD\_BEGIN\] \[--period-end PERIOD\_END\] \[--period-begin-key PERIOD\_BEGIN\_KEY\] \[--period-end-key PERIOD\_END\_KEY\] \[--period-key-value PERIOD\_KEY\_VALUE\] \[--cpu CPU\] \[--timerange TIMERANGE\] \[--progress-use-size\] \[--no-intersection\] \[-V\] \[--debug\] \[--no-color\] \[--no-progress\] \[--min MIN\] \[--max MAX\] \[--freq\] \[--freq-resolution FREQ\_RESOLUTION\] \[--freq-uniform\] \[--freq-series\] \[--limit LIMIT\] \[--top\] \[--log\] \[--stats\] \[--min-duration MIN\_DURATION\] \[--max-duration MAX\_DURATION\] \[--aggregate-by AGGREGATE\_BY\] \[--select SELECT\] \[--group-by GROUP\_BY\] \[--order-by ORDER\_BY\] \<path/to/trace\>

The periods command.

### positional arguments:

- \<path/to/trace\>

  trace path

### optional arguments:

- **-h**, **--help**

  show this help message and exit

- **-r** REFRESH, **--refresh** REFRESH

  Refresh period, with optional units suffix (default units: s)

- **--gmt**

  Manipulate timestamps based on GMT instead of local time

- **--skip-validation**

  Skip the trace validation

- **--begin** BEGIN

  start time: hh:mm:ss\[.nnnnnnnnn\]

- **--end** END

  end time: hh:mm:ss\[.nnnnnnnnn\]

- **--period** PERIOD

  Period definition

- **--period-captures** PERIOD\_CAPTURES

  Period captures definition

- **--period-begin** PERIOD\_BEGIN

  Analysis period start marker event name

- **--period-end** PERIOD\_END

  Analysis period end marker event name (requires **--period-begin**)

- **--period-begin-key** PERIOD\_BEGIN\_KEY

  Optional, list of event field names used to match period markers (default: cpu\_id)

- **--period-end-key** PERIOD\_END\_KEY

  Optional, list of event field names used to match period marker. If none specified, use the same **--period-begin-key**

- **--period-key-value** PERIOD\_KEY\_VALUE

  Optional, define a fixed key value to which a period must correspond to be considered.

- **--cpu** CPU

  Filter the results only for this list of CPU IDs

- **--timerange** TIMERANGE

  time range: \[begin,end\]

- **--progress-use-size**

  use trace size to approximate progress

- **--no-intersection**

  disable stream intersection mode

- **-V**, **--version**

  show program's version number and exit

- **--debug**

  Enable debug mode (or set LTTNG\_ANALYSES\_DEBUG environment variable)

- **--no-color**

  Disable colored output

- **--no-progress**

  Don't display the progress bar

- **--min** MIN

  Filter out durations shorter than min usec

- **--max** MAX

  Filter out durations longer than max usec

- **--freq**

  Output statistics about periods durations

- **--freq-resolution** FREQ\_RESOLUTION

  Frequency distribution resolution (default 20)

- **--freq-uniform**

  Use a uniform resolution across distributions

- **--freq-series**

  Consolidate frequency distribution histogram as a single one

- **--limit** LIMIT

  Limit to top X (default = 10)

- **--top**

  Output the top sched switch durations

- **--log**

  Output the sched switches in chronological order

- **--stats**

  Output sched switch statistics

- **--min-duration** MIN\_DURATION

  Filter out, periods shorter that duration (usec)

- **--max-duration** MAX\_DURATION

  Filter out, periods longer than duration (usec)

- **--aggregate-by** AGGREGATE\_BY

  FIXME

- **--select** SELECT

  FIXME

- **--group-by** GROUP\_BY

  Present the results grouped by a list of fields(period.captured\_field\[, period.captured\_field2\])

- **--order-by** ORDER\_BY

  hierarchy, time