trazer.analyzer#

class trazer.analyzer.TraceAnalyzer(trace: Trace)#

Bases: object

match(event_pattern: str, event_chain_name: str, exclusive_wildcard: bool = True) → list[trazer.trace.EventChain]#

Match a specific event sequence by the given event_pattern. A new EventChain is created for each matched event sequence and is added into the event_chains attribute. Event chains and original trace can be exported into different groups so that they can be visualized in the same view.

For example, we have an event sequence for processing a network message:

  • 0.001 s: Begin receive_request_msg

  • 0.002 s: Begin process_request_msg

  • 0.003 s: End process_request_msg

  • 0.004 s: Begin prepare_response_msg

  • 0.005 s: End prepare_response_msg

  • 0.006 s: Begin send_response_msg

  • 0.007 s: End send_response_msg

  • 0.008 s: End receive_request_msg

Let’s assume that the events are to be stored in the network_trace object.

>>> network_trace = Trace()
>>> network_trace.add_events([
...     TraceEventDurationBegin('receive_request_msg', 1),  # Unit of timestamp is millisecond
...     TraceEventDurationBegin('process_request_msg', 2),
...     TraceEventDurationEnd('process_request_msg', 3),
...     TraceEventDurationBegin('prepare_response_msg', 4),
...     TraceEventDurationEnd('prepare_response_msg', 5),
...     TraceEventDurationBegin('send_response_msg', 6),
...     TraceEventDurationBegin('send_response_msg', 7),
...     TraceEventDurationEnd('receive_request_msg', 8)
... ])

If we focus on the duration of request and response, respectively, we can merge the request-related events into an request-event and response-related events into an response-event by calling

>>> trace_analyzer = TraceAnalyzer(network_trace)
>>> requests = trace_analyzer.match('receive_request_msg+*process_request_msg-', 'request_event_chain')
>>> responses = trace_analyzer.match('prepare_response_msg+*receive_request_msg-', 'response_event_chain')

Usage of symbols in event_pattern:

  • ‘+’ following an event name: the event begins

  • ‘-’ following an event name: the event ends

  • ‘*’: arbitrary events

The matched event chains are returned in a list.

>>> requests[0]
[1 - 3 ms]: request_event_chain (3 events)
>>> responses[0]
[4 - 8 ms]: response_event_chain (5 events)

>>> print('\n'.join(map(str, trace_analyzer.event_chains)))
[1 - 3 ms]: request_event_chain (3 events)
[4 - 8 ms]: response_event_chain (5 events)
Parameters:

  • event_pattern – A string for matching an event sequence.

  • event_chain_name – The name of the event chain for the matched event sequence.

  • exclusive_wildcard – Whether explicitly specified events should be excluded from the wildcard.

Returns:

A list of matched event chains.

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

Merge the event chains with the original trace so that they can be visualized in the same view. Each of the event chain is represented as a pair of begin and end events. Export the merged trace in Trace Event Format JSON.

The export works on a copy, so the original trace events are not modified.

Parameters:

  • event_chain_pid – Process ID for the event chains.

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

Returns:

The JSON dict or None if file_path is provided.