trazer.trace#

class trazer.trace.EventChain(name: str)#

Bases: Trace

An event chain consists of a set of related events. It is basically a subset of a trace.

as_event_pair()#

Represent the even chain as a pair of (TraceEventDurationBegin, TraceEventDurationEnd) The events in the event pair have the same name as the event chain. The two events has the timestamps of the begin and end events respectively.

Returns:

The event pair.

property begin_event: TraceEvent#

Get the first event in the event chain.

Returns:

The first event.

property dur: float#

Get the duration of the event chain.

Returns:

The time difference between the last and the first event in the event chain.

property end_event: TraceEvent#

Get the last event in the event chain. :return: The last event.

property ts: float#

Get the timestamp of the beginning of the event chain.

Returns:

The timestamp of the first event in the event chain.

class trazer.trace.Trace#

Bases: object

A Trace contains all collected trace events and can be exported into different trace file formats for further processing in other tools, e.g. for visualization.

add_event(event: TraceEvent)#

Add a trace event into the trace.

Parameters:

event – The event instance to be appended.

Returns:

None

add_events(events: Iterable[TraceEvent])#

Add trace events from an iterable into the trace.

Parameters:

events – An iterable providing trace events.

Returns:

None

add_flow(name: str, src: TraceEventDurationBegin, dest: TraceEventDurationBegin)#

Add a flow from one duration to another. It is a little bit tricky to derive the timestamps for the flow events. The start and end points of the flow need to be bound to “slices”, i.e. the duration bars in the trace visualization. The exact slice to be bound to is determined by the timestamp of the respective flow event.

The general rule is: - The start point is bound to the most recent enclosing slice, if multiple slices cover the start timestamp. - The end point is bound to the next slice that begins, which is closest to the end timestamp.

For Perfetto v20.1, the end timestamp needs to be strictly smaller than the slice to be bound to.

Parameters:

  • name – The name of the flow.

  • src – The begin of the source duration.

  • dest – The begin of the destination duration.

Returns:

None

property metadata_events: list[trazer.trace.TraceEventMetadata]#

Get a list of metadata events for the trace. It contains the metadata events for process and thread names.

Returns:

A list of TraceEventMetadata.

set_process_name(pid: int, name: str)#

Set the process name for the process identified by pid.

Parameters:

  • pid – Process id.

  • name – Process name.

Returns:

None

set_thread_name(pid: int, tid: int, name: str)#

Set the thread name for the thread identified by pid and tid.

Parameters:

  • pid – Process id.

  • tid – Thread id.

  • name – Thread name.

Returns:

None

to_tef_json(file_like: IO[str] | None = None) → dict[str, Any] | None#

Get the JSON in Trace Event Format The string can be written into a JSON file for the visualization in Chrome `chrome://tracing`.

Parameters:

file_like – A file-like object for writing the JSON.

Returns:

The JSON dict or None if file_path is provided.

class trazer.trace.TraceEvent(event_name: str, ts: float | None = None, pid: int | None = None, tid: int | None = None, **kwargs)#

Bases: ABC

An abstract class containing the basic properties for a trace event.

property tef#

Get a dict containing the properties required for the Trace Event Format.

Returns:

A dict with properties from Trace Event Format

class trazer.trace.TraceEventCounter(name, ts, value, pid=0, tid=0)#

Bases: TraceEvent

A TraceEvent representing a utility event containing a counter which changes with time.

class trazer.trace.TraceEventDurationBegin(event_name: str, ts: float, pid: int = 0, tid: int = 0, **kwargs)#

Bases: TraceEvent

A TraceEvent representing the beginning of an event with certain duration. The complete span of an event with certain duration is defined by its corresponding TraceEventDurationBegin and TraceEventDurationEnd

class trazer.trace.TraceEventDurationEnd(event_name: str, ts: float, pid: int = 0, tid: int = 0, **kwargs)#

Bases: TraceEvent

A TraceEvent representing the end of an event with certain duration. The complete span of an event with certain duration is defined by its corresponding TraceEventDurationBegin and TraceEventDurationEnd

class trazer.trace.TraceEventFlowEnd(name: str, ts: float, pid: int, tid: int, id_: int, **kwargs)#

Bases: TraceEvent

A TraceEvent representing the end of a flow.

class trazer.trace.TraceEventFlowStart(name: str, ts: float, pid: int, tid: int, id_: int, **kwargs)#

Bases: TraceEvent

A TraceEvent representing the start of a flow.

class trazer.trace.TraceEventInstant(event_name: str, ts: float | None = None, pid: int | None = None, tid: int | None = None, **kwargs)#

Bases: TraceEvent

A TraceEvent representing an instantaneous event without any duration.

class trazer.trace.TraceEventMetadata(metadata_name: str, *, pid: int | None = None, tid: int | None = None, **kwargs)#

Bases: TraceEvent

A TraceEvent representing a metadata event for associating extra information with the events in the trace.