Kernel trace analysis

Introduction

LISA comes with a plethora of analysis functions based on Ftrace traces. We convert the trace events into pandas.DataFrame which are suited to handling mid-sized data sets.

Trace

Our Trace takes an Ftrace trace.dat file as input (Systrace trace.html are also accepted, but mileage may vary since it’s an intrinsically ambiguous format), and provides access to both the raw trace events, as well as some new pandas.DataFrame built from analysing and aggregating trace events.

You can create one like so:

trace = Trace("path/to/trace.dat")

Raw trace events can be accessed like this:

trace.df_event("sched_switch")

Whereas analysis dataframes can be obtained like that:

# trace.ana.<analysis name>.<analysis method>
trace.ana.tasks.df_tasks_states()

See also

See the Trace documentation for more details.

Available analysis

Dataframes

The majority of these dataframes are time-indexed (and if they aren’t, it will be called out in the docstring). This makes it easy to create dataframe slices to study specific trace windows.

Plots

When run in a notebook, these plots will be displayed automatically. By default, they are also saved in the same directory as your trace.dat

cpus:plot_context_switches()
cpus:plot_orig_capacity()
frequency:plot_cpu_frequencies()
frequency:plot_cpu_frequency_residency()
frequency:plot_cpu_frequency_transitions()
frequency:plot_domain_frequencies()
frequency:plot_domain_frequency_residency()
frequency:plot_domain_frequency_transitions()
frequency:plot_peripheral_frequency()
functions_json:plot_profiling_stats()
idle:plot_cluster_idle_state_residency()
idle:plot_clusters_idle_state_residency()
idle:plot_cpu_idle_state_residency()
latency:plot_activations()
latency:plot_latencies_cdf()
latency:plot_latencies_histogram()
latency:plot_latencies()
latency:plot_latency_bands()
latency:plot_runtimes()
load_tracking:plot_cpus_signals()
load_tracking:plot_task_placement()
load_tracking:plot_task_required_capacity()
load_tracking:plot_task_signals()
notebook:plot_event_field()
pixel6:plot_power_meter()
rta:plot_latency()
rta:plot_perf_index_histogram()
rta:plot_perf()
rta:plot_phases()
rta:plot_slack_histogram()
status:plot_overutilized()
tasks:plot_task_activation()
tasks:plot_task_residency()
tasks:plot_task_total_residency()
tasks:plot_tasks_activation()
tasks:plot_tasks_forks_heatmap()
tasks:plot_tasks_forks()
tasks:plot_tasks_total_residency()
tasks:plot_tasks_wakeups_heatmap()
tasks:plot_tasks_wakeups()
thermal:plot_cpu_cooling_states()
thermal:plot_dev_freq_cooling_states()
thermal:plot_thermal_zone_temperature()

API

Trace

class lisa.trace.Trace(*args, df_fmt=None, **kwargs)[source]

Bases: TraceBase

This class provides a way to access event dataframes and ties together various low-level moving pieces to make that happen.

Parameters:

trace_path (str or None) – File containing the trace
events (TraceEventCheckerBase or list(str) or None) –
events to be parsed. Since events can be loaded on-demand, that is optional but still recommended to improve trace parsing speed.

See also

lisa.trace.TraceBase.df_event() for event formats accepted.
events_namespaces (list(str or None)) – List of namespaces of the requested events. Each namespace will be tried in order until the event is found. The None namespace can be used to specify no namespace. The full event name is formed with <namespace>__<event>.
strict_events (bool) – When True, all the events specified in events have to be present, and any other events will be assumed to not be present. This allows early failure and avoid the cost of lazy detection of events in very large traces.
plat_info (lisa.platforms.platinfo.PlatformInfo) – Platform info describing the target that this trace was collected on.
normalize_time (bool) – Make the first timestamp in the trace 0 instead of the system timestamp that was captured when tracing.
parser (object or None) – Optional trace parser to use as a backend. It must implement the API defined by TraceParserBase, and will be called as parser(path=trace_path, events=events, needed_metadata={'time-range', ...}) with the events that should be parsed. Other parameters must either have default values, or be pre-assigned using partially-applied constructor (for subclasses of lisa.utils.PartialInit) or functools.partial(). By default, .txt files will be assumed to be in human-readable format output directly by the kernel (or trace-cmd report without -R). Support for this format is limited and some events might not be parsed correctly (or at least without custom event parsers).
plots_dir (str) – directory where to save plots
sanitization_functions (object) – This parameter is only for backward compatibility with existing code, use lisa.trace.TraceBase.get_view() with process_df parameter instead.
max_mem_size (int or None) – Maximum memory usage to be used for dataframe cache. Note that the peak memory usage can exceed that, as the cache can not forcefully evict an object from memory (it can only drop references to it). When None, use illimited amount of memory.
swap_dir (str or None) – Swap directory used to store dataframes evicted from the cache. When None, a hidden directory along the trace file is used.
enable_swap (bool) – If True, the on-disk swap is enabled.
max_swap_size (int or None) – Maximum size of the swap directory. When None, the max size is the size of the trace file.

Attributes:

start: The timestamp of the first trace event in the trace
end: The timestamp of the last trace event in the trace
time_range: Maximum timespan for all collected events
window: Conveniency tuple of (start, end).
available_events: Events available in the parsed trace, exposed as some kind of set-ish smart container. Querying for event might trigger the parsing of it.
ana: The analysis proxy used as an entry point to run analysis methods on the trace. See lisa.analysis._proxy.AnalysisProxy.

Supporting more events:

Subclasses of TraceParserBase can usually auto-detect the event format, but there may be a number of reasons to pass a custom event parser:

The event format produced by a given kernel differs from the description bundled with the parser, leading to incorrect parse (missing field).

The event cannot be parsed in raw format in case text output of trace-cmd is used, because of a const char* field displayed as a pointer for example.

See also

For events not following the regular field syntax, use CustomFieldsTxtEventParser

Automatic detection can take a heavy performance toll. This is why parsers needing descriptions will come with pre-defined descritption of most used events.

Custom event parsers can be passed as extra parameters to the parser, which can be set manually:

# Event parsers provided by TxtTraceParser can also be overridden
# with user-provided ones in case they fail to parse what a given
# kernel produced
event_parsers = [
    TxtEventParser('foobar', fields={'foo': int, 'bar': 'string'}, raw=True)
]

# Pre-fill the "event_parsers" parameter of
# TxtEventParser.from_dat() using a partial application.
#
# Note: you need to choose the parser appropriately for the
# format of the trace, since the automatic filetype detection is
# bypassed.
parser = TxtTraceParser.from_dat(event_parsers=event_parsers)
trace = Trace('foobar.dat', parser=parser)

Warning

Custom event parsers that are not types or functions (such as partially-applied values) will tie the on-disc swap entries to the parser Trace instance, incurring higher pandas.DataFrame load time when a new Trace object is created.

property ana

property analysis

get_view(window=None, *, df_fmt=None, **kwargs)[source]

Get a view on a trace cropped time-wise to fit in window and with event dataframes post processed with process_df.

Parameters:

window (tuple(float or None, float or None) or None) – Crop the dataframe to include events that are inside the given window. This includes the event immediately preceding the left boundary if there is no exact timestamp match. This can also include more rows before the beginning of the window based on the signals required by the user. A None boundary will extend to the beginning/end of the trace.
signals (list(lisa.datautils.SignalDesc) or None) – List of lisa.datautils.SignalDesc to use when selecting rows before the beginning of the window. This allows ensuring that all the given signals have a known value at the beginning of the window.
compress_signals_init (bool or None) – If True, the timestamp of the events before the beginning of the window will be compressed to be either right before the beginning of the window, or at the exact timestamp of the beginning of the window (depending on the dataframe library chosen, since pandas cannot cope with more than one row for each timestamp).
normalize_time (bool or None) – If True, the beginning of the window will become timestamp 0. If no window is used, the beginning of the trace is taken as T=0. This allows easier comparison of traces that were generated with absolute timestamps (e.g. timestamp related to the uptime of the system). It also allows comparing various slices of the same trace.
events_namespaces (list(str or None)) – List of namespaces of the requested events. Each namespace will be tried in order until the event is found. The None namespace can be used to specify no namespace. The full event name is formed with <namespace>__<event>.
events (list(str) or lisa.trace.TraceEventCheckerBase or None) – Preload the given events when creating the view. This can be advantageous as a single instance of the parser will be spawned, so if the parser supports it, multiple events will be parsed in one trace traversal.
strict_events – If True, will raise an exception if the events specified cannot be loaded from the trace. This allows failing early in trace processing.
strict_events – bool or None
process_df (Callable[[str, polars.LazyFrame], polars.LazyFrame] or None) –
Function called on each dataframe returned by lisa.trace.TraceBase.df_event(). The parameters are as follow:
1. Name of the event being queried.
2. A polars.LazyFrame of the event.
It is expected to return a polars.LazyFrame as well.
df_fmt (str or None) –
Format of the dataframes returned by lisa.trace.TraceBase.df_events(). One of:
- "pandas": pandas.DataFrame.
- "polars-lazyframe": polars.LazyFrame.
- None: defaults to "pandas" for backward-compatibility.

Variable arguments:

Forwarded to the contructor of the view.

property trace_state

State of the trace object that might impact the output of dataframe getter functions like lisa.trace.TraceBase.df_event().

It must be hashable and serializable to JSON, so that it can be recorded when analysis methods results are cached to the swap.

df_event(event, *, df_fmt=None, **kwargs)[source]

Get a dataframe containing all occurrences of the specified trace event in the parsed trace.

Parameters:

event (str) –
Trace event name.

In addition to actual events, the following formats for meta events are supported:
- trace_printk@: The event format is described by the bprint event format string, and the field values are decoded from the variable arguments buffer. Note that:
  - The field values must be in the buffer, i.e. the format string is only used as the event format, no “literal value” will be extracted from it.
  - The event must have fields. If not, trace_printk() will emit a bputs event that will be ignored at the moment. We need to get a bprint event.
  - Field names must be unique.
```
// trace.df_event('trace_printk@myevent')
void foo(void) {
    trace_printk("myevent: field1=%s field2=%i", "foo", 42);
}
```
- userspace@: the event is generated by userspace:
```
# trace.df_event('userspace@myevent')
echo "myevent: field1=foo field2=42" > /sys/kernel/debug/tracing/trace_marker
```
  Note that the field names must be unique.
Note

All meta event names are expected to be valid C language identifiers. Usage of other characters will prevent correct parsing.
signals (list(SignalDesc)) – List of signals to fixup if signals_init == True. If left to None, lisa.datautils.SignalDesc.from_event() will be used to infer a list of default signals.
compress_signals_init (bool) – Give a timestamp very close to the beginning of the sliced dataframe to rows that are added by signals_init. This allows keeping a very close time span without introducing duplicate indices.

classmethod from_target(target, events=None, buffer_size=10240, filepath=None, **kwargs)[source]

Context manager that can be used to collect a lisa.trace.TraceBase directly from a lisa.target.Target without needing to setup an FtraceCollector.

Example:

from lisa.trace import Trace
from lisa.target import Target

target = Target.from_default_conf()

with Trace.from_target(target, events=['sched_switch', 'sched_wakeup']) as trace:
    target.execute('echo hello world')
    # DO NOT USE trace object inside the `with` statement

trace.ana.tasks.plot_tasks_total_residency(filepath='plot.png')

Parameters:

target (Target) – Target to connect to.
events (list(str)) – ftrace events to collect and parse in the trace.
buffer_size (int) – Size of the ftrace ring buffer.
filepath (str or None) – If set, the trace file will be saved at that location. Otherwise, a temporary file is created and removed as soon as the parsing is finished.

Variable keyword arguments:

Forwarded to Trace.

classmethod get_event_sources(*args, **kwargs)[source]

Trace Parser Module

class lisa.trace.CPU

Bases: int

Alias to int used for CPU IDs

exception lisa.trace.MissingMetadataError(metadata)[source]

Bases: KeyError

Raised when a given metadata is not available.

class lisa.trace.MockTraceParser(*args, **kwargs)[source]

Bases: TraceParserBase

Mock parser that just returns the dataframes it was given.

Parameters:

dfs (dict(str, pandas.DataFrame)) – Dictionary of pandas.DataFrame for each event that the parser can handle.
path (str or None) – Useless for now, but it’s part of the Trace API, and it will be used for the dataframe cache as well.
events – Unused.
events – collections.abc.Iterable(str)
time_range (tuple(float, float)) – Time range of the trace in seconds. If not specified, the min and max timestamp of all dfs will be extracted, but it can lead to wrong analysis results (especially for signals that are not updated very often).

Variable keyword arguments:

Forwarded to TraceParserBase

As a subclass of lisa.utils.PartialInit, its constructor supports being applied to a partial set of parameters, leaving the rest to the internals of lisa.trace.Trace:

dfs = {
    'sched_wakeup': pd.DataFrame.from_records(
        [
            (0, 1, 1, 'task1', 'task1', 1, 1, 1),
            (1, 2, 1, 'task1', 'task1', 1, 1, 2),
            (2, 4, 2, 'task2', 'task2', 2, 1, 4),
        ],
        columns=('Time', '__cpu', '__pid', '__comm', 'comm', 'pid', 'prio', 'target_cpu'),
        index='Time',
    ),
}
trace = Trace(parser=MockTraceParser(dfs))
print(trace.df_event('sched_wakeup'))

parse_event(event)[source]

Parse the given event from the trace and return a pandas.DataFrame with the following columns:

Time index: floating point absolute timestamp in seconds. The index must not have any duplicated values.

One column per event field, with the appropriate dtype.

Columns prefixed with __: Header of each event, usually containing the following fields:

__cpu: CPU number the event was emitted from

__pid: PID of the current process scheduled at the time the event was emitted

__comm: Task command name going with __pid at the point the event was emitted

Parameters:: event (str) – name of the event to parse
Raises:: MissingTraceEventError – If the event cannot be parsed.

Note

The caller is free to modify the index of the data, and it must not affect other dataframes.

get_metadata(key)[source]

Return the metadata value.

Parameters:

key (str) –

Name of the metadata. Can be one of:

time-range: tuple (start, end) of the timestamps in the trace. This must be the first timestamp to appear in the trace, regardless of what events is being parsed. Otherwise, it would be impossible to use the time range of a parser in the mother TraceBase when requesting specific events.
symbols-address: Dictionnary of address (int) to symbol names in the kernel (str) that was used to create the trace. This allows resolving the fields of events that recorded addresses rather than function names.
cpus-count: Number of CPUs on the system the trace was collected on.
available-events: List of all available events stored in the trace. The list must be exhaustive, not limited to the events that were requested. If an exhaustive list cannot be gathered, this metadata should not be implemented.
trace-id: Unique identifier for that trace file used to
validate the cache. If not available, a checksum will be used.

Raises:

MissingMetadataError if the metadata is not available on that parser.

Note

A given metadata can only be expected to be available if asked for in the constructor, but bear in mind that there is no promise on the availability of any except for the following that must be provided if asked for:

time-range

Metadata may still be made available if not asked for, but only if it’s a very cheap byproduct of parsing that incurs no extra cost.

exception lisa.trace.TraceDumpError(errors, event=None, cmd=None)[source]

Bases: Exception

Exception containing errors forwarded from the trace-dump parser

class lisa.trace.TraceBase[source]

Bases: _InternalTraceBase

abstract df_event(event, **kwargs)[source]

Get a dataframe containing all occurrences of the specified trace event in the parsed trace.

Parameters:

event (str) –
Trace event name.

In addition to actual events, the following formats for meta events are supported:
- trace_printk@: The event format is described by the bprint event format string, and the field values are decoded from the variable arguments buffer. Note that:
  - The field values must be in the buffer, i.e. the format string is only used as the event format, no “literal value” will be extracted from it.
  - The event must have fields. If not, trace_printk() will emit a bputs event that will be ignored at the moment. We need to get a bprint event.
  - Field names must be unique.
```
// trace.df_event('trace_printk@myevent')
void foo(void) {
    trace_printk("myevent: field1=%s field2=%i", "foo", 42);
}
```
- userspace@: the event is generated by userspace:
```
# trace.df_event('userspace@myevent')
echo "myevent: field1=foo field2=42" > /sys/kernel/debug/tracing/trace_marker
```
  Note that the field names must be unique.
Note

All meta event names are expected to be valid C language identifiers. Usage of other characters will prevent correct parsing.
signals (list(SignalDesc)) – List of signals to fixup if signals_init == True. If left to None, lisa.datautils.SignalDesc.from_event() will be used to infer a list of default signals.
compress_signals_init (bool) – Give a timestamp very close to the beginning of the sliced dataframe to rows that are added by signals_init. This allows keeping a very close time span without introducing duplicate indices.

