lisa.trace.TraceParserBase

class lisa.trace.TraceParserBase(*args, **kwargs)

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.

Attention

This class and its base class is not subject to the normal backward compatibility guarantees. It is considered somewhat internal and will be modified if necessary, with backward compatibility being offered on a best-effort basis.

Attributes

METADATA_KEYS

Possible metadata keys.

Properties

logger inherited

Convenience short-hand for self.get_logger().

Methods

__enter__()
__exit__()
get_all_metadata()	Collect all available metadata.
get_metadata()	Return the metadata value.
get_parser_id()	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.
parse_all_events()	Parse all available events.
parse_event()	Parse the given event from the trace and return a pandas.DataFrame with the following columns:.
parse_events()	Same as parse_event() but taking a list of events as input, and returning a mapping of event names to pandas.DataFrame for each.
factory() inherited	Decorator to use on alternative constructors, i.e. classmethods that return instances of the class.
get_logger() inherited	Provides a logging.Logger named after cls.
log_locals() inherited	Debugging aid: log the local variables of the calling function.

Attributes

TraceParserBase.METADATA_KEYS = ['time-range', 'symbols-address', 'cpus-count', 'available-events', 'trace-id']

Possible metadata keys

Properties

property TraceParserBase.logger

Inherited property, see lisa.utils.Loggable.logger

Convenience short-hand for self.get_logger().

Methods

TraceParserBase.__enter__()

TraceParserBase.__exit__(*args, **kwargs)

TraceParserBase.get_all_metadata()

Collect all available metadata.

TraceParserBase.get_metadata(key)

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.

TraceParserBase.get_parser_id()

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.

TraceParserBase.parse_all_events()

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.

abstract TraceParserBase.parse_event(event)

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.

TraceParserBase.parse_events(events, best_effort=False, **kwargs)

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()

classmethod TraceParserBase.factory(f)

Inherited method, see lisa.utils.PartialInit.factory()

Decorator to use on alternative constructors, i.e. classmethods that return instances of the class.

classmethod TraceParserBase.get_logger(suffix=None)

Inherited method, see lisa.utils.Loggable.get_logger()

Provides a logging.Logger named after cls.

classmethod TraceParserBase.log_locals(var_names=None, level='debug')

Inherited method, see lisa.utils.Loggable.log_locals()

Debugging aid: log the local variables of the calling function.