lisa.trace.TxtTraceParserBase

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

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.

Attributes

DEFAULT_EVENT_PARSER_CLS	Class used to create event parsers when inferred from the trace.
DTYPE_INFERENCE_ORDER	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.
EVENT_DESCS	Mapping of event names to parser description as a dict.
HEADER_FIELDS	Pandas dtype of the header fields.
METADATA_KEYS inherited	Possible metadata keys.

Properties

logger inherited

Convenience short-hand for self.get_logger().

Methods

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

Attributes

TxtTraceParserBase.DEFAULT_EVENT_PARSER_CLS = None

Class used to create event parsers when inferred from the trace.

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

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

TxtTraceParserBase.HEADER_FIELDS = {'__comm': 'string', '__cpu': 'uint32', '__event': 'string', '__pid': 'uint32', '__timestamp': 'float64'}

Pandas dtype of the header fields.

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

Inherited attribute, see lisa.trace.TraceParserBase.METADATA_KEYS

Possible metadata keys.

Properties

property TxtTraceParserBase.logger

Inherited property, see lisa.utils.Loggable.logger

Convenience short-hand for self.get_logger().

Methods

classmethod TxtTraceParserBase.from_string(txt, path=None, *, events=None, needed_metadata=None, event_parsers=None, default_event_parser_cls=None, pre_filled_metadata=None, temp_dir)

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 TxtTraceParserBase.from_txt_file(path, *, events=None, needed_metadata=None, event_parsers=None, default_event_parser_cls=None, pre_filled_metadata=None, temp_dir)

Build an instance from a path to a text file.

Variable keyword arguments:

Forwarded to __init__

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

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

TxtTraceParserBase.__enter__()

Inherited method, see lisa.trace.TraceParserBase.__enter__()

TxtTraceParserBase.__exit__(*args, **kwargs)

Inherited method, see lisa.trace.TraceParserBase.__exit__()

classmethod TxtTraceParserBase.factory(f)

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

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

TxtTraceParserBase.get_all_metadata()

Inherited method, see lisa.trace.TraceParserBase.get_all_metadata()

Collect all available metadata.

classmethod TxtTraceParserBase.get_logger(suffix=None)

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

Provides a logging.Logger named after cls.

TxtTraceParserBase.get_parser_id()

Inherited method, see lisa.trace.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.

classmethod TxtTraceParserBase.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.

TxtTraceParserBase.parse_all_events()

Inherited method, see lisa.trace.TraceParserBase.parse_all_events()

Parse all available events.

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

Inherited method, see lisa.trace.TraceParserBase.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.