get_view(*args, **kwargs)[source]

Get a view on a trace cropped time-wise to fit in window and with event dataframes post processed with process_df.

Parameters:

window (tuple(float or None, float or None) or None) – Crop the dataframe to include events that are inside the given window. This includes the event immediately preceding the left boundary if there is no exact timestamp match. This can also include more rows before the beginning of the window based on the signals required by the user. A None boundary will extend to the beginning/end of the trace.
signals (list(lisa.datautils.SignalDesc) or None) – List of lisa.datautils.SignalDesc to use when selecting rows before the beginning of the window. This allows ensuring that all the given signals have a known value at the beginning of the window.
compress_signals_init (bool or None) – If True, the timestamp of the events before the beginning of the window will be compressed to be either right before the beginning of the window, or at the exact timestamp of the beginning of the window (depending on the dataframe library chosen, since pandas cannot cope with more than one row for each timestamp).
normalize_time (bool or None) – If True, the beginning of the window will become timestamp 0. If no window is used, the beginning of the trace is taken as T=0. This allows easier comparison of traces that were generated with absolute timestamps (e.g. timestamp related to the uptime of the system). It also allows comparing various slices of the same trace.
events_namespaces (list(str or None)) – List of namespaces of the requested events. Each namespace will be tried in order until the event is found. The None namespace can be used to specify no namespace. The full event name is formed with <namespace>__<event>.
events (list(str) or lisa.trace.TraceEventCheckerBase or None) – Preload the given events when creating the view. This can be advantageous as a single instance of the parser will be spawned, so if the parser supports it, multiple events will be parsed in one trace traversal.
strict_events – If True, will raise an exception if the events specified cannot be loaded from the trace. This allows failing early in trace processing.
strict_events – bool or None
process_df (Callable[[str, polars.LazyFrame], polars.LazyFrame] or None) –
Function called on each dataframe returned by lisa.trace.TraceBase.df_event(). The parameters are as follow:
1. Name of the event being queried.
2. A polars.LazyFrame of the event.
It is expected to return a polars.LazyFrame as well.
df_fmt (str or None) –
Format of the dataframes returned by lisa.trace.TraceBase.df_events(). One of:
- "pandas": pandas.DataFrame.
- "polars-lazyframe": polars.LazyFrame.
- None: defaults to "pandas" for backward-compatibility.

Variable arguments:

Forwarded to the contructor of the view.

df_events(*args, **kwargs)[source]: Attention

Deprecated since version 2.0.

df_events() is deprecated and will be removed in version 4.0, use df_event instead: This method has been deprecated and is an alias

abstract property ana

abstract property analysis

show()[source]

Open the parsed trace using the most appropriate native viewer.

The native viewer depends on the specified trace format: - ftrace: open using kernelshark - systrace: open using a browser

In both cases the native viewer is assumed to be available in the host machine.

get_task_name_pids(*args, **kwargs)[source]: Attention

Deprecated since version 3.0.

get_task_name_pids() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.get_task_name_pids instead: This method has been deprecated and is an alias

get_task_by_name(name)[source]: Attention

Deprecated since version 2.0.

get_task_by_name() is deprecated and will be removed in version 4.0, use lisa.trace.TraceBase.get_task_name_pids() instead: This method has been deprecated and is an alias

get_task_pid_names(*args, **kwargs)[source]: Attention

Deprecated since version 3.0.

get_task_pid_names() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.get_task_pid_names instead: This method has been deprecated and is an alias

get_task_by_pid(*args, **kwargs)[source]: Attention

Deprecated since version 3.0.

get_task_by_pid() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.get_task_by_pid instead: This method has been deprecated and is an alias

get_task_ids(*args, **kwargs)[source]: Attention

Deprecated since version 3.0.

get_task_ids() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.get_task_ids instead: This method has been deprecated and is an alias

get_task_id(*args, **kwargs)[source]: Attention

Deprecated since version 3.0.

get_task_id() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.get_task_id instead: This method has been deprecated and is an alias

get_task_pid(*args, **kwargs)[source]: Attention

Deprecated since version 3.0.

get_task_pid() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.get_task_pid instead: This method has been deprecated and is an alias

get_tasks(*args, **kwargs)[source]: Attention

Deprecated since version 3.0.

get_tasks() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.get_tasks instead: This method has been deprecated and is an alias

property task_ids: List of all the lisa.analysis.tasks.TaskID in the trace, sorted by PID.

Attention

Deprecated since version 3.0.

task_ids() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.task_ids instead: This property has been deprecated and is an alias

class lisa.trace.TraceEventCheckerBase(check=True, checkers=None)[source]

Bases: ABC, Loggable, Sequence

ABC for events checker classes.

Event checking can be achieved using a boolean expression on expected events.

Parameters:: check (bool) – Check that the listed events are present in the self.trace attribute of the instance on which the decorated method is applied. If no such attribute is found, no check will be done.

check_events(event_set, check_optional=False, namespaces=None)[source]

Check that certain trace events are available in the given set of events.

Returns:: Set of events selected by the checker in event_set.
Raises:: MissingTraceEventError if some events are not available. The exception must be raised after inspecting children node and combine their missing events so that the resulting exception is accurate.

abstract get_all_events()[source]

Return a set of all events that are checked by this checker.

That may be a superset of events that are strictly required, when the checker checks a logical OR combination of events for example.

abstract map(f)[source]: Apply the given function to all the children and rebuild a new object with the result.

expand_namespaces(namespaces=None)[source]: Build a TraceEventCheckerBase that will fixup the event names to take into account the given namespaces.

__call__(f)[source]

Decorator for methods that require some given trace events

Parameters:: events (list(str or TraceEventCheckerBase)) – The list of required events

The decorated method must operate on instances that have a self.trace attribute.

If some event requirements have already been defined for it (it has a used_events attribute, i.e. it has already been decorated), these will be combined with the new requirements using an :class`AndTraceEventChecker`.

__and__(other)[source]: Combine two event checkers into one that checks the presence of both.

See also

AndTraceEventChecker

__or__(other)[source]: Combine two event checkers into one that checks the presence of either of them.

See also

OrTraceEventChecker

__matmul__(other)[source]: Combine two event checkers into an optional one.

See also

OptionalTraceEventChecker

doc_str()[source]: Top-level function called by Sphinx’s autodoc extension to augment docstrings of the functions.

class lisa.trace.TraceEventChecker(event, check=True)[source]

Bases: TraceEventCheckerBase

Check for one single event.

Parameters:

event (str) – Name of the event to check for.
check (bool) – Check that the listed events are present in the self.trace attribute of the instance on which the decorated method is applied. If no such attribute is found, no check will be done.

get_all_events()[source]

Return a set of all events that are checked by this checker.

That may be a superset of events that are strictly required, when the checker checks a logical OR combination of events for example.

map(f)[source]: Apply the given function to all the children and rebuild a new object with the result.

class lisa.trace.EmptyTraceEventChecker(check=True)[source]

Bases: TraceEventCheckerBase

Check for no event at all.

Parameters:: check (bool) – Check that the listed events are present in the self.trace attribute of the instance on which the decorated method is applied. If no such attribute is found, no check will be done.

get_all_events()[source]

Return a set of all events that are checked by this checker.

That may be a superset of events that are strictly required, when the checker checks a logical OR combination of events for example.

map(f)[source]: Apply the given function to all the children and rebuild a new object with the result.

class lisa.trace.AssociativeTraceEventChecker(op_str, event_checkers, check=True, prefix_str='')[source]

Bases: TraceEventCheckerBase

Base class for associative operators like and and or

map(f)[source]: Apply the given function to all the children and rebuild a new object with the result.

get_all_events()[source]

Return a set of all events that are checked by this checker.

That may be a superset of events that are strictly required, when the checker checks a logical OR combination of events for example.

classmethod from_events(events, **kwargs)[source]

Build an instance of the class, converting str to TraceEventChecker.

Parameters:: events (list(str or TraceEventCheckerBase)) – Iterable of events

class lisa.trace.OrTraceEventChecker(event_checkers=None, **kwargs)[source]

Bases: AssociativeTraceEventChecker

Check that one of the given event checkers is satisfied.

Parameters:: event_checkers (list(TraceEventCheckerBase)) – Event checkers to check for

class lisa.trace.OptionalTraceEventChecker(event_checkers=None, **kwargs)[source]

Bases: _OptionalTraceEventCheckerBase

Do not check anything, but exposes the information that the events may be used if present.

Parameters:: event_checkers (list(TraceEventCheckerBase)) – Event checkers that may be used

class lisa.trace.DynamicTraceEventChecker(event_checkers=None, **kwargs)[source]

Bases: _OptionalTraceEventCheckerBase

Do not check anything, but exposes the information that one of the group of events will be used.

This allows an API to manually decide which group is chosen based on its parameters, but will still convey the information that they are not really optional.

Parameters:: event_checkers (list(TraceEventCheckerBase)) – Event checkers that may be used

class lisa.trace.AndTraceEventChecker(event_checkers=None, **kwargs)[source]

Bases: AssociativeTraceEventChecker

Check that all the given event checkers are satisfied.

Parameters:: event_checkers (list(TraceEventCheckerBase)) – Event checkers to check for

doc_str()[source]: Top-level function called by Sphinx’s autodoc extension to augment docstrings of the functions.

lisa.trace.requires_events(*events, **kwargs)[source]

Decorator for methods that require some given trace events.

Parameters:

events (list(str or TraceEventCheckerBase)) – The list of required events
check (bool) – Check that the listed events are present in the self.trace attribute of the instance on which the decorated method is applied. If no such attribute is found, no check will be done.

lisa.trace.requires_one_event_of(*events, **kwargs)[source]: Same as requires_events() with logical OR semantic.

lisa.trace.may_use_events(*events, **kwargs)[source]: Same as requires_events() but just exposes some events that may be used if presents.

lisa.trace.will_use_events_from(*events, **kwargs)[source]: Same as requires_events() but just exposes some events groups that will be used, depending on some dynamic factor.

exception lisa.trace.DroppedTraceEventError[source]

Bases: Exception

Raised when some events were dropped from the ftrace ring buffer because of lack of space.

exception lisa.trace.MissingTraceEventError(missing_events, available_events=None, msg='Trace is missing the following required events: {missing_events}{available}')[source]

Bases: RuntimeError, ValueError

Parameters:: missing_events (TraceEventCheckerBase or list(str)) – The missing trace events

class lisa.trace.FtraceConf(conf=None, src='user', add_default_src=True)[source]

Bases: SimpleMultiSrcConf, HideExekallID

Configuration class of FtraceCollector

Available keys:

ftrace-conf: FTrace configuration

events (Sequence or TraceEventCheckerBase): FTrace events to trace.

events-namespaces (Sequence or None): FTrace events namespaces to use. See Trace namespace constructor parameter..

functions (Sequence): FTrace functions to trace.

buffer-size (int): FTrace buffer size.

trace-clock (str or None): Clock used while tracing (see “trace_clock” in ftrace.txt kernel doc).

saved-cmdlines-nr (int): Number of saved cmdlines with associated PID while tracing.

tracer (str or None): FTrace tracer to use.

modules: Kernel modules settings

auto-load (bool): Compile kernel modules and load them automatically based on the events that are needed..

Example YAML:

# FTrace configuration
ftrace-conf:

    # ├ modules: Kernel modules settings
    #     
    #     Compile kernel modules and load them automatically based on
    #     the events that are needed.
    #     type: bool
    modules:

        # Compile kernel modules and load them automatically based on
        # the events that are needed.
        # type: bool
        auto-load: _

    # FTrace events to trace
    # type: Sequence or TraceEventCheckerBase
    events: _

    # FTrace events namespaces to use. See Trace namespace
    # constructor parameter.
    # type: Sequence or None
    events-namespaces: _

    # FTrace functions to trace
    # type: Sequence
    functions: _

    # FTrace buffer size
    # type: int
    buffer-size: _

    # Clock used while tracing (see "trace_clock" in ftrace.txt
    # kernel doc)
    # type: str or None
    trace-clock: _

    # Number of saved cmdlines with associated PID while tracing
    # type: int
    saved-cmdlines-nr: _

    # FTrace tracer to use
    # type: str or None
    tracer: _

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

STRUCTURE = <lisa.conf.TopLevelKeyDesc object>

add_merged_src(src, conf, optional_events=False, **kwargs)[source]

Merge-in a configuration source.

Parameters:

src (str) – Name of the merged source
conf (FtraceConf or dict(str, object)) – Conf to merge in
optional_events (bool) – If True, the events brought by conf will be wrapped in OptionalTraceEventChecker. This avoids failing just because the user asked for extra events that are not present in the kernel.

class BufferSize

Bases: HideExekallID

FTrace buffer size

DEFAULT_SRC = {'buffer-size': 10240, 'events-namespaces': ('lisa', None), 'modules': {'auto-load': True}, 'saved-cmdlines-nr': 8192}: Source added automatically using add_src() under the name ‘default’ when instances are built.

class Events

Bases: HideExekallID

FTrace events to trace

class EventsNamespaces

Bases: HideExekallID

FTrace events namespaces to use. See Trace namespace constructor parameter.

class Functions

Bases: HideExekallID

FTrace functions to trace

class ModulesAutoLoad

Bases: HideExekallID

Compile kernel modules and load them automatically based on the events that are needed.

class SavedCmdlinesNr

Bases: HideExekallID

Number of saved cmdlines with associated PID while tracing

class TraceClock

Bases: HideExekallID

Clock used while tracing (see “trace_clock” in ftrace.txt kernel doc)

class Tracer

Bases: HideExekallID

FTrace tracer to use

class lisa.trace.CollectorBase(collector, output_path=None)[source]

Bases: Loggable

Base class for devlib.collector.CollectorBase-based collectors using composition.

TOOLS = []: Sequence of tools to install on the target when using the collector.

NAME = None: Name of the collector class.

get_data(path=None)[source]: Similar to devlib.collector.CollectorBase.get_data() but takes the path directly as a parameter in order to disallow representing an invalid state where no path has been set.

get_trace(path)[source]: Deprecated alias for get_data().

Attention

Deprecated since version 2.0.

get_trace() is deprecated and will be removed in version 4.0, use lisa.trace.CollectorBase.get_data() instead

class lisa.trace.ComposedCollector(collectors)[source]

Bases: Mapping

Compose multiple lisa.trace.CollectorBase together.

When used as a context manager, collectors will be nested. Individual collectors can be retrieved by using the instance as a mapping, using the collectors’ NAME attribute as key.

Note

Only one collector of each type is allowed. This allows:

Getting back the collector instance using a fixed name.
Some collectors like lisa.trace.DmesgCollector are not re-entrant

class lisa.trace.FtraceCollector(target, *, events=None, functions=None, buffer_size=10240, output_path=None, autoreport=False, trace_clock=None, saved_cmdlines_nr=8192, tracer=None, kmod_auto_load=True, events_namespaces=('lisa', None), **kwargs)[source]

Bases: CollectorBase, Configurable

Thin wrapper around devlib.collector.ftrace.FtraceCollector.

Note

Events are expected to be provided by the target’s kernel, but if they are not lisa._kmod.LISADynamicKmod will build a kernel module to attempt to satisfy the missing events. This will typically require correct target setup, see lisa.target.TargetConf kernel/src configurations.

Parameters:

events (Sequence or lisa.trace.TraceEventCheckerBase) – FTrace events to trace
functions (Sequence) – FTrace functions to trace
buffer_size (int) – FTrace buffer size
trace_clock (str or None) – Clock used while tracing (see “trace_clock” in ftrace.txt kernel doc)
saved_cmdlines_nr (int) – Number of saved cmdlines with associated PID while tracing
tracer (str or None) – FTrace tracer to use
events_namespaces (Sequence or None) – FTrace events namespaces to use. See Trace namespace constructor parameter.
kmod_auto_load (bool) – Compile kernel modules and load them automatically based on the events that are needed.

NAME = 'ftrace': Name of the collector class.

CONF_CLASS: alias of FtraceConf

INIT_KWARGS_KEY_MAP = {'buffer_size': ['buffer-size'], 'events': ['events'], 'events_namespaces': ['events-namespaces'], 'functions': ['functions'], 'kmod_auto_load': ['modules', 'auto-load'], 'saved_cmdlines_nr': ['saved-cmdlines-nr'], 'trace_clock': ['trace-clock'], 'tracer': ['tracer']}

TOOLS = ['trace-cmd']: Sequence of tools to install on the target when using the collector.

