lisa.trace.TraceBase#

class lisa.trace.TraceBase[source]#

Bases: ABC

Base class for all public trace classes.

This abc.ABC class defines the API available on trace-like objects, and is suitable to use with isinstance and issubclass.

Properties

ana

Allows calling an analysis method on the trace, sharing the dataframe cache.

available_events

Set of available events on that trace.

basetime

Absolute timestamp when the tracing started.

end

The timestamp of the last trace event.

endtime

Absolute timestamp when the tracing stopped.

start

The timestamp of the first trace event.

time_range

Duration of that trace (difference between start and end).

trace_state

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

window

Same as (trace.start, trace.end).

Methods

__enter__()

__exit__()

__getitem__()

Slice the trace with the given time range.

df_event()

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

get_view()

Get a view on a trace.

show()

Open the parsed trace using the most appropriate native viewer.

Properties#

abstract property TraceBase.ana[source]#

Allows calling an analysis method on the trace, sharing the dataframe cache.

Example

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

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

The trace.ana 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')
property TraceBase.available_events#

Set of available events on that trace.

Warning

The set of events can change as new events are parsed. Not all trace parsers are able to provide the list of events that could be parsed upfront, so do not rely on this set to be stable. However, using event in trace.available_events will always return True if the event can be parsed, possibly at the cost of actually parsing the event to check if that works.

abstract property TraceBase.basetime#

Absolute timestamp when the tracing started.

This might differ from start as the latter can be affected by various normalization or windowing features.

abstract property TraceBase.end#

The timestamp of the last trace event.

abstract property TraceBase.endtime#

Absolute timestamp when the tracing stopped.

This might differ from end as the latter can be affected by various normalization or windowing features.

Note

With some parsers, that might be the timestamp of the last recorded event instead if the trace end timestamp was not recorded.

abstract property TraceBase.start#

The timestamp of the first trace event.

property TraceBase.time_range#

Duration of that trace (difference between start and end).

property TraceBase.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.

property TraceBase.window#

Same as (trace.start, trace.end).

This is handy to pass to functions expecting a window tuple.

abstract property TraceBase.analysis[source]#

Deprecated since version 3.0.

analysis() is deprecated and will be removed in version 4.0, use lisa.trace.TraceBase.ana instead

property TraceBase.task_ids[source]#

List of all the lisa.analysis.tasks.TaskID in the trace, sorted by PID.

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

Methods#

abstract TraceBase.__enter__()#
abstract TraceBase.__exit__(*args)#
TraceBase.__getitem__(window)#

Slice the trace with the given time range.

abstract TraceBase.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.

TraceBase.get_view(**kwargs)#

Get a view on a trace.

Various aspects of the trace can be altered depending on the parameters, such as cropping time-wise to fit in window.

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.

TraceBase.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.

TraceBase.add_events_deltas(df, col_name='delta', inplace=True)#

Store the time between each event in a new dataframe column

This function assumes that at time [n] the event starts and at [n+1] the event stops, so the formula for the returned value is:

      |        |            |
      |        |            |
      |        |            |
------+--------+------------+------
    [n-1]     [n]         [n+1]

delta[n] = index[n+1] - index[n]
Parameters:

  • df (pandas.DataFrame) – The DataFrame to operate one

  • col_name (str) – The name of the column to add

  • inplace (bool) – Whether to operate on the passed DataFrame, or to use a copy of it

This method only really makes sense for events tracking an on/off state (e.g. overutilized, idle)

Deprecated since version 2.0.

add_events_deltas() is deprecated and will be removed in version 4.0, use lisa.datautils.df_add_delta() instead: Prefer adding delta once signals have been extracted from the event dataframe for correctness

TraceBase.df_all_events(*args, **kwargs)#

Deprecated since version 2.0.

df_all_events() is deprecated and will be removed in version 4.0, use lisa.analysis.notebook.NotebookAnalysis.df_all_event instead: This method has been deprecated and is an alias for “trace.ana.notebook.df_all_events()”

TraceBase.df_events(*args, **kwargs)[source]#

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

TraceBase.get_task_by_name(name)[source]#

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

TraceBase.get_task_by_pid(*args, **kwargs)[source]#

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

TraceBase.get_task_id(*args, **kwargs)[source]#

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

TraceBase.get_task_ids(*args, **kwargs)[source]#

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

TraceBase.get_task_name_pids(*args, **kwargs)[source]#

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

TraceBase.get_task_pid(*args, **kwargs)[source]#

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

TraceBase.get_task_pid_names(*args, **kwargs)[source]#

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

TraceBase.get_tasks(*args, **kwargs)[source]#

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