Implementation:Mlc ai Mlc llm Event Trace Recorder Py

Overview

python/mlc_llm/serve/event_trace_recorder.py provides the EventTraceRecorder class, a Python wrapper around a C++ TVM runtime object for recording and exporting request-level events in the MLC LLM serving engine. Events are logged in Chrome Trace Event Format, enabling visualization with tools such as chrome://tracing or Perfetto.

Location

• File: python/mlc_llm/serve/event_trace_recorder.py
• Module: mlc_llm.serve.event_trace_recorder
• Lines: 41

Class: EventTraceRecorder

@tvm_ffi.register_object("mlc.serve.EventTraceRecorder")
class EventTraceRecorder(Object):
    """The event trace recorder for requests."""

    def __init__(self) -> None:
        self.__init_handle_by_constructor__(
            _ffi_api.EventTraceRecorder
        )

The class is registered as a TVM FFI object with the name mlc.serve.EventTraceRecorder. It inherits from tvm.runtime.Object and delegates all construction and method calls to the C++ implementation via FFI.

Constructor

The constructor takes no parameters and initializes the underlying C++ EventTraceRecorder object via __init_handle_by_constructor__. This creates an empty trace recorder ready to receive events.

add_event

def add_event(self, request_id: str, event: str) -> None:

Records a single event associated with a specific request.

Parameters:

Parameter	Type	Description
request_id	str	The subject request that the event belongs to
event	str	The event name following a specific naming convention

Event naming convention:

• "start xxx" -- Marks the beginning of a duration event named "xxx"
• "finish xxx" -- Marks the end of a duration event named "xxx"
• "yyy" -- Marks an instant event named "yyy"

Start and finish events with matching names are automatically paired by the underlying C++ implementation to form duration events in the trace output.

Implementation:

return _ffi_api.EventTraceRecorderAddEvent(self, request_id, event)

dump_json

def dump_json(self) -> str:

Serializes all logged events to a JSON string in Chrome Trace Event Format.

Returns: A JSON string that can be loaded directly into Chrome's chrome://tracing viewer or Perfetto for visualization.

Implementation:

return _ffi_api.EventTraceRecorderDumpJSON(self)

Usage Context

The EventTraceRecorder is used by the serving engine when tracing is enabled. It is accessed through async_engine.state.trace_recorder and its output is exposed via the /debug/dump_event_trace debug endpoint (see Debug Entrypoints).

Dependencies

• tvm_ffi: For TVM object registration via @tvm_ffi.register_object.
• tvm.runtime.Object: Base class for TVM FFI-backed objects.
• _ffi_api: The local FFI module providing access to EventTraceRecorder, EventTraceRecorderAddEvent, and EventTraceRecorderDumpJSON C++ functions.

Design Notes

• The class is a thin Python wrapper; all actual event storage and trace formatting logic lives in the C++ implementation.
• The Chrome Trace Event Format output enables integration with standard profiling visualization tools without custom viewers.
• The automatic pairing of "start" and "finish" events simplifies the API -- callers do not need to manually track duration event pairs.