get_data(*args, **kwargs)[source]: Similar to devlib.collector.CollectorBase.get_data() but takes the path directly as a parameter in order to disallow representing an invalid state where no path has been set.

classmethod from_conf(target, conf, *, events=None, functions=None, buffer_size=10240, output_path=None, autoreport=False, trace_clock=None, saved_cmdlines_nr=8192, tracer=None, kmod_auto_load=True, events_namespaces=('lisa', None))[source]

Build an FtraceCollector from a FtraceConf

Parameters:

target (lisa.target.Target) – Target to use when collecting the trace
conf (FtraceConf) – Configuration object

Variable keyword arguments:

Forwarded to __init__.

classmethod from_user_conf(target, base_conf=None, user_conf=None, merged_src='merged', *, events=None, functions=None, buffer_size=10240, output_path=None, autoreport=False, trace_clock=None, saved_cmdlines_nr=8192, tracer=None, kmod_auto_load=True, events_namespaces=('lisa', None))[source]

Build an FtraceCollector from two FtraceConf.

base_conf is expected to contain the minimal configuration, and user_conf some additional settings that are used to augment the base configuration.

Parameters:

target (lisa.target.Target) – Target to use when collecting the trace
base_conf (FtraceConf) – Base configuration object, merged with user_conf.
user_conf (FtraceConf) – User configuration object
merged_src (str) – Name of the configuration source created by merging base_conf and user_conf

Other keyword arguments:

Forwarded to from_conf().

class lisa.trace.DmesgCollector(target, *, empty_buffer=False, facility='kern', level='debug', output_path=None)[source]

Bases: CollectorBase

Wrapper around devlib.collector.dmesg.DmesgCollector.

It installs the dmesg tool automatically on the target upon creation, so we know what version is being is used.

NAME = 'dmesg': Name of the collector class.

TOOLS = ['dmesg']: Sequence of tools to install on the target when using the collector.

LOG_LEVELS = ['emerg', 'alert', 'crit', 'err', 'warn', 'notice', 'info', 'debug']

Analysis proxy

Helper module for registering Analysis classes methods

class lisa.analysis._proxy.AnalysisProxy(trace, params=None)[source]

Bases: Loggable

Entry point to call analysis methods on Trace objects.

Example

# Call lisa.analysis.LoadTrackingAnalysis.df_task_signal() on a trace:

df = trace.ana.load_tracking.df_task_signal(task='foo', signal='util')

The proxy can also be called like a function to define default values for analysis methods:

ana = trace.ana(task='big_0-3')
ana.load_tracking.df_task_signal(signal='util')

# Equivalent to:
ana.load_tracking.df_task_signal(task='big_0-3', signal='util')

# The proxy can be called again to override the value given to some
# parameters, and the the value can also be overridden when calling the
# method:
ana(task='foo').df_task_signal(signal='util')
ana.df_task_signal(task='foo', signal='util')

Parameters:: trace (lisa.trace.Trace) – input Trace object

__call__(**kwargs)[source]: Call self as a function.

classmethod get_all_events()[source]: Returns the set of all events used by any of the registered analysis.

__dir__()[source]: Provide better completion support for interactive notebook usage

Analysis base class

class lisa.analysis.base.AnalysisHelpers[source]

Bases: Loggable, ABC

Helper methods class for Analysis modules.

abstract property name: Name of the analysis class.

classmethod setup_plot(width=16, height=4, ncols=1, nrows=1, interactive=None, link_dataframes=None, cursor_delta=None, **kwargs)[source]

Common helper for setting up a matplotlib plot

Parameters:

width (int or float) – Width of the plot (inches)
height (int or float) – Height of each subplot (inches)
ncols (int) – Number of plots on a single row
nrows (int) – Number of plots in a single column
link_dataframes (list(pandas.DataFrame) or None) – Link the provided dataframes to the axes using lisa.notebook.axis_link_dataframes()
cursor_delta (bool or None) – Add two vertical lines set with left and right clicks, and show the time delta between them in a widget.
interactive (bool) – If True, use the pyplot API of matplotlib, which integrates well with notebooks. However, it can lead to memory leaks in scripts generating lots of plots, in which case it is better to use the non-interactive API. Defaults to True when running under IPython or Jupyter notebook, False` otherwise.

Keywords arguments:

Extra arguments to pass to matplotlib.figure.Figure.subplots

Returns:

tuple(matplotlib.figure.Figure, matplotlib.axes.Axes (or an array of, if nrows > 1))

Attention

Deprecated since version 2.0.

setup_plot() is deprecated and will be removed in version 4.0: Made irrelevant by the use of holoviews

classmethod set_axis_cycler(axis, *cyclers)[source]: Context manager to set cyclers on an axis (and the default cycler as well), and then restore the default cycler.

Note

The given cyclers are merged with the original cycler. The given cyclers will override any key of the original cycler, and the number of values will be adjusted to the maximum size between all of them. This way of merging allows decoupling the length of all keys.

Attention

Deprecated since version 2.0.

set_axis_cycler() is deprecated and will be removed in version 4.0: Made irrelevant by the use of holoviews

classmethod set_axis_rc_params(axis, rc_params)[source]: Context manager to set matplotlib.rcParams while plotting, and then restore the default parameters.

Attention

Deprecated since version 2.0.

set_axis_rc_params() is deprecated and will be removed in version 4.0: Made irrelevant by the use of holoviews

classmethod cycle_colors(axis, nr_cycles=1)[source]

Cycle the axis color cycle nr_cycles forward

Parameters:

axis (matplotlib.axes.Axes) – The axis to manipulate
nr_cycles (int) – The number of colors to cycle through.

Note

This is an absolute cycle, as in, it will always start from the first color defined in the color cycle.

Attention

Deprecated since version 2.0.

cycle_colors() is deprecated and will be removed in version 4.0: Made irrelevant by the use of holoviews

classmethod get_next_color(axis)[source]

Get the next color that will be used to draw lines on the axis

Parameters:: axis (matplotlib.axes.Axes) – The axis

Warning

This will consume the color from the cycler, which means it will change which color is to be used next.

Attention

Deprecated since version 2.0.

get_next_color() is deprecated and will be removed in version 4.0: Made irrelevant by the use of holoviews

get_default_plot_path(img_format, plot_name, default_dir='.')[source]

Return the default path to use to save plots for the analysis.

Parameters:

img_format (str) – Format of the image to save.
plot_name (str) – Middle-name of the plot
default_dir (str) – Default folder to store plots into.

save_plot(figure, filepath=None, img_format=None, backend=None)[source]

Called on Trace instances as trace.ana.thermal.save_plot()

Save a holoviews element or matplotlib.figure.Figure as an image file.

Parameters:

figure (matplotlib.figure.Figure or holoviews.core.Element) – Figure to save to a file.
filepath (str or None) – Path to the file to save the plot. If None, a default path will be used.
img_format (str or None) – Format of the image. If None, it is guessed from the filepath.
backend (str or None) – Holoviews backend to use. If left to None, the current backend enabled with hv.extension() will be used.

do_plot(plotter, axis=None, **kwargs)[source]

Called on Trace instances as trace.ana.thermal.do_plot()

Simple helper for consistent behavior across methods.

Attention

Deprecated since version 2.0.

do_plot() is deprecated and will be removed in version 4.0: Made irrelevant by the use of holoviews

classmethod get_plot_methods(*args, **kwargs)[source]

classmethod plot_method(f)[source]

Plot function decorator.

It provides among other things:

automatic plot setup

HTML and reStructuredText output.

workarounds some holoviews issues

integration in other tools

class lisa.analysis.base.TraceAnalysisBase(trace, proxy=None)[source]

Bases: AnalysisHelpers

Base class for Analysis modules.

Parameters:: trace (lisa.trace.Trace) – input Trace object
Design notes:

Method depending on certain trace events must be decorated with lisa.trace.requires_events()

classmethod get_df_methods(*args, **kwargs)[source]

classmethod df_method(f)[source]

Dataframe function decorator.

It provides among other things:

Dataframe format conversion

classmethod cache(f, fmt='parquet', ignored_params=None)[source]

Decorator to enable caching of the output of dataframe getter function in the trace cache.

This will write the return data to the swap as well, so processing can be skipped completely when possible.

Parameters:

fmt (str) – Format of the data to write to the cache. This will influence the extension of the cache file created. If disk-only format is chosen, the data is not retained in memory and the path to the allocated cache file is passed as first parameter to the wrapped function. This allows manual management of the file’s content, as well having a path to a file to pass to external tools if they can consume the data directly.
ignored_params (list(str)) – Parameters to ignore when trying to hit the cache.

classmethod get_all_events()[source]: Returns the set of all events used by any of the methods.

get_default_plot_path(**kwargs)[source]

Called on Trace instances as trace.ana.thermal.get_default_plot_path()

Return the default path to use to save plots for the analysis.

Parameters:

img_format (str) – Format of the image to save.
plot_name (str) – Middle-name of the plot
default_dir (str) – Default folder to store plots into.

classmethod get_analysis_classes()[source]

classmethod call_on_trace(meth, trace, meth_kwargs)[source]

Call a method of a subclass on a given trace.

Parameters:

meth (collections.abc.Callable) – Function (method) defined on a subclass.
trace (lisa.trace.Trace) – Trace object to use
meth_kwargs (dict) – Dictionary of keyword arguments to pass to meth

It will create an instance of the right analysis, bind the function to it and call the resulting bound method with meth_kwargs extra keyword arguments.

Load tracking

Scheduler load tracking analysis module

class lisa.analysis.load_tracking.LoadTrackingAnalysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for scheduler load tracking analysis

Parameters:: trace (lisa.trace.Trace) – input Trace object

name = 'load_tracking'

df_cpus_signal(signal, cpus: Sequence[CPU] = None)[source]

Called on Trace instances as trace.ana.load_tracking.df_cpus_signal()

Get the load-tracking signals for the CPUs

Returns:

a pandas.DataFrame with a column of the same name as the specified signal, and additional context columns such as cpu.

Parameters:

signal (str) –
Signal name to get. Can be any of:
- util
- load
- enqueued (util est enqueued)
- capacity
cpus (list(lisa.trace.CPU) or None) – If specified, list of CPUs to select.

Required trace events:

one group of: (sched_pelt_cfs or sched_load_cfs_rq or sched_load_avg_cpu) , sched_util_est_cfs , sched_cpu_capacity

df_cpus_signals()[source]

Called on Trace instances as trace.ana.load_tracking.df_cpus_signals()

Get the load-tracking signals for the CPUs

Returns:

a pandas.DataFrame with:

A util column (the average utilization of a CPU at time t)
A load column (the average load of a CPU at time t)

Attention

Deprecated since version 2.0.

df_cpus_signals() is deprecated and will be removed in version 4.0, use lisa.analysis.load_tracking.LoadTrackingAnalysis.df_cpus_signal() instead

Required trace events:

sched_pelt_cfs or sched_load_cfs_rq or sched_load_avg_cpu

df_tasks_signal(signal, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.load_tracking.df_tasks_signal()

Get the load-tracking signals for the tasks

Returns:

a pandas.DataFrame with a column of the same name as the specified signal, and additional context columns such as cpu.

Parameters:

signal (str) –

Signal name to get. Can be any of:

util
load
enqueued (util est enqueued)
ewma (util est ewma)
required_capacity

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

one group of: (sched_pelt_se or sched_load_se or sched_load_avg_task) , sched_util_est_se

df_task_signal(task, signal, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.load_tracking.df_task_signal()

Same as df_tasks_signal() but for one task only.

Parameters:

task (str or int or tuple) – The name or PID of the task, or a tuple (pid, comm)
signal – See df_tasks_signal().

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

one group of: (sched_pelt_se or sched_load_se or sched_load_avg_task) , sched_util_est_se

df_tasks_signals()[source]

Called on Trace instances as trace.ana.load_tracking.df_tasks_signals()

Get the load-tracking signals for the tasks

Returns:

a pandas.DataFrame with:

A util column (the average utilization of a task at time t)
A load column (the average load of a task at time t)

If CPU capacity information is available:

A required_capacity column (the minimum available CPU capacity required to run this task without being CPU-bound)

Attention

Deprecated since version 2.0.

df_tasks_signals() is deprecated and will be removed in version 4.0, use lisa.analysis.load_tracking.LoadTrackingAnalysis.df_tasks_signal() instead

Required trace events:

sched_pelt_se or sched_load_se or sched_load_avg_task

df_top_big_tasks(util_threshold, min_samples=100, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.load_tracking.df_top_big_tasks()

Tasks which had ‘utilization’ samples bigger than the specified threshold

Parameters:

min_samples (int) – minumum number of samples over the min_utilization
min_utilization (int) – minimum utilization used to filter samples default: capacity of a little cluster

Returns:

a pandas.DataFrame with:

Task PIDs as index
A samples column (The number of util samples above the threshold)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

one group of: (sched_pelt_se or sched_load_se or sched_load_avg_task) , sched_util_est_se

plot_cpus_signals(cpus: Sequence[CPU] = None, signals: Sequence[str] = ['util', 'load'], *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.load_tracking.plot_cpus_signals()

Plot the CPU-related load-tracking signals

Parameters:

cpus (list(int)) – list of CPUs to be plotted
signals (list(str)) – List of signals to plot.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

one group of: (sched_pelt_cfs or sched_load_cfs_rq or sched_load_avg_cpu) , sched_util_est_cfs , sched_cpu_capacity
optional: sched_overutilized

Example plot:

signals=['util', 'load']

plot_task_signals(task: TaskID, signals: Sequence[str] = ['util', 'load'], *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.load_tracking.plot_task_signals()

Plot the task-related load-tracking signals

Parameters:

task (str or int or tuple) – The name or PID of the task, or a tuple (pid, comm)
signals (list(str)) – List of signals to plot.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

one group of: (sched_pelt_se or sched_load_se or sched_load_avg_task) , sched_util_est_se

Example plot:

signals=['util', 'load'], task=big_0-0

plot_task_required_capacity(task: TaskID, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.load_tracking.plot_task_required_capacity()

Plot the minimum required capacity of a task

Parameters:: task (str or int or tuple) – The name or PID of the task, or a tuple (pid, comm)

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

one group of: (sched_pelt_se or sched_load_se or sched_load_avg_task) , sched_util_est_se

Example plot:

task=big_0-0

plot_task_placement(task: TaskID, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.load_tracking.plot_task_placement()

Plot the CPU placement of the task

Parameters:: task (str or int or tuple) – The name or PID of the task, or a tuple (pid, comm)

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

one group of: (sched_pelt_se or sched_load_se or sched_load_avg_task) , sched_util_est_se

Example plot:

task=big_0-0

CPUs

CPUs Analysis Module

class lisa.analysis.cpus.CpusAnalysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for CPUs signals analysis

name = 'cpus'

df_context_switches(*, df_fmt=None)[source]

Called on Trace instances as trace.ana.cpus.df_context_switches()

Compute number of context switches on each CPU.

Returns:

A pandas.DataFrame with:

A context_switch_cnt column (the number of context switch per CPU)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_switch

plot_context_switches(*, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.cpus.plot_context_switches()

Plot histogram of context switches on each CPU.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch

Example plot:

plot_orig_capacity(cpu: CPU, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.cpus.plot_orig_capacity()

Plot the orig capacity of a CPU onto a given axis

Parameters:: cpu (int) – The CPU

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Example plot:

cpu=0

Frequency

Frequency Analysis Module

class lisa.analysis.frequency.FrequencyAnalysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for plotting Frequency Analysis data

Parameters:: trace (lisa.trace.Trace) – input Trace object

name = 'frequency'

df_cpus_frequency(signals_init=True)[source]

Called on Trace instances as trace.ana.frequency.df_cpus_frequency()

Similar to trace.df_event('cpu_frequency'), with userspace@cpu_frequency_devlib support.

Parameters:: signals_init – If True, and initial value for signals will be provided. This includes initial value taken outside window boundaries and devlib-provided events.

The userspace@cpu_frequency_devlib user event is merged in the dataframe if it provides earlier values for a CPU.

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib

df_cpu_frequency(cpu, **kwargs)[source]

Called on Trace instances as trace.ana.frequency.df_cpu_frequency()

Same as df_cpus_frequency() but for a single CPU.

Parameters:

cpu (int) – CPU ID to get the frequency of.

Variable keyword arguments:

Forwarded to df_cpus_frequency().

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib

df_cpu_frequency_residency(cpu)[source]

Called on Trace instances as trace.ana.frequency.df_cpu_frequency_residency()

Get per-CPU frequency residency, i.e. amount of time CPU cpu spent at each frequency.

Parameters:

cpu (int) – CPU ID

Returns:

A pandas.DataFrame with:

A total_time column (the total time spent at a frequency)
A active_time column (the non-idle time spent at a frequency)

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib
cpu_idle

df_domain_frequency_residency(cpu)[source]

Called on Trace instances as trace.ana.frequency.df_domain_frequency_residency()

Get per-frequency-domain frequency residency, i.e. amount of time each domain at each frequency.

Parameters:

cpu (int) – Any CPU of the domain to analyse

Returns:

A pandas.DataFrame with:

A total_time column (the total time spent at a frequency)
A active_time column (the non-idle time spent at a frequency)

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib
cpu_idle

df_cpu_frequency_transitions(cpu, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.frequency.df_cpu_frequency_transitions()

Compute number of frequency transitions of a given CPU.

Parameters:

cpu (int) – a CPU ID

Returns:

A pandas.DataFrame with:

A transitions column (the number of frequency transitions)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib

df_cpu_frequency_transition_rate(cpu, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.frequency.df_cpu_frequency_transition_rate()

Compute frequency transition rate of a given CPU.

Parameters:

cpu (int) – a CPU ID

Returns:

A pandas.DataFrame with:

A transitions column (the number of frequency transitions per second)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib

get_average_cpu_frequency(cpu)[source]

Called on Trace instances as trace.ana.frequency.get_average_cpu_frequency()

Get the average frequency for a given CPU

Parameters:

cpu (int) – The CPU to analyse

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib

df_peripheral_clock_effective_rate(clk_name, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.frequency.df_peripheral_clock_effective_rate()

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

clk_set_rate
clk_enable
clk_disable

plot_cpu_frequencies(cpu: CPU, average: bool = True, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.frequency.plot_cpu_frequencies()

Plot frequency for the specified CPU

Parameters:

cpu – The CPU for which to plot frequencies
average (bool) – If True, add a horizontal line which is the frequency average.

If sched_overutilized events are available, the plots will also show the intervals of time where the system was overutilized.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib

Example plot:

average=True, cpu=0

plot_domain_frequencies(*, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.frequency.plot_domain_frequencies()

Plot frequency trend for all frequency domains.

If sched_overutilized events are available, the plots will also show the intervals of time where the cluster was overutilized.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib

Example plot:

plot_cpu_frequency_residency(cpu: CPU, pct: bool = False, domain_label: bool = False, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.frequency.plot_cpu_frequency_residency()

Plot per-CPU frequency residency.

Parameters:

cpu (int) – The CPU to generate the plot for
pct (bool) – Plot residencies in percentage
domain_label (bool) – If True, the labels will mention all CPUs in the domain, rather than the CPU passed.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib
cpu_idle

Example plot:

cpu=0, domain_label=False, pct=False

plot_domain_frequency_residency(pct: bool = False, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.frequency.plot_domain_frequency_residency()

Plot the frequency residency for all frequency domains.

Parameters:: pct (bool) – Plot residencies in percentage

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib
cpu_idle

Example plot:

pct=False

plot_cpu_frequency_transitions(cpu: CPU, pct: bool = False, domain_label: bool = False, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.frequency.plot_cpu_frequency_transitions()

Plot frequency transitions count of the specified CPU

Parameters:

cpu (int) – The CPU to genererate the plot for
pct (bool) – Plot frequency transitions in percentage
domain_label (bool) – If True, the labels will mention all CPUs in the domain, rather than the CPU passed.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib

Example plot:

cpu=0, domain_label=False, pct=False

plot_domain_frequency_transitions(pct: bool = False, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.frequency.plot_domain_frequency_transitions()

Plot frequency transitions count for all frequency domains

Parameters:: pct (bool) – Plot frequency transitions in percentage

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib

Example plot:

pct=False

plot_peripheral_frequency(clk_name: str, average: bool = True, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.frequency.plot_peripheral_frequency()

Plot frequency for the specified peripheral clock frequency

Parameters:

clk_name (str) – The clock name for which to plot frequency
average (bool) – If True, add a horizontal line which is the frequency average.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

clk_set_rate
clk_enable
clk_disable

Example plot:

average=True, clk_name=aplclk

Tasks

class lisa.analysis.tasks.StateInt(value, char='', doc='')[source]

Bases: int

An tweaked int for lisa.analysis.tasks.TaskState

static __new__(cls, value, char='', doc='')[source]

__or__(other)[source]: Return self|value.

class lisa.analysis.tasks.TaskState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: StateInt, Enum

Represents the task state as visible in sched_switch

Values are extracted from include/linux/sched.h
Chars are extracted from fs/proc/array.c:get_task_state()

TASK_RUNNING = 0

TASK_INTERRUPTIBLE = 1

TASK_UNINTERRUPTIBLE = 2

TASK_STOPPED = 4

TASK_TRACED = 8

EXIT_DEAD = 16

EXIT_ZOMBIE = 32

TASK_PARKED = 64

TASK_DEAD = 128

TASK_WAKEKILL = 256

TASK_WAKING = 512

TASK_NOLOAD = 1024

TASK_NEW = 2048

TASK_STATE_MAX = 4096

TASK_ACTIVE = 8192

TASK_RENAMED = 8193

TASK_UNKNOWN = -1

classmethod list_reported_states()[source]

List the states that can be reported in a sched_switch trace

See include/linux/sched.h:TASK_REPORT

classmethod sched_switch_str(value)[source]

Get the task state string that would be used in a sched_switch event

Parameters:: value (int) – The task state value

Tries to emulate what is done in include/trace/events:TRACE_EVENT(sched_switch)

classmethod from_sched_switch_str(string)[source]

Build a StateInt from a string as it would be used in sched_switch event’s prev_state field.

Parameters:: string (str) – String to parse.

__new__(value)

__format__(format_spec): Default object formatter.

class lisa.analysis.tasks.TaskID(pid, comm)[source]

Bases: TaskID

Unique identifier of a logical task in a lisa.trace.Trace.

Parameters:

pid (int) – PID of the task. None indicates the PID is not important.
comm (str) – Name of the task. None indicates the name is not important. This is useful to describe tasks like PID0, which can have multiple names associated.

Create new instance of TaskID(pid, comm)

__slots__ = []

class lisa.analysis.tasks.TasksAnalysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for Tasks signals analysis.

Parameters:: trace (lisa.trace.Trace) – input Trace object

name = 'tasks'

get_task_name_pids(name, ignore_fork=True)[source]

Called on Trace instances as trace.ana.tasks.get_task_name_pids()

Get the PIDs of all tasks with the specified name.

The same PID can have different task names, mainly because once a task is generated it inherits the parent name and then its name is updated to represent what the task really is.

Parameters:

name (str) – task name
ignore_fork (bool) – Hide the PIDs of tasks that initially had name but were later renamed. This is common for shell processes for example, which fork a new task, inheriting the shell name, and then being renamed with the final “real” task name

Returns:

a list of PID for tasks which name matches the required one.

get_task_pid_names(pid)[source]

Called on Trace instances as trace.ana.tasks.get_task_pid_names()

Get the all the names of the task(s) with the specified PID, in appearance order.

The same PID can have different task names, mainly because once a task is generated it inherits the parent name and then its name is updated to represent what the task really is.

Parameters:: name (int) – task PID
Returns:: the name of the task which PID matches the required one, the last time they ran in the current trace

get_task_by_pid(pid)[source]

Called on Trace instances as trace.ana.tasks.get_task_by_pid()

Get the name of the task with the specified PID.

The same PID can have different task names, mainly because once a task is generated it inherits the parent name and then its name is updated to represent what the task really is.

This API works under the assumption that a task name is updated at most one time and it always report the name the task had the last time it has been scheduled for execution in the current trace.

Parameters:: name (int) – task PID
Returns:: the name of the task which PID matches the required one, the last time they ran in the current trace

Attention

Deprecated since version 2.0.

get_task_by_pid() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.get_task_pid_names() instead: This function raises exceptions when faced with ambiguity instead of giving the choice to the user

get_task_ids(task, update=True)[source]

Called on Trace instances as trace.ana.tasks.get_task_ids()

Similar to get_task_id() but returns a list with all the combinations, instead of raising an exception.

Parameters:

task (int or str or tuple(int, str)) – Either the task name, the task PID, or a tuple (pid, comm)
update (bool) – If a partially-filled TaskID is passed (one of the fields set to None), returns a complete TaskID instead of leaving the None fields.

get_task_id(task, update=True)[source]

Called on Trace instances as trace.ana.tasks.get_task_id()

Helper that resolves a task PID or name to a TaskID.

Parameters:

task (int or str or tuple(int, str)) – Either the task name, the task PID, or a tuple (pid, comm)
update (bool) – If a partially-filled TaskID is passed (one of the fields set to None), returns a complete TaskID instead of leaving the None fields.

Raises:

ValueError – If there the input matches multiple tasks in the trace. See get_task_ids() to get all the ambiguous alternatives instead of an exception.

get_task_pid(task)[source]

Called on Trace instances as trace.ana.tasks.get_task_pid()

Helper that takes either a name or a PID and always returns a PID

Parameters:: task (int or str or tuple(int, str)) – Either the task name or the task PID

Attention

Deprecated since version 2.0.

get_task_pid() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.get_task_id() instead

get_tasks()[source]

Called on Trace instances as trace.ana.tasks.get_tasks()

Get a dictionary of all the tasks in the Trace.

Returns:: a dictionary which maps each PID to the corresponding list of task name

property task_ids: List of all the TaskID in the trace, sorted by PID.

cpus_of_tasks(tasks)[source]

Called on Trace instances as trace.ana.tasks.cpus_of_tasks()

Return the list of CPUs where the tasks executed.

Parameters:

tasks (list(int or str or tuple(int, str))) – Task names or PIDs or (pid, comm) to look for.

Required trace events:

sched_switch

df_tasks_wakeups(*, df_fmt=None)[source]

Called on Trace instances as trace.ana.tasks.df_tasks_wakeups()

The number of wakeups per task

Returns:

a pandas.DataFrame with:

Task PIDs as index
A wakeups column (The number of wakeups)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_wakeup

df_top_wakeup(min_wakeups=100, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.tasks.df_top_wakeup()

Tasks which wakeup more frequently than a specified threshold.

Parameters:: min_wakeups (int) – minimum number of wakeups

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_wakeup

df_rt_tasks(min_prio=100, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.tasks.df_rt_tasks()

Tasks with RT priority

Note

priorities uses scheduler values, thus: the lower the value the higher is the task priority. RT Priorities: [ 0..100] FAIR Priorities: [101..120]

Parameters:

min_prio (int) – minimum priority

Returns:

a pandas.DataFrame with:

Task PIDs as index
A prio column (The priority of the task)
A comm column (The name of the task)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_switch

df_tasks_states(*, df_fmt=None)[source]

Called on Trace instances as trace.ana.tasks.df_tasks_states()

DataFrame of all tasks state updates events

Returns:

a pandas.DataFrame with:

A cpu column (the CPU where the event took place)
A pid column (the PID of the task)
A comm column (the name of the task)
A target_cpu column (the CPU where the task has been scheduled). Will be NaN for non-wakeup events
A curr_state column (the current task state, see TaskState)
A delta column (the duration for which the task will remain in this state)
A next_state column (the next task state)

Warning

Since sched_switch event multiplexes the update to two PIDs at the same time, the resulting dataframe would contain duplicated indices, breaking some Pandas functions. In order to avoid that, the duplicated timestamps are updated with the minimum increment possible to remove duplication.

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

df_task_states(task, stringify=False, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.tasks.df_task_states()

DataFrame of task’s state updates events

Parameters:

task (int or str or tuple(int, str)) – The task’s name or PID or tuple (pid, comm)
stringify (bool) – Include stringifed TaskState columns

Returns:

a pandas.DataFrame with:

A cpu column (the CPU where the event took place)
A target_cpu column (the CPU where the task has been scheduled). Will be -1 for non-wakeup events
A curr_state column (the current task state, see TaskState)
A next_state column (the next task state)
A delta column (the duration for which the task will remain in this state)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

classmethod stringify_task_state_series(series)[source]

Called on Trace instances as trace.ana.tasks.stringify_task_state_series()

Stringify a series containing TaskState values

Parameters:: series (pandas.Series) – The series

The common use case for this will be to pass a dataframe column:

df["state_str"] = stringify_task_state_series(df["state"])

classmethod stringify_df_task_states(df, columns, inplace=False)[source]

Called on Trace instances as trace.ana.tasks.stringify_df_task_states()

Adds stringified TaskState columns to a Dataframe

Parameters:

df (pandas.DataFrame) – The DataFrame to operate on
columns (list) – The columns to stringify
inplace (bool) – Do the modification on the original DataFrame

df_tasks_runtime(*, df_fmt=None)[source]

Called on Trace instances as trace.ana.tasks.df_tasks_runtime()

DataFrame of the time each task spent in TASK_ACTIVE (TaskState)

Returns:

a pandas.DataFrame with:

PIDs as index
A comm column (the name of the task)
A runtime column (the time that task spent running)

Note

This function only tracks time spent by each PID. The reported name is the last name associated with the PID in chronological order.

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

df_task_total_residency(task, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.tasks.df_task_total_residency()

DataFrame of a task’s execution time on each CPU

Parameters:

task (int or str or tuple(int, str)) – the task to report runtimes for

Returns:

a pandas.DataFrame with:

CPU IDs as index
A runtime column (the time the task spent being active)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

df_tasks_total_residency(tasks=None, ascending=False, count=None)[source]

Called on Trace instances as trace.ana.tasks.df_tasks_total_residency()

DataFrame of tasks execution time on each CPU

Parameters:

tasks (list(int or str or tuple(int, str))) – List of tasks to report, all trace tasks by default
ascending (bool) – Set True to order plot by ascending task runtime False by default
count (int) – Maximum number of tasks to report

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

df_task_activation(task, cpu=None, active_value=1, sleep_value=0, preempted_value=nan, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.tasks.df_task_activation()

DataFrame of a task’s active time on a given CPU

Parameters:

task (int or str or tuple(int, str)) – the task to report activations of
cpu (int or None) – the CPUs to look at. If None, all CPUs will be used.
active_value (float) – the value to use in the series when task is active.
sleep_value (float) – the value to use in the series when task is sleeping.
preempted_value – the value to use in the series when task is preempted (runnable but not actually executing).

Returns:

a pandas.DataFrame with:

A timestamp as index
A active column, containing active_value when the task is running, sleep_value when sleeping, and preempted_value otherwise.
A cpu column with the CPU the task was running on.
A duration column containing the duration of the current sleep or activation.
A duty_cycle column containing the duty cycle in [0...1] of the task, updated at each pair of activation and sleep.

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

plot_task_residency(task: TaskID, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.tasks.plot_task_residency()

Plot on which CPUs the task ran on over time

Parameters:: task (int or str or tuple(int, str)) – Task to track

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch

Example plot:

task=big_0-0

plot_task_total_residency(task: TaskID, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.tasks.plot_task_total_residency()

Plot a task’s total time spent on each CPU

Parameters:: task (str or int or tuple(int, str)) – The task’s name or PID or tuple (pid, comm)

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

Example plot:

task=big_0-0

plot_tasks_total_residency(tasks: Sequence[TaskID] = None, ascending: bool = False, count: bool = None, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.tasks.plot_tasks_total_residency()

Plot the stacked total time spent by each task on each CPU

Parameters:

tasks (list(int or str or tuple(int, str))) – List of tasks to plot, all trace tasks by default
ascending (bool) – Set True to order plot by ascending task runtime, False by default
count (int) – Maximum number of tasks to report

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

Example plot:

ascending=False

plot_tasks_wakeups(target_cpus: Sequence[CPU] = None, window: float = 0.01, per_sec: bool = False, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.tasks.plot_tasks_wakeups()

Plot task wakeups over time

Parameters:

target_cpus
window (float) – The rolling window size for wakeup counts.
per_sec (bool) – Display wakeups per second if True, else wakeup counts within the window

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Example plot:

per_sec=False, window=0.01

plot_tasks_wakeups_heatmap(bins: int = 100, xbins=None, colormap=None, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.tasks.plot_tasks_wakeups_heatmap()

Plot tasks wakeups heatmap

Parameters:

bins (int) – Number of x-axis bins, i.e. in how many slices should time be arranged
colormap (str) –
The name of a colormap:
- matplotlib backend: https://matplotlib.org/stable/tutorials/colors/colormaps.html
- bokeh backend: https://docs.bokeh.org/en/latest/docs/reference/palettes.html

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_wakeup

Example plot:

bins=100

plot_tasks_forks(target_cpus: Sequence[CPU] = None, window: float = 0.01, per_sec: bool = False, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.tasks.plot_tasks_forks()

Plot task forks over time

Parameters:

target_cpus
window (float) – The rolling window size for fork counts.
per_sec (bool) – Display wakeups per second if True, else wakeup counts within the window

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_wakeup_new

Example plot:

per_sec=False, window=0.01

plot_tasks_forks_heatmap(bins: int = 100, xbins=None, colormap=None, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.tasks.plot_tasks_forks_heatmap()

Plot number of task forks over time as a heatmap.

Parameters:

bins (int) – Number of x-axis bins, i.e. in how many slices should time be arranged
colormap (str) –
The name of a colormap:
- matplotlib backend: https://matplotlib.org/stable/tutorials/colors/colormaps.html
- bokeh backend: https://docs.bokeh.org/en/latest/docs/reference/palettes.html

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_wakeup_new

Example plot:

bins=100

plot_tasks_activation(tasks: Sequence[TaskID] = None, hide_tasks: Sequence[TaskID] = None, which_cpu: bool = True, overlay: bool = False, *, show_legend=None, cpu: CPU = None, alpha: float = None, duration: bool = False, duty_cycle: bool = False, height_duty_cycle: bool = False, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.tasks.plot_tasks_activation()

Plot all tasks activations, in a style similar to kernelshark.

Parameters:

tasks (list(TaskID) or None) – Tasks to plot. If None, all tasks in the trace will be used.
hide_tasks (list(TaskID) or None) – Tasks to hide. Note that PID 0 (idle task) will always be hidden.
alpha – transparency level of the plot.
overlay – If True, adjust the transparency and plot activations on a separate hidden scale so existing scales are not modified.
duration (bool) – Plot the duration of each sleep/activation.
duty_cycle (bool) – Plot the duty cycle of each pair of sleep/activation.
which_cpu (bool) – If True, plot the activations on each CPU in a separate row like kernelshark does.
height_duty_cycle (bool) – Height of each activation’s rectangle is proportional to the duty cycle during that activation.

See also

df_task_activation()

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

Example plot:

duration=False, duty_cycle=False, height_duty_cycle=False, overlay=False, which_cpu=True

plot_task_activation(task: TaskID, *, hide_tasks: Sequence[TaskID] = None, which_cpu: bool = True, overlay: bool = False, show_legend=None, cpu: CPU = None, alpha: float = None, duration: bool = False, duty_cycle: bool = False, height_duty_cycle: bool = False, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.tasks.plot_task_activation()

Plot task activations, in a style similar to kernelshark.

Parameters:: task (int or str or tuple(int, str)) – the task to report activations of

See also

plot_tasks_activation()

Attention

Deprecated since version 2.0.

plot_task_activation() is deprecated and will be removed in version 4.0, use lisa.analysis.tasks.TasksAnalysis.plot_tasks_activation() instead: Deprecated since it does not provide anything more than plot_tasks_activation

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

Example plot:

duration=True, duty_cycle=False, height_duty_cycle=False, overlay=False, task=big_0-0, which_cpu=True

rt-app

class lisa.analysis.rta.RefTime(kernel, user)

Bases: tuple

Named tuple to synchronize kernel and userspace (rt-app) timestamps.

__getnewargs__(): Return self as a plain tuple. Used by copy and pickle.

__match_args__ = ('kernel', 'user')

static __new__(_cls, kernel, user): Create new instance of RefTime(kernel, user)

kernel: Alias for field number 0

user: Alias for field number 1

class lisa.analysis.rta.PhaseWindow(id, start, end, properties)

Bases: tuple

Named tuple with fields:

id: integer ID of the phase or its name.

start: timestamp of the start of the phase

end: timestamp of the end of the phase

properties: properties of the phase, extracted from a lisa.wlgen.rta profile.

__getnewargs__(): Return self as a plain tuple. Used by copy and pickle.

__match_args__ = ('id', 'start', 'end', 'properties')

static __new__(_cls, id, start, end, properties): Create new instance of PhaseWindow(id, start, end, properties)

end: Alias for field number 2

id: Alias for field number 0

properties: Alias for field number 3

start: Alias for field number 1

class lisa.analysis.rta.RTAEventsAnalysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for RTA events analysis.

Parameters:: trace (lisa.trace.Trace) – input Trace object

name = 'rta'

RTAPP_USERSPACE_EVENTS = ['userspace@rtapp_main', 'userspace@rtapp_task', 'userspace@rtapp_loop', 'userspace@rtapp_event', 'userspace@rtapp_stats']: List of ftrace events rtapp is able to emit.

property rtapp_tasks

List of lisa.analysis.tasks.TaskID of the rt-app tasks present in the trace.

Required trace events:

userspace@rtapp_main or userspace@rtapp_task or userspace@rtapp_loop or userspace@rtapp_event or userspace@rtapp_stats

df_rtapp_main()[source]

Called on Trace instances as trace.ana.rta.df_rtapp_main()

Dataframe of events generated by the rt-app main task.

Returns:

a pandas.DataFrame with:

A __comm column: the actual rt-app trace task name
A __cpu column: the CPU on which the task was running at event
generation time
A __pid column: the PID of the task
A data column: the data corresponding to the reported event
An event column: the event generated

The event column can report these events:

start: the start of the rt-app main thread execution

end: the end of the rt-app main thread execution

clock_ref: the time rt-app gets the clock to be used for logfile entries

The data column reports:

the base timestamp used for logfile generated event for the clock_ref event

NaN for all the other events

Required trace events:

userspace@rtapp_main

property rtapp_window

Return the time range the rt-app main thread executed.

Returns:

a tuple(start_time, end_time)

Required trace events:

userspace@rtapp_main

property rtapp_reftime

Return the tuple representing the kernel and user timestamp.

RTApp log events timestamps are generated by the kernel ftrace infrastructure. This method allows to know which trace timestamp corresponds to the rt-app generated timestamps stored in log files.

Returns:

a RefTime reporting kernel and user timestamps.

Required trace events:

userspace@rtapp_main

df_rtapp_task(task=None, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.rta.df_rtapp_task()

Dataframe of events generated by each rt-app generated task.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the (optional) rt-app task to filter for

Returns:

a pandas.DataFrame with:

A __comm column: the actual rt-app trace task name
A __cpu column: the CPU on which the task was running at event
generation time
A __line column: the ftrace line numer
A __pid column: the PID of the task
An event column: the event generated

The event column can report these events:

start: the start of the __pid:__comm task execution

end: the end of the __pid:__comm task execution

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

userspace@rtapp_task

df_rtapp_loop(task=None, wlgen_profile=None)[source]

Called on Trace instances as trace.ana.rta.df_rtapp_loop()

Dataframe of events generated by each rt-app generated task.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the (optional) rt-app task to filter for
wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhase) or None) – Dictionary of rt-app task names to RTAPhase used to resolve phase name from the trace and will add a properties column with the RTAPhase properties.

Returns:

a pandas.DataFrame with:

A __comm column: the actual rt-app trace task name
A __cpu column: the CPU on which the task was running at event
generation time
A __line column: the ftrace line numer
A __pid column: the PID of the task
An event column: the generated event
A phase column: the phases counter for each __pid:__comm task
A phase_loop colum: the phase_loops’s counter
A thread_loop column: the thread_loop’s counter

The event column can report these events:

start: the start of the __pid:__comm related event

end: the end of the __pid:__comm related event

Required trace events:

userspace@rtapp_loop

df_phases(task, wlgen_profile=None)[source]

Called on Trace instances as trace.ana.rta.df_phases()

Get phases actual start times and durations

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for
wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhase) or None) – See df_rtapp_loop()

Returns:

A pandas.DataFrame with index representing the start time of a phase and these column:

phase: the phase number or its name extracted from wlgen_profile.

duration: the measured phase duration.

properties: the properties mapping of the phase extracted from wlgen_profile.

Required trace events:

userspace@rtapp_loop

task_phase_windows(task, wlgen_profile=None)[source]

Called on Trace instances as trace.ana.rta.task_phase_windows()

Yield the phases of the specified task.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for
wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhaseBase) or None) – See df_phases().

Yield :class: namedtuple reporting:

id : the iteration ID

start : the iteration start time

end : the iteration end time

Returns:

Generator yielding PhaseWindow with start end end timestamps.

Required trace events:

userspace@rtapp_loop

df_rtapp_phases_start(task=None, wlgen_profile=None)[source]

Called on Trace instances as trace.ana.rta.df_rtapp_phases_start()

Dataframe of phases start times.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the (optional) rt-app task to filter for
wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhaseBase) or None) – See df_rtapp_loop()

Returns:

a pandas.DataFrame with:

A __comm column: the actual rt-app trace task name
A __pid column: the PID of the task
A phase column: the phases counter for each __pid:__comm task

The index represents the timestamp of a phase start event.

Required trace events:

userspace@rtapp_loop

df_rtapp_phases_end(task=None, wlgen_profile=None)[source]

Called on Trace instances as trace.ana.rta.df_rtapp_phases_end()

Dataframe of phases end times.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the (optional) rt-app task to filter for
wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhaseBase) or None) – See df_rtapp_loop()

Returns:

a pandas.DataFrame with:

A __comm column: the actual rt-app trace task name
A __pid column: the PID of the task
A phase column: the phases counter for each __pid:__comm task

The index represents the timestamp of a phase end event.

Required trace events:

userspace@rtapp_loop

df_rtapp_phase_start(task, phase=0, wlgen_profile=None)[source]

Called on Trace instances as trace.ana.rta.df_rtapp_phase_start()

Start of the specified phase for a given task.

A negative phase value can be used to count from the oldest, e.g. -1 represents the last phase.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for
phase (int or str) – the ID (or name with wlgen_profile) of the phase start to return.
wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhaseBase) or None) – See df_rtapp_loop()

Returns:

the requires task’s phase start timestamp

Required trace events:

userspace@rtapp_loop

df_rtapp_phase_end(task, phase=-1, wlgen_profile=None)[source]

Called on Trace instances as trace.ana.rta.df_rtapp_phase_end()

End of the specified phase for a given task.

A negative phase value can be used to count from the oldest, e.g. -1 represents the last phase.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for
phase (int or str) – the id (or name with wlgen_profile) of the phase end to return.
wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhaseBase) or None) – See df_rtapp_loop()

Returns:

the requires task’s phase end timestamp

Required trace events:

userspace@rtapp_loop

task_window(task)[source]

Called on Trace instances as trace.ana.rta.task_window()

Return the start end end time for the specified task.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for

Required trace events:

userspace@rtapp_task

task_phase_window(task, phase, wlgen_profile=None)[source]

Called on Trace instances as trace.ana.rta.task_phase_window()

Return the window of a requested task phase.

For the specified task it returns a tuple with the (start, end) time of the requested phase. A negative phase number can be used to count phases backward from the last (-1) toward the first.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for
phase (int or str) – the ID (or name with wlgen_profile) of the phase to consider.
wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhaseBase) or None) – See df_rtapp_loop()

Return type:

PhaseWindow

Required trace events:

userspace@rtapp_loop

task_phase_at(task, timestamp, wlgen_profile=None)[source]

Called on Trace instances as trace.ana.rta.task_phase_at()

Return the PhaseWindow for the specified task and timestamp.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for
timestamp (int or float) – the timestamp to get the phase for
wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhaseBase) or None) – See df_rtapp_loop()

Returns:

the ID of the phase corresponding to the specified timestamp.

Required trace events:

userspace@rtapp_loop

df_rtapp_event(task=None)[source]

Called on Trace instances as trace.ana.rta.df_rtapp_event()

Returns a pandas.DataFrame of all the rt-app generated events.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the (optional) rt-app task to filter for

Returns:

a pandas.DataFrame with:

A __comm column: the actual rt-app trace task name
A __pid column: the PID of the task
A __cpu column: the CPU on which the task was running at event
generation time
A __line column: the ftrace line numer
A type column: the type of the generated event
A desc column: the mnemonic type of the generated event
A id column: the ID of the resource associated to the event,
e.g. the ID of the fired timer

The index represents the timestamp of the event.

Required trace events:

userspace@rtapp_event

df_rtapp_stats(task=None)[source]

Called on Trace instances as trace.ana.rta.df_rtapp_stats()

Returns a pandas.DataFrame of all the rt-app generated stats.

Parameters:: task (int or str or lisa.analysis.tasks.TaskID) – the (optional) rt-app task to filter for
Returns:: a pandas.DataFrame with a set of colums representing the stats generated by rt-app after each loop.

See also

the rt-app provided documentation: https://github.com/scheduler-tools/rt-app/blob/master/doc/tutorial.txt

A __comm column: the actual rt-app trace task name
A __pid column: the PID of the task
A __cpu column: the CPU on which the task was running at event
generation time
A __line column: the ftrace line numer
A type column: the type of the generated event
A desc column: the mnemonic type of the generated event
A id column: the ID of the resource associated to the event,
e.g. the ID of the fired timer

The index represents the timestamp of the event.

Required trace events:

userspace@rtapp_stats

plot_phases(task: TaskID, wlgen_profile=None, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.rta.plot_phases()

Draw the task’s phases colored bands

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for
wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhase) or None) – See df_rtapp_loop()

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

userspace@rtapp_loop
optional: (sched_switch and sched_wakeup and one group of: task_rename and optional: sched_wakeup_new)

Example plot:

task=big_0-0, wlgen_profile={'small_0': , 'small_1': , 'small_2': , 'big_0': , 'big_1': }

plot_perf(task: TaskID, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.rta.plot_perf()

Plot the performance index.

Parameters:: task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for

The perf index is defined as:

\[perf_index = \frac{slack}{c_period - c_run}\]

where

c_period: is the configured period for an activation

c_run: is the configured run time for an activation, assuming to
run at the maximum frequency and on the maximum capacity CPU.

slack: is the measured slack for an activation

The slack is defined as the different among the activation deadline and the actual completion time of the activation.

The deadline defines also the start of the next activation, thus in normal conditions a task activation is always required to complete before its deadline.

The slack is thus a positive value if a task complete before its deadline. It’s zero when a task complete an activation right at its eadline. It’s negative when the completion is over the deadline.

Thus, a performance index in [0..1] range represents activations completed within their deadlines. While, the more the performance index is negative the more the task is late with respect to its deadline.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

userspace@rtapp_stats

Example plot:

task=big_0-0

plot_latency(task: TaskID, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.rta.plot_latency()

Plot the Latency/Slack and Performance data for the specified task.

Parameters:: task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for

See also

plot_perf() for metrics definition.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

userspace@rtapp_stats

Example plot:

task=big_0-0

plot_slack_histogram(task: TaskID, bins: int = 30, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.rta.plot_slack_histogram()

Plot the slack histogram.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for
bins (int) – number of bins for the histogram.

See also

plot_perf() for the slack definition.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

userspace@rtapp_stats

Example plot:

bins=30, task=big_0-0

plot_perf_index_histogram(task: TaskID, bins: int = 30, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.rta.plot_perf_index_histogram()

Plot the perf index histogram.

Parameters:

task (int or str or lisa.analysis.tasks.TaskID) – the rt-app task to filter for
bins (int) – number of bins for the histogram.

See also

plot_perf() for the perf index definition.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

userspace@rtapp_stats

Example plot:

bins=30, task=big_0-0

Idle

class lisa.analysis.idle.IdleAnalysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for plotting Idle Analysis data

Parameters:: trace (lisa.trace.Trace) – input Trace object

name = 'idle'

df_cpus_idle(cpus=None, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.idle.df_cpus_idle()

Dataframe of the cpu_idle event, with the following columns:

cpu

state: Instead of 4294967295, the -1 type independent value is used.

Parameters:: cpus (list(int) or None) – Optionally, filter on that list of CPUs

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

cpu_idle

df_cpu_idle(cpu=None, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.idle.df_cpu_idle()

Same as df_cpus_idle() but for one CPU.

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

cpu_idle

signal_cpu_active(cpu)[source]

Called on Trace instances as trace.ana.idle.signal_cpu_active()

Build a square wave representing the active (i.e. non-idle) CPU time

Parameters:

cpu (int) – CPU ID

Returns:

A pandas.Series that equals 1 at timestamps where the CPU is reported to be non-idle, 0 otherwise

Required trace events:

cpu_idle

signal_cluster_active(cluster)[source]

Called on Trace instances as trace.ana.idle.signal_cluster_active()

Build a square wave representing the active (i.e. non-idle) cluster time

Parameters:

cluster (list(int)) – list of CPU IDs belonging to a cluster

Returns:

A pandas.Series that equals 1 at timestamps where at least one CPU is reported to be non-idle, 0 otherwise

Required trace events:

cpu_idle

df_cpus_wakeups(*, df_fmt=None)[source]

Called on Trace instances as trace.ana.idle.df_cpus_wakeups()

Get a DataFrame showing when CPUs have woken from idle

Parameters:

cpus (list(int) or None) – List of CPUs to find wakeups for. If None, all CPUs.

Returns:

A pandas.DataFrame with

A cpu column (the CPU that woke up at the row index)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

cpu_idle

df_cpu_idle_state_residency(cpu)[source]

Called on Trace instances as trace.ana.idle.df_cpu_idle_state_residency()

Compute time spent by a given CPU in each idle state.

Parameters:

cpu (int) – CPU ID

Returns:

a pandas.DataFrame with:

Idle states as index
A time column (The time spent in the idle state)

Required trace events:

cpu_idle

df_cluster_idle_state_residency(cluster)[source]

Called on Trace instances as trace.ana.idle.df_cluster_idle_state_residency()

Compute time spent by a given cluster in each idle state.

Parameters:

cluster (list(int)) – list of CPU IDs

Returns:

a pandas.DataFrame with:

Idle states as index
A time column (The time spent in the idle state)

Required trace events:

cpu_idle

plot_cpu_idle_state_residency(cpu: CPU, pct: bool = False, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.idle.plot_cpu_idle_state_residency()

Plot the idle state residency of a CPU

Parameters:

cpu (int) – The CPU
pct (bool) – Plot residencies in percentage

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

cpu_idle

Example plot:

cpu=0, pct=False

plot_cluster_idle_state_residency(cluster: Sequence[CPU], pct: bool = False, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.idle.plot_cluster_idle_state_residency()

Plot the idle state residency of a cluster

Parameters:

cluster – The cluster
pct (bool) – Plot residencies in percentage

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

cpu_idle

Example plot:

cluster=[0, 3, 4, 5], pct=False

plot_clusters_idle_state_residency(pct: bool = False, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.idle.plot_clusters_idle_state_residency()

Plot the idle state residency of all clusters

Parameters:: pct (bool) – Plot residencies in percentage

Note

This assumes clusters == frequency domains, which may not hold true…

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

cpu_idle

Example plot:

pct=False

Latency

class lisa.analysis.latency.LatencyAnalysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for plotting Latency Analysis data

Parameters:: trace (lisa.trace.Trace) – input Trace object

name = 'latency'

LATENCY_THRESHOLD_ZONE_COLOR = '#4daf4a'

LATENCY_THRESHOLD_COLOR = '#f781bf'

df_latency_wakeup(task)[source]

Called on Trace instances as trace.ana.latency.df_latency_wakeup()

DataFrame of a task’s wakeup latencies

Parameters:

task (int or str or tuple(int, str)) – The task’s name or PID

Returns:

a pandas.DataFrame with:

A wakeup_latency column (the wakeup latency at that timestamp)
A cpu column (the CPU where the event took place)
A target_cpu column (the CPU where the task has been scheduled)

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

df_latency_preemption(task)[source]

Called on Trace instances as trace.ana.latency.df_latency_preemption()

DataFrame of a task’s preemption latencies

Parameters:

task (int or str or tuple(int, str)) – The task’s name or PID

Returns:

a pandas.DataFrame with:

A preempt_latency column (the preemption latency at that timestamp)
A cpu column (the CPU where the event took place)

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

df_activations(task, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.latency.df_activations()

DataFrame of a task’s activations

Parameters:

task (int or str or tuple(int, str)) – The task’s name or PID

Returns:

a pandas.DataFrame with:

An activation_interval column (the time since the last activation).

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

df_runtimes(task, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.latency.df_runtimes()

DataFrame of task’s runtime each time the task blocks

Parameters:

task (int or str or tuple(int, str)) – The task’s name or PID

Returns:

a pandas.DataFrame with:

The times where the task stopped running as an index
A curr_state column (the current task state, see lisa.analysis.tasks.TaskState)
A running_time column (the cumulated running time since the last activation).

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

plot_latencies(task: TaskID, wakeup: bool = True, preempt: bool = True, threshold_ms: float = 1, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.latency.plot_latencies()

Plot the latencies of a task over time

Parameters:

task (int or str or tuple(int, str)) – The task’s name or PID
wakeup (bool) – Whether to plot wakeup latencies
preempt (bool) – Whether to plot preemption latencies
threshold_ms (int or float) – The latency threshold to plot

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

Example plot:

preempt=True, task=big_0-0, threshold_ms=1, wakeup=True

plot_latencies_cdf(task: TaskID, wakeup: bool = True, preempt: bool = True, threshold_ms: float = 1, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.latency.plot_latencies_cdf()

Plot the latencies Cumulative Distribution Function of a task

Parameters:

task (int or str or tuple(int, str)) – The task’s name or PID
wakeup (bool) – Whether to plot wakeup latencies
preempt (bool) – Whether to plot preemption latencies
threshold_ms (int or float) – The latency threshold to plot

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

Example plot:

preempt=True, task=big_0-0, threshold_ms=1, wakeup=True

plot_latencies_histogram(task: TaskID, wakeup: bool = True, preempt: bool = True, threshold_ms: float = 1, bins: int = 64, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.latency.plot_latencies_histogram()

Plot the latencies histogram of a task

Parameters:

task (int or str or tuple(int, str)) – The task’s name or PID
wakeup (bool) – Whether to plot wakeup latencies
preempt (bool) – Whether to plot preemption latencies
threshold_ms (int or float) – The latency threshold to plot

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

Example plot:

bins=64, preempt=True, task=big_0-0, threshold_ms=1, wakeup=True

plot_latency_bands(task: TaskID, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.latency.plot_latency_bands()

Draw the task wakeup/preemption latencies as colored bands

Parameters:: task (int or str or tuple(int, str)) – The task’s name or PID

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

Example plot:

task=big_0-0

plot_activations(task: TaskID, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.latency.plot_activations()

Plot the lisa.analysis.latency.LatencyAnalysis.df_activations() of a task

Parameters:: task (int or str or tuple(int, str)) – The task’s name or PID

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

Example plot:

task=big_0-0

plot_runtimes(task: TaskID, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.latency.plot_runtimes()

Plot the lisa.analysis.latency.LatencyAnalysis.df_runtimes() of a task

Parameters:: task (int or str or tuple(int, str)) – The task’s name or PID

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_switch
sched_wakeup
one group of: task_rename
optional: sched_wakeup_new

Example plot:

task=big_0-0

Status

System Status Analaysis Module

class lisa.analysis.status.StatusAnalysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for System Status analysis

Parameters:: trace (lisa.trace.Trace) – input Trace object

name = 'status'

df_overutilized()[source]

Called on Trace instances as trace.ana.status.df_overutilized()

Get overutilized events

Returns:

A pandas.DataFrame with:

A overutilized column (the overutilized status at a given time)
A len column (the time spent in that overutilized status)

Required trace events:

sched_overutilized

get_overutilized_time()[source]

Called on Trace instances as trace.ana.status.get_overutilized_time()

Return the time spent in overutilized state.

get_overutilized_pct()[source]

Called on Trace instances as trace.ana.status.get_overutilized_pct()

The percentage of the time spent in overutilized state.

plot_overutilized(*, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.status.plot_overutilized()

Draw the system’s overutilized status as colored bands

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

sched_overutilized

Example plot:

Thermal

class lisa.analysis.thermal.ThermalAnalysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for plotting Thermal Analysis data

Parameters:: trace (lisa.trace.Trace) – input Trace object

name = 'thermal'

df_thermal_zones_temperature()[source]

Called on Trace instances as trace.ana.thermal.df_thermal_zones_temperature()

Get the temperature of the thermal zones

Returns:

a pandas.DataFrame with:

An id column (The thermal zone ID)
A thermal_zone column (The thermal zone name)
A temp column (The reported temperature)

Required trace events:

thermal_temperature

df_cpufreq_cooling_state(cpus=None, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.thermal.df_cpufreq_cooling_state()

Get cpufreq cooling device states

Parameters:

cpus (list(int)) – The CPUs to consider (all by default)

Returns:

a pandas.DataFrame with:

An cpus column (The CPUs affected by the cooling device)
A freq column (The frequency limit)
A cdev_state column (The cooling device state index)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

thermal_power_cpu_limit

df_devfreq_cooling_state(devices=None, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.thermal.df_devfreq_cooling_state()

Get devfreq cooling device states

Parameters:

devices – The devfreq devices to consider (all by default)

Returns:

a pandas.DataFrame with:

An cpus column (The CPUs affected by the cooling device)
A freq column (The frequency limit)
A cdev_state column (The cooling device state index)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

thermal_power_devfreq_limit

property thermal_zones

Get thermal zone ids that appear in the trace

Required trace events:

thermal_temperature

property cpufreq_cdevs

Get cpufreq cooling devices that appear in the trace

Required trace events:

thermal_power_cpu_limit

property devfreq_cdevs

Get devfreq cooling devices that appear in the trace

Required trace events:

thermal_power_devfreq_limit

plot_thermal_zone_temperature(thermal_zone_id: int, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.thermal.plot_thermal_zone_temperature()

Plot temperature of thermal zones (all by default)

Parameters:: thermal_zone_id (int) – ID of the zone

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

thermal_temperature

plot_cpu_cooling_states(cpu: CPU, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.thermal.plot_cpu_cooling_states()

Plot the state evolution of a cpufreq cooling device

Parameters:: cpu (int) – The CPU. Whole clusters can be controlled as a single cooling device, they will be plotted as long this CPU belongs to the cluster.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

thermal_power_cpu_limit

plot_dev_freq_cooling_states(device: str, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.thermal.plot_dev_freq_cooling_states()

Plot the state evolution of a devfreq cooling device

Parameters:: device (str) – The devfreq devices to consider

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Pixel 6

class lisa.analysis.pixel6.Pixel6Analysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for Pixel 6-specific data analysis

Parameters:: trace (lisa.trace.Trace) – input Trace object

name = 'pixel6'

EMETER_CHAN_NAMES = {'S2M_VDD_CPUCL2': 'CPU-Big', 'S2S_VDD_G3D': 'GPU', 'S3M_VDD_CPUCL1': 'CPU-Mid', 'S4M_VDD_CPUCL0': 'CPU-Little'}

df_power_meter(*, df_fmt=None)[source]

Called on Trace instances as trace.ana.pixel6.df_power_meter()

Get the power meter readings across the trace.

Retuns:

A pandas.DataFrame with:

A channel column (name of the power meter channel)
A power column (average power usage in mW since the last measurement)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

pixel6_emeter

plot_power_meter(channels=None, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.pixel6.plot_power_meter()

Plot the power meter readings from various channels.

Parameters:: channels (list(str)) – List of channels to plot

The channels needs to correspond to values in the channel column of df_power_meter().

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Required trace events:

pixel6_emeter

Example plot:

Function profiling

Functions Analysis Module

class lisa.analysis.functions.FunctionsAnalysis(trace, proxy=None)[source]

Bases: TraceAnalysisBase

Support for ftrace events-based kernel functions profiling and analysis

name = 'functions'

df_resolve_ksym(df, addr_col, name_col='func_name', addr_map=None, exact=True)[source]

Called on Trace instances as trace.ana.functions.df_resolve_ksym()

Resolve the kernel function names.

Note

If the addr_col is not of a numeric dtype, it will be assumed to be function names already and the content will be copied to name_col.

Parameters:

df (pandas.DataFrame) – Dataframe to augment
addr_col (str) – Name of the column containing a kernel address.
name_col – Name of the column to create with symbol names
name_col – str
addr_map (dict(int, str)) – If provided, the mapping of kernel addresses to symbol names. If missing, the symbols addresses from the lisa.platforms.platinfo.PlatformInfo attached to the trace will be used.
exact (bool) – If True, an exact symbol address is expected. If False, symbol addresses are sorted and paired to form intervals, which are then used to infer the name. This is suited to resolve an instruction pointer that could point anywhere inside of a function (but before the starting address of the next function).

df_funcgraph(event, *, df_fmt=None)[source]

Called on Trace instances as trace.ana.functions.df_funcgraph()

Return augmented dataframe of the event with the following column:

func_name: Name of the calling function if it could be resolved.

Parameters:

event (str) –

One of:

entry (funcgraph_entry event)
exit (funcgraph_exit event)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

"pandas": pandas.DataFrame
"polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

funcgraph_entry or funcgraph_exit

df_calls(tag_df=None, thread_root_functions=None, normalize=True)[source]

Called on Trace instances as trace.ana.functions.df_calls()

Return a pandas.DataFrame with a row for each function call, along some metrics:

cum_time: cumulative time spent in that function. This
includes the time spent in all children too.

self_time: time spent in that function only. This
excludes the time spent in all children.

Parameters:

tag_df (pandas.DataFrame) – Dataframe containing the tag event, which is used to tag paths in the callgraph. The __cpu column is mandatory in order to know which CPU is to be tagged at any index. Other colunms will be used as tag keys. Tags are inherited from from both parents and children. This allows a leaf function to emit an event and use it for the whole path that lead to there. Equally, if a function emits a tag, all the children of this call will inherit the tag too. This allows a top-level function to tag a whole subtree at once.
thread_root_functions (list(str) or None) – Functions that are considered to be a root of threads. When they appear in the callgraph, the profiler will consider the current function to be preempted and will not register the call as a child of it and will avoid to count it in the cumulative time.
normalize (bool) –
Normalize metrics according to the current CPU capacity so that they appear to have run on the fastest CPU at maximum frequency. This allows merging calls regardless of their origin (CPU and frequency).

Note

Normalization only currently takes into account the capacity of the CPU when the function is entered. If it changes during execution, the result will be somewhat wrong.

Note

Calls during which the current function name changes are not accounted for. They are typically a sign of functions that did not properly return, for example functions triggering a context switch and returning to userspace.

Required trace events:

funcgraph_entry or funcgraph_exit
one group of: (sched_pelt_cfs or sched_load_cfs_rq or sched_load_avg_cpu) , sched_util_est_cfs , sched_cpu_capacity

compare_with_traces(others, normalize=True, **kwargs)[source]

Called on Trace instances as trace.ana.functions.compare_with_traces()

Compare the Trace it’s called on with the other traces passed as others. The reference is the trace it’s called on.

Returns:

a lisa.stats.Stats object just like profile_stats().

Parameters:

others (list(lisa.trace.Trace)) – List of traces to compare against.

Variable keyword arguments:

Forwarded to profile_stats().

Required trace events:

funcgraph_entry or funcgraph_exit
one group of: (sched_pelt_cfs or sched_load_cfs_rq or sched_load_avg_cpu) , sched_util_est_cfs , sched_cpu_capacity

profile_stats(tag_df=None, normalize=True, ref_function=None, ref_tags=None, **kwargs)[source]

Called on Trace instances as trace.ana.functions.profile_stats()

Create a lisa.stats.Stats out of profiling information of the trace.

Parameters:

tag_df (pandas.DataFrame or None) – Dataframe of tags, forwarded to df_calls()
normalize (bool) – Normalize execution time according to CPU capacity, forwarded to to df_calls()
metric (str) –
Name of the metric to use for statistics. Can be one of:
- self_time: Time spent in the function, not accounting for time spent in children
- cum_time: Total time spent in the function, including the time spent in children.
Defaults to self_time.
functions (list(str) or None) – Restrict the statistics to the given list of function.
ref_function (str or None) – Function to compare to.
ref_tags (dict(str, set(object)) or None) – Function tags to compare to. Ignored if ref_function is None.
cpus (list(int) or None) – List of CPUs where the functions were called to take into account. If left to None, all CPUs are considered.
per_cpu (bool or None) – If True, the per-function statistics are separated for each CPU they ran on. This is useful if the frequency was fixed and the only variation in speed was coming from the CPU it ran on.
tags (dict(str, object)) – Restrict the statistics to the function tagged with the given tag values. If a function has multiple values for a given tag and one of the value is in tags, the function is selected.

Variable keyword arguments:

Forwarded to lisa.stats.Stats.

Note

Recursive calls are treated as if they were inlined in their callers. This means that the count of calls will be counting the toplevel calls only, and that the self_time for a recursive function is directly linked to how much time each level consumes multiplied by the number of levels. cum_time will also be tracked on the top-level call only to provide a more accurate result.

Required trace events:

funcgraph_entry or funcgraph_exit
one group of: (sched_pelt_cfs or sched_load_cfs_rq or sched_load_avg_cpu) , sched_util_est_cfs , sched_cpu_capacity

class lisa.analysis.functions.JSONStatsFunctionsAnalysis(stats_path)[source]

Bases: AnalysisHelpers

Support for kernel functions profiling and analysis

Parameters:: stats_path (str) – Path to JSON function stats as returned by devlib devlib.collector.ftrace.FtraceCollector.get_stats()

name = 'functions_json'

get_default_plot_path(**kwargs)[source]

Return the default path to use to save plots for the analysis.

Parameters:

img_format (str) – Format of the image to save.
plot_name (str) – Middle-name of the plot
default_dir (str) – Default folder to store plots into.

df_functions_stats(functions=None)[source]

Get a DataFrame of specified kernel functions profile data

For each profiled function a DataFrame is returned which reports stats on kernel functions execution time. The reported stats are per-CPU and includes: number of times the function has been executed (hits), average execution time (avg), overall execution time (time) and samples variance (s_2). By default returns a DataFrame of all the functions profiled.

Parameters:: functions (list(str)) – the name of the function or a list of function names to report

plot_profiling_stats(functions: str = None, metrics: str = 'avg', *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Plot functions profiling metrics for the specified kernel functions.

For each speficied metric a barplot is generated which report the value of the metric when the kernel function has been executed on each CPU. By default all the kernel functions are plotted.

Parameters:

functions (str or list(str)) – the name of list of name of kernel functions to plot
metrics (list(str)) – the metrics to plot avg - average execution time time - total execution time

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Interactive notebook helper

Notebook Analysis Module

class lisa.analysis.notebook.NotebookAnalysis(*args, **kwargs)[source]

Bases: TraceAnalysisBase

Support for custom Notebook-defined plots

This analysis provides a proxy object that can be used to turn any plot method defined in a notebook into a proper analysis plot method:

import holoviews as hv
from lisa.trace import Trace
trace = Trace('trace.dat', events=['sched_switch'])

# Define a plot method in any cell:
# The first parameter will be the trace, other parameters are free-form
def plot_foo(trace, y):
    print(f'Plotting horizontal line at level: {y}')
    return hv.HLine(y).options(color='red')

# The plot function becomes available on the "notebook.custom" proxy
# object.
trace.ana.notebook.custom.plot_foo(0.5)

name = 'notebook'

df_all_events(events=None, *, field_sep=' ', fields_as_cols=None, event_as_col=True, df_fmt=None)[source]

Called on Trace instances as trace.ana.notebook.df_all_events()

Provide a dataframe with an info column containing the textual human-readable representation of the events fields.

Parameters:

events (list(str) or None) –
List of events to include. If None, all parsed events will be used.

Note

Since events can be parsed on-demand, passing None might result in different results depending on what was done with the object. For reproducible behaviour, pass an explicit list of events.
field_sep (str) – String to use to separate fields.
fields_as_cols (list(str) or None) – List of fields to keep as separate columns rather than merged in the info column. If None, will default to a fixed set of columns.
event_as_col (bool) – If True, the event name is split in its own column.

plot_event_field(event: str, field: str, filter_columns=None, filter_f=None, *, filepath=None, output='holoviews', img_format=None, always_save=False, backend=None, _compat_render=False, link_dataframes=None, cursor_delta=None, width=None, height=None, rc_params=None, axis=None, interactive=None, colors: Sequence[str] = None, linestyles: Sequence[str] = None, markers: Sequence[str] = None, **kwargs)[source]

Called on Trace instances as trace.ana.notebook.plot_event_field()

Plot a signal represented by the filtered values of a field of an event.

Parameters:

event (str) – FTrace event name of interest.
field (str) – Name of the field of event.
filter_columns (dict or None) – Pre-filter the dataframe using lisa.datautils.df_filter(). Also, a signal will be inferred from the column names being used and will be passed to lisa.trace.TraceBase.df_event().
filter_f (collections.abc.Callable) – Function used to filter the dataframe of the event. The function must take a dataframe as only parameter and return a filtered dataframe. It is applied after filter_columns filter.

Added by lisa.analysis.base.AnalysisHelpers.plot_method():

Returns:

The return type is determined by the output parameter.

Parameters:

backend (str or None) –
Holoviews plot library backend to use:
- bokeh: good support for interactive plots
- matplotlib: sometimes better static image output, but unpredictable results that more often than not require a fair amount of hacks to get something good.
- plotly: not supported by LISA but technically available. Since it’s very similar to bokeh feature-wise, bokeh should be preferred.
Note

In a notebook, the way to choose which backend should be used to display plots is typically selected with e.g. holoviews.extension('bokeh') at the beginning of the notebook. The backend parameter is more intended for expert use where an object of the given library is required, without depending on the environment.
link_dataframes (list(pandas.DataFrame) or None) – Gated by output="ui". List of dataframes to display under the figure, which is dynamically linked with it: clicking on the plot will scroll in the dataframes and vice versa.
filepath (str or None) – Path of the file to save the figure in. If None, no file is saved.
always_save (bool) – When True, the plot is always saved even if no filepath has explicitly been set. In that case, a default path will be used.
img_format (str) – The image format to generate. Defaults to using filepath to guess the type, or “png” if no filepath is given. html and rst are supported in addition to matplotlib image formats.
output (str or None) –
Change the return value of the method:
- None: Equivalent to holoviews for now. In the future, this will be either holoviews or ui if used in an interactive jupyter notebook.
- holoviews: a bare holoviews element.
- render: a backend-specific object, such as matplotlib.figure.Figure if backend='matplotlib'
- html: HTML document
- rst: a snippet of reStructuredText
- ui: Pseudo holoviews figure, enriched with extra controls.
  
  Note
  
  No assumption must be made on the return type other than that it can be displayed in a notebook cell output (and with IPython.display.display()). The public API holoviews is implemented in a best-effort approach, so that .options() and .opts() will work, but compositions using e.g. x * y will not work if x is a holoviews element.
  
  In the midterm, the output type will be changed so that it is a real holoviews object, rather than some sort of proxy.
colors (list(str) or None) –
List of color names to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
linestyles (list(str) or None) –
List of linestyle to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
markers (list(str) or None) –
List of marker to use for the plots.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
axis (matplotlib.axes.Axes or numpy.ndarray(matplotlib.axes.Axes) or None) –
instance of matplotlib.axes.Axes to plot into. If None, a new figure and axis are created and returned.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to compose plot elements: http://holoviews.org/user_guide/Composing_Elements.html
rc_params (dict(str, object) or None) –
Matplotlib rc params dictionary overlaid on existing settings.

Deprecated since version 2.0: This parameter is deprecated, use holoviews APIs to set matplotlib options.
_compat_render (bool) – Internal parameter not to be used. This enables the compatibility mode where render=True by default when matplotlib is the current holoviews backend.

Example plot:

event=cpu_frequency, field=state, filter_columns={'cpu_id': 0}

Trace parsers

Note

lisa.trace.Trace is the class to use to manipulate a trace file, trace parsers are backend objects that are usually not manipulated by the user.

class lisa.trace.TraceParserBase(*args, **kwargs)[source]

Bases: ABC, Loggable, PartialInit

Abstract Base Class for trace parsers.

Parameters:

events – Iterable of events to parse. An empty iterable can be passed, in which case some metadata may still be available. If _ALL_EVENTS is passed, the caller may subsequently call parse_all_events().
events – collections.abc.Iterable(str)
needed_metadata (collections.abc.Iterable(str)) – Set of metadata name to gather in the parser.

The parser will be used as a context manager whenever it is queried for either events dataframes. Querying for metadata could happen immediately after object creation, but without expectation of success. Expensive metadata should only be computed when the object is used as a context manager. Note that the same parser object might be used as a context manager multiple times in its lifetime.

METADATA_KEYS = ['time-range', 'symbols-address', 'cpus-count', 'available-events', 'trace-id']: Possible metadata keys

get_parser_id()[source]: Get the unique ID of that parser. Any parameter affecting the output dataframes or metadata must be somehow part of that ID, so that the cache is not accidentally hit with stale data.

get_metadata(key)[source]

Return the metadata value.

Parameters:

key (str) –

Name of the metadata. Can be one of:

time-range: tuple (start, end) of the timestamps in the trace. This must be the first timestamp to appear in the trace, regardless of what events is being parsed. Otherwise, it would be impossible to use the time range of a parser in the mother TraceBase when requesting specific events.
symbols-address: Dictionnary of address (int) to symbol names in the kernel (str) that was used to create the trace. This allows resolving the fields of events that recorded addresses rather than function names.
cpus-count: Number of CPUs on the system the trace was collected on.
available-events: List of all available events stored in the trace. The list must be exhaustive, not limited to the events that were requested. If an exhaustive list cannot be gathered, this metadata should not be implemented.
trace-id: Unique identifier for that trace file used to
validate the cache. If not available, a checksum will be used.

Raises:

MissingMetadataError if the metadata is not available on that parser.

Note

A given metadata can only be expected to be available if asked for in the constructor, but bear in mind that there is no promise on the availability of any except for the following that must be provided if asked for:

time-range

Metadata may still be made available if not asked for, but only if it’s a very cheap byproduct of parsing that incurs no extra cost.

get_all_metadata()[source]: Collect all available metadata.

abstract parse_event(event)[source]

Parse the given event from the trace and return a pandas.DataFrame with the following columns:

Time index: floating point absolute timestamp in seconds. The index must not have any duplicated values.

One column per event field, with the appropriate dtype.

Columns prefixed with __: Header of each event, usually containing the following fields:

__cpu: CPU number the event was emitted from

__pid: PID of the current process scheduled at the time the event was emitted

__comm: Task command name going with __pid at the point the event was emitted

Parameters:: event (str) – name of the event to parse
Raises:: MissingTraceEventError – If the event cannot be parsed.

Note

The caller is free to modify the index of the data, and it must not affect other dataframes.

parse_all_events()[source]: Parse all available events.

Note

A parser that does not support querying the available-events metadata may raise an exception. This might also lead to multilple scans of the trace in some implementations.

parse_events(events, best_effort=False, **kwargs)[source]

Same as parse_event() but taking a list of events as input, and returning a mapping of event names to pandas.DataFrame for each.

Parameters:

events (list(str)) – Event names to parse.
best_effort (bool) – If True, do not raise MissingTraceEventError, silently skip the event. Must default to False.

Variable keyword arguments:

Forwarded to parse_event()

class lisa.trace.EventParserBase(event, fields)[source]

Bases: object

Base class for trace event parser.

Required attributes or properties:

event: name of the event

regex: full regex to parse a line of the event

fields: mapping of field names to pandas dtype to use for the pandas.DataFrame column.

PARSER_REGEX_TERMINALS = {'blank': ' +', 'floating': '\\d+\\.\\d+', 'identifier': '\\w+', 'integer': '\\d+'}: Snippets of regex to be used in building more complex regexes in textual trace parsers.

Note

Meant to be used with the re.ASCII flags.

class lisa.trace.TxtTraceParserBase(*args, **kwargs)[source]

Bases: TraceParserBase

Text trace parser base class.

Parameters:

lines (collections.abc.Iterable(bytes)) – Iterable of text lines as bytes.
events (list(str)) – List of events that will be available using parse_event(). If not provided, all events will be considered. .. note:: Restricting the set of events can speed up some operations.
event_parsers (list(EventParserBase)) –
Pre-built event parsers. Missing event parsers will be inferred from the fields parsed in the trace, which is costly and can lead to using larger dtypes than necessary (e.g. int64 rather than uint16).

See also

TxtEventParser
default_event_parser_cls (type) – Class used to build event parsers inferred from the trace.
pre_filled_metadata (dict(str, object) or None) – Metadata pre-filled by the caller of the constructor.

HEADER_FIELDS = {'__comm': 'string', '__cpu': 'uint32', '__event': 'string', '__pid': 'uint32', '__timestamp': 'float64'}: Pandas dtype of the header fields.

DTYPE_INFERENCE_ORDER = ['int64', 'uint64', 'float64']: When the dtype of a field is not provided by a user-defined parser, these dtypes will be tried in order to convert the column from string to something more appropriate.

Note

uint64 allows testing for hexadecimal formatting of numbers.

DEFAULT_EVENT_PARSER_CLS = None: Class used to create event parsers when inferred from the trace.

EVENT_DESCS = {}

Mapping of event names to parser description as a dict.

Each event description can include the constructor parameters of the class used as DEFAULT_EVENT_PARSER_CLS, which will be used to build event parsers from the descriptions.

If an instance of EventParserBase is passed instead of a dict, it will be used as is.

classmethod from_string(txt, path=None, *, events=None, needed_metadata=None, event_parsers=None, default_event_parser_cls=None, pre_filled_metadata=None, temp_dir)[source]

Build an instance from a single multiline string.

Parameters:: txt (bytes or str) – String containing the trace. It will be encoded as ASCII before being forwarded to the constructor if it’s not already bytes.
Variable keyword arguments:: Forwarded to __init__

classmethod from_txt_file(path, *, events=None, needed_metadata=None, event_parsers=None, default_event_parser_cls=None, pre_filled_metadata=None, temp_dir)[source]

Build an instance from a path to a text file.

Variable keyword arguments:: Forwarded to __init__

parse_event(event)[source]

Parse the given event from the trace and return a pandas.DataFrame with the following columns:

Time index: floating point absolute timestamp in seconds. The index must not have any duplicated values.

One column per event field, with the appropriate dtype.

Columns prefixed with __: Header of each event, usually containing the following fields:

__cpu: CPU number the event was emitted from

__pid: PID of the current process scheduled at the time the event was emitted

__comm: Task command name going with __pid at the point the event was emitted

Parameters:: event (str) – name of the event to parse
Raises:: MissingTraceEventError – If the event cannot be parsed.

Note

The caller is free to modify the index of the data, and it must not affect other dataframes.

get_metadata(key)[source]

Return the metadata value.

Parameters:

key (str) –

Name of the metadata. Can be one of:

time-range: tuple (start, end) of the timestamps in the trace. This must be the first timestamp to appear in the trace, regardless of what events is being parsed. Otherwise, it would be impossible to use the time range of a parser in the mother TraceBase when requesting specific events.
symbols-address: Dictionnary of address (int) to symbol names in the kernel (str) that was used to create the trace. This allows resolving the fields of events that recorded addresses rather than function names.
cpus-count: Number of CPUs on the system the trace was collected on.
available-events: List of all available events stored in the trace. The list must be exhaustive, not limited to the events that were requested. If an exhaustive list cannot be gathered, this metadata should not be implemented.
trace-id: Unique identifier for that trace file used to
validate the cache. If not available, a checksum will be used.

Raises:

MissingMetadataError if the metadata is not available on that parser.

Note

A given metadata can only be expected to be available if asked for in the constructor, but bear in mind that there is no promise on the availability of any except for the following that must be provided if asked for:

time-range

Metadata may still be made available if not asked for, but only if it’s a very cheap byproduct of parsing that incurs no extra cost.

class lisa.trace.TxtTraceParser(*args, **kwargs)[source]

Bases: TxtTraceParserBase

Text trace parser for the raw output of trace-cmd report -R trace.dat.

Parameters:

lines (collections.abc.Iterable(str)) – Iterable of text lines.
events (list(str) or None) – List of events that will be available using parse_event(). If not provided, all events will be considered. .. note:: Restricting the set of events can speed up some operations.
event_parsers (list(EventParserBase)) –
Pre-built event parsers. Missing event parsers will be inferred from the fields parsed in the trace, which is costly and can lead to using larger dtypes than necessary (e.g. int64 rather than uint16).

See also

TxtEventParser
default_event_parser_cls – Class used to build event parsers inferred from the trace.

DEFAULT_EVENT_PARSER_CLS: alias of TxtEventParser

EVENT_DESCS = {'bprint': <lisa.trace.PrintTxtEventParser object>, 'bputs': <lisa.trace.PrintTxtEventParser object>, 'cpu_frequency': {'fields': {'cpu_id': 'uint16', 'state': 'uint32'}}, 'cpu_idle': {'fields': {'cpu_id': 'uint16', 'state': 'int64'}}, 'cpuhp_enter': {'fields': {'cpu': 'uint16', 'fun': 'string', 'idx': 'uint16', 'target': 'uint16'}}, 'funcgraph_entry': {'fields': {'depth': 'uint16', 'func': 'uint64'}}, 'funcgraph_exit': {'fields': {'calltime': 'uint64', 'depth': 'uint16', 'func': 'uint64', 'overrun': 'bool', 'rettime': 'uint64'}}, 'ipi_entry': {'fields': {'reason': 'string'}, 'positional_field': 'reason', 'raw': False}, 'ipi_exit': {'fields': {'reason': 'string'}, 'positional_field': 'reason', 'raw': False}, 'ipi_raise': <lisa.trace.CustomFieldsTxtEventParser object>, 'lisa__sched_cpu_capacity': {'fields': {'capacity': 'uint16', 'capacity_curr': 'uint16', 'capacity_orig': 'uint16', 'cpu': 'uint16'}}, 'lisa__sched_overutilized': {'fields': {'overutilized': 'bool', 'span': 'string'}}, 'lisa__sched_pelt_cfs': {'fields': {'cpu': 'uint16', 'load': 'uint16', 'path': 'string', 'rbl_load': 'uint16', 'update_time': 'uint64', 'util': 'uint16'}}, 'lisa__sched_pelt_dl': {'fields': {'cpu': 'uint16', 'load': 'uint16', 'rbl_load': 'uint16', 'util': 'uint16'}}, 'lisa__sched_pelt_irq': {'fields': {'cpu': 'uint16', 'load': 'uint16', 'rbl_load': 'uint16', 'util': 'uint16'}}, 'lisa__sched_pelt_rt': {'fields': {'cpu': 'uint16', 'load': 'uint16', 'rbl_load': 'uint16', 'util': 'uint16'}}, 'lisa__sched_pelt_se': {'fields': {'comm': 'string', 'cpu': 'uint16', 'load': 'uint16', 'path': 'string', 'pid': 'int32', 'rbl_load': 'uint16', 'update_time': 'uint64', 'util': 'uint16'}}, 'lisa__sched_util_est_cfs': {'fields': {'cpu': 'uint16', 'enqueued': 'uint16', 'ewma': 'uint16', 'path': 'string', 'util': 'uint16'}}, 'lisa__sched_util_est_se': {'fields': {'comm': 'string', 'cpu': 'uint16', 'enqueued': 'uint16', 'ewma': 'uint16', 'path': 'string', 'pid': 'int32', 'util': 'uint16'}}, 'lisa__uclamp_util_cfs': {'fields': {'cpu': 'uint16', 'uclamp_avg': 'uint16', 'uclamp_max': 'uint16', 'uclamp_min': 'uint16', 'util_avg': 'uint16'}}, 'lisa__uclamp_util_se': {'fields': {'comm': 'string', 'cpu': 'uint16', 'pid': 'uint32', 'uclamp_avg': 'uint16', 'uclamp_max': 'uint16', 'uclamp_min': 'uint16', 'util_avg': 'uint16'}}, 'print': <lisa.trace.PrintTxtEventParser object>, 'sched_compute_energy': {'fields': {'comm': 'string', 'dst_cpu': 'uint16', 'energy': 'uint64', 'pid': 'uint32', 'prev_cpu': 'uint16'}}, 'sched_migrate_task': {'fields': {'comm': 'string', 'dest_cpu': 'uint16', 'orig_cpu': 'uint16', 'pid': 'uint32', 'prio': 'int16'}}, 'sched_process_wait': {'fields': {'comm': 'string', 'pid': 'uint32', 'prio': 'int16'}}, 'sched_switch': {'fields': {'next_comm': 'string', 'next_pid': 'uint32', 'next_prio': 'int16', 'prev_comm': 'string', 'prev_pid': 'uint32', 'prev_prio': 'int16', 'prev_state': 'uint16'}}, 'sched_wakeup': {'fields': {'comm': 'string', 'pid': 'uint32', 'prio': 'int16', 'target_cpu': 'uint16'}}, 'sched_wakeup_new': {'fields': {'comm': 'string', 'pid': 'uint32', 'prio': 'int16', 'success': 'bool', 'target_cpu': 'uint16'}}, 'sched_waking': {'fields': {'comm': 'string', 'pid': 'uint32', 'prio': 'int16', 'success': 'bool', 'target_cpu': 'uint16'}}, 'task_rename': {'fields': {'newcomm': 'string', 'oldcomm': 'string', 'pid': 'uint32'}}, 'thermal_power_cpu_get_power': {'fields': {'cpus': 'bytes', 'dynamic_power': 'uint32', 'freq': 'uint32', 'load': 'bytes'}, 'raw': False}, 'thermal_power_cpu_limit': {'fields': {'cdev_state': 'uint64', 'cpus': 'bytes', 'freq': 'uint32', 'power': 'uint32'}, 'raw': False}}

Mapping of event names to parser description as a dict.

Each event description can include the constructor parameters of the class used as DEFAULT_EVENT_PARSER_CLS, which will be used to build event parsers from the descriptions.

If an instance of EventParserBase is passed instead of a dict, it will be used as is.

classmethod from_dat(path, events, needed_metadata=None, event_parsers=None, default_event_parser_cls=None, *, pre_filled_metadata=None, temp_dir)[source]

Build an instance from a path to a trace.dat file created with trace-cmd.

Variable keyword arguments:: Forwarded to __init__

Note

We unfortunately cannot use -F filter option to pre-filter on some events, since global timestamp deduplication has to happen. The returned dataframe must be stable, because it could be reused in another context (cached on disk), and the set of events in a Trace object can be expanded dynamically.

class lisa.trace.MetaTxtTraceParser(*args, **kwargs)[source]

Bases: SimpleTxtTraceParser

Textual trace parser to parse meta-events.

Parameters:: time (collections.abc.Iterable(float)) – Iterable of timestamps matching lines.

Meta events are events “embedded” as a string inside the field of another event. They are expected to comply with the raw format as output by trace-cmd report -R.

HEADER_REGEX = '(?P<__event>[\\w@]+):?'

Default regex to use to parse event header. It must parse the following groups:

__timestamp: the timestamp of the event

__event: the name of the event

__cpu (optional): the CPU by which the event was emitted

__pid (optional): the currently scheduled PID at the point the event was emitted

__comm (optional): the currently scheduled task’s name at the point the event was emitted

Note

It must not capture the event fields, as it will be concatenated with the field regex of each event to parse full lines.

class DEFAULT_EVENT_PARSER_CLS(event, fields, positional_field=None, greedy_field=None, raw=True)[source]: Bases: TxtEventParser

EVENT_DESCS = {'userspace@rtapp_event': {'fields': {'desc': 'string', 'id': 'uint32', 'type': 'uint32'}}, 'userspace@rtapp_loop': {'fields': {'event': 'string', 'phase': 'uint32', 'phase_loop': 'uint32', 'thread_loop': 'uint32'}}, 'userspace@rtapp_main': {'fields': {'data': None, 'event': 'string'}}, 'userspace@rtapp_stats': {'fields': {'c_period': 'uint64', 'c_run': 'uint64', 'period': 'uint64', 'run': 'uint64', 'slack': 'uint64', 'wa_lat': 'uint64'}}, 'userspace@rtapp_task': {'fields': {'event': 'string'}}}

Mapping of event names to parser description as a dict.

Each event description can include the following dict keys:

header_regex: Regex to parse the event header. If not set, the header regex from the trace parser will be used.

fields_regex: Regex to parse the fields part of the event (i.e. the part after the header). This is the most commonly modified setting to take into account special cases in event formatting.

fields: Mapping of field names to pandas.DataFrame column dtype. This allows using a smaller dtype or the use of a non-inferred dtype like boolean.

positional_field: Name of the positional field (comming before the named fields). If None, the column will be suppressed in the parsed dataframe.

class lisa.trace.SimpleTxtTraceParser(*args, **kwargs)[source]

Bases: TxtTraceParserBase

Simple text trace parser (base) class.

Parameters:

lines (collections.abc.Iterable(str)) – Lines of the text to parse.
events (list(str)) – List of events that will be potentially parsed by parse_events(). If None, all available will be considered but that may increase the initial parsing stage.
event_parsers (list(TxtTraceParserBase)) –
Optional list of TxtTraceParserBase to provide fully customized event regex.

Note

See EVENT_DESCS for class-provided special case handling.
header_regex (str) – Regex used to parse the header of each event. See HEADER_REGEX documentation.

Note

This class is easier to customize than TxtTraceParser but may have higher processing time and peak memory usage.

EVENT_DESCS = {}

Mapping of event names to parser description as a dict.

Each event description can include the following dict keys:

header_regex: Regex to parse the event header. If not set, the header regex from the trace parser will be used.

fields_regex: Regex to parse the fields part of the event (i.e. the part after the header). This is the most commonly modified setting to take into account special cases in event formatting.

fields: Mapping of field names to pandas.DataFrame column dtype. This allows using a smaller dtype or the use of a non-inferred dtype like boolean.

positional_field: Name of the positional field (comming before the named fields). If None, the column will be suppressed in the parsed dataframe.

HEADER_REGEX = None

Default regex to use to parse event header. It must parse the following groups:

__timestamp: the timestamp of the event

__event: the name of the event

__cpu (optional): the CPU by which the event was emitted

__pid (optional): the currently scheduled PID at the point the event was emitted

__comm (optional): the currently scheduled task’s name at the point the event was emitted

Note

It must not capture the event fields, as it will be concatenated with the field regex of each event to parse full lines.

class lisa.trace.HRTxtTraceParser(*args, **kwargs)[source]

Bases: SimpleTxtTraceParser

Parse text trace in their human readable format (as opposed to the raw format).

The accepted format is the one produced by the kernel, after formatting event records with their format string. This means that format strings deviating from the classic field=value format need a custom regex.

Note

This parser is provided for convenience but is probably not complete. More specifically, it does not contain custom regex for all the events which format deviates from the raw format as output by trace-cmd report -R.

For a better supported format, see TxtTraceParser.

EVENT_DESCS = {'sched_switch': {'fields': {'next_comm': 'string', 'next_pid': 'uint32', 'next_prio': 'int16', 'prev_comm': 'string', 'prev_pid': 'uint32', 'prev_prio': 'int16', 'prev_state': 'string'}, 'fields_regex': 'prev_comm=(?P<prev_comm>.+?) +prev_pid=(?P<prev_pid>\\d+) +prev_prio=(?P<prev_prio>\\d+) +prev_state=(?P<prev_state>[^ ]+) ==> next_comm=(?P<next_comm>.+?) +next_pid=(?P<next_pid>\\d+) +next_prio=(?P<next_prio>\\d+)'}, 'tracing_mark_write': {'fields': {'buf': 'bytes'}, 'positional_field': 'buf'}}

Mapping of event names to parser description as a dict.

Each event description can include the following dict keys:

header_regex: Regex to parse the event header. If not set, the header regex from the trace parser will be used.

fields_regex: Regex to parse the fields part of the event (i.e. the part after the header). This is the most commonly modified setting to take into account special cases in event formatting.

fields: Mapping of field names to pandas.DataFrame column dtype. This allows using a smaller dtype or the use of a non-inferred dtype like boolean.

positional_field: Name of the positional field (comming before the named fields). If None, the column will be suppressed in the parsed dataframe.

HEADER_REGEX = '\\s*(?P<__comm>.+)-(?P<__pid>\\d+)[^[]*\\[(?P<__cpu>\\d*)\\][^\\d]+(?P<__timestamp>\\d+\\.\\d+): +(?P<__event>\\w+):'

Default regex to use to parse event header. It must parse the following groups:

__timestamp: the timestamp of the event

__event: the name of the event

__cpu (optional): the CPU by which the event was emitted

__pid (optional): the currently scheduled PID at the point the event was emitted

__comm (optional): the currently scheduled task’s name at the point the event was emitted

Note

It must not capture the event fields, as it will be concatenated with the field regex of each event to parse full lines.

class lisa.trace.SysTraceParser(*args, **kwargs)[source]

Bases: HRTxtTraceParser

Parse Google’s systrace format.

Note

This parser is based on HRTxtTraceParser and is therefore provided for convenience but may lack some events custom field regex.

classmethod from_html(path, *, events=None, needed_metadata=None, event_parsers=None, default_event_parser_cls=None, pre_filled_metadata=None, temp_dir)[source]

Build an instance from a path to a text file.

Variable keyword arguments:: Forwarded to __init__

class lisa.trace.TxtEventParser(event, fields, positional_field=None, greedy_field=None, raw=True)[source]

Bases: EventParserBase

Trace event parser for raw output of trace-cmd report -R trace.dat.

Parameters:

event (str) – name of the event
fields (dict(str, str)) – mapping of field name to pandas.DataFrame column dtype to use for each.
positional_field (str or None) – Name of the positional field. If None, no positional field will be parsed.
greedy_field (str or None) – Name of a greedy field that will consume the remainder of the line, no matter what the content is. This allows parsing events with a field containing a string formatted itself as an event
raw (bool) – If True, trace-cmd report will be used in raw mode. This usually ensures compliance with the format, but may sometimes be a problem. For exampe const char* are displayed as an hex pointer in raw mode, which is not helpful.

Parses events with the following format:

  devlib:     <idle>-0     [001]    76.214046: sched_wakeup: something here: comm=watchdog/1 pid=15 prio=0 success=1 target_cpu=1
  \____/     \___________________________________________/ \____________/ \_________________________________________________/
  buffer                          header                        positional                          fields
(optional)

property bytes_regex: Same as regex but acting on bytes instead of str.

class lisa.trace.CustomFieldsTxtEventParser(event, fields_regex, fields, raw)[source]

Bases: TxtEventParser

Subclass of TxtEventParser to be used for funky formats.

When the format of the textual event does not respect at all the raw trace-cmd format, and if raw format cannot be used (e.g. because of const char* fields), this class provides a way out. For example, this event can be parsed with this class, but would be impossible to be parse using TxtEventParser:

# non-raw format lacks a field delimiter for the "reason"
kworker/u16:6-262   [003]   177.417147: ipi_raise:            target_mask=00000000,00000020 (Function call interrupts)
# raw format, even less usable because of the const char* pointer not being resolved
kworker/u16:6-262   [003]   177.417147: ipi_raise:             target_cpus=ARRAY[20, 00, 00, 00, 00, 00, 00, 00] reason=0xffffff8c0774fe6b

Note

Use TxtEventParser if possible, since it provides a more optimized fields regex than what you are likely to come up with, and can deal with missing fields.

Parameters:

event (str) – Name of the event.
fields_regex (str) – Regex to parse the fields part of the event occurence. Regex groups are used to delimit fields, e.g. r"field1=(?P<field1>[0-9]+)" would recognize "field1=42" as a field1 column.
fields (dict(str, object)) – Mapping of field names (group names in the regex) to dtype to use in the pandas.DataFrame. This is passed to lisa.datautils.series_convert() so the accepted values are a bit wider than pandas dtypes.
raw (bool) – If True, the event will be parsed as raw by trace-cmd. If you have const char* fields, this must be False in order to get the string instead of the pointer.

class lisa.trace.PrintTxtEventParser(event, func_field, content_field)[source]

Bases: TxtEventParser

Event parser for the folling events, displayed in non-raw format by trace-cmd:

print

bprint

bputs

Note

bputs and print could be parsed in raw format, but that would make them harder to parse (function resolution needed), and bprint is just impossible to parse in raw format, since the data to interpolate the format string with are not displayed by trace-cmd.

class lisa.trace.TraceDumpTraceParser(*args, **kwargs)[source]

Bases: TraceParserBase

trace.dat parser shipped by LISA

classmethod from_dat(path, events, **kwargs)[source]

parse_event(event)[source]

Parse the given event from the trace and return a pandas.DataFrame with the following columns:

Time index: floating point absolute timestamp in seconds. The index must not have any duplicated values.

One column per event field, with the appropriate dtype.

Columns prefixed with __: Header of each event, usually containing the following fields:

__cpu: CPU number the event was emitted from

__pid: PID of the current process scheduled at the time the event was emitted

__comm: Task command name going with __pid at the point the event was emitted

Parameters:: event (str) – name of the event to parse
Raises:: MissingTraceEventError – If the event cannot be parsed.

Note

The caller is free to modify the index of the data, and it must not affect other dataframes.

get_metadata(key)[source]

Return the metadata value.

Parameters:

key (str) –

Name of the metadata. Can be one of:

time-range: tuple (start, end) of the timestamps in the trace. This must be the first timestamp to appear in the trace, regardless of what events is being parsed. Otherwise, it would be impossible to use the time range of a parser in the mother TraceBase when requesting specific events.
symbols-address: Dictionnary of address (int) to symbol names in the kernel (str) that was used to create the trace. This allows resolving the fields of events that recorded addresses rather than function names.
cpus-count: Number of CPUs on the system the trace was collected on.
available-events: List of all available events stored in the trace. The list must be exhaustive, not limited to the events that were requested. If an exhaustive list cannot be gathered, this metadata should not be implemented.
trace-id: Unique identifier for that trace file used to
validate the cache. If not available, a checksum will be used.

Raises:

MissingMetadataError if the metadata is not available on that parser.

Note

A given metadata can only be expected to be available if asked for in the constructor, but bear in mind that there is no promise on the availability of any except for the following that must be provided if asked for:

time-range

Metadata may still be made available if not asked for, but only if it’s a very cheap byproduct of parsing that incurs no extra cost.