Implementation:Mlc ai Mlc llm Event Trace Recorder Header

Overview

File: cpp/serve/event_trace_recorder.h

Purpose: Declares the abstract interface for the event trace recorder used throughout the MLC LLM serving engine. The EventTraceRecorderObj base class defines the API for recording timestamped events per request, supporting both single-request and batch-request event recording, and exporting traces in Chrome Trace Event Format. The header also provides the RECORD_EVENT convenience macro used pervasively across engine action code.

Namespace: mlc::llm::serve

Class: EventTraceRecorderObj

Inherits from tvm::runtime::Object and defines the pure virtual interface for event tracing.

Virtual Methods

virtual void AddEvent(const String& request_id, const std::string& event) = 0;

Records a single event for one request. The event string follows a naming convention:

Pattern	Meaning	Chrome Trace Phase
"start xxx"	Marks the beginning of a duration event named "xxx"	B (begin)
"finish xxx"	Marks the end of a duration event named "xxx"	E (end)
"yyy"	An instant event named "yyy"	i (instant)

Start/finish pairs are automatically matched in the trace recorder to form duration spans.

virtual void AddEvent(const Array<String>& request_ids, const std::string& event) = 0;

Records the same event for a batch of requests simultaneously. Used by batched engine actions that process multiple requests in a single GPU kernel call.

virtual std::string DumpJSON() = 0;

Serializes all recorded events to a JSON string in Chrome Trace Event Format, suitable for loading in chrome://tracing or Perfetto.

TVM Object Registration

static void RegisterReflection() {
    namespace refl = tvm::ffi::reflection;
    refl::ObjectDef<EventTraceRecorderObj>();
}

static constexpr const bool _type_has_method_sequal_reduce = false;
static constexpr const bool _type_has_method_shash_reduce = false;
static constexpr const bool _type_mutable = true;
TVM_FFI_DECLARE_OBJECT_INFO("mlc.serve.EventTraceRecorder", EventTraceRecorderObj, Object);

The object is registered as mutable since events are accumulated over time. Structural equality and hashing are disabled.

Class: EventTraceRecorder

class EventTraceRecorder : public ObjectRef {
 public:
  static EventTraceRecorder Create();
  TVM_FFI_DEFINE_OBJECT_REF_METHODS_NULLABLE(EventTraceRecorder, ObjectRef, EventTraceRecorderObj);
};

The managed reference type for EventTraceRecorderObj. Notably, this uses TVM_FFI_DEFINE_OBJECT_REF_METHODS_NULLABLE, meaning an EventTraceRecorder reference can be null. This is by design: when tracing is disabled, the recorder is stored as Optional<EventTraceRecorder> with no value, and the RECORD_EVENT macro checks for this before attempting to record.

Factory Method

Create() is the static factory method that constructs a concrete implementation of the trace recorder. The implementation is provided in event_trace_recorder.cc.

RECORD_EVENT Macro

#define RECORD_EVENT(trace_recorder, request_ids, event)  \
  if (trace_recorder.defined()) {                         \
    trace_recorder.value()->AddEvent(request_ids, event); \
  }

A convenience macro that conditionally records an event only if the trace recorder is defined (non-null). This is the primary interface used by engine action code throughout the codebase.

Parameters:

• trace_recorder: An Optional<EventTraceRecorder> instance.
• request_ids: Either a single String request ID or an Array<String> of request IDs.
• event: The event string (e.g., "start prefill", "finish decode").

Usage example in engine actions:

RECORD_EVENT(trace_recorder_, request_ids, "start proposal embedding");
// ... perform embedding computation ...
RECORD_EVENT(trace_recorder_, request_ids, "finish proposal embedding");

The macro pattern ensures zero overhead when tracing is disabled, since the defined() check short-circuits before any timestamp capture or event recording occurs.

Design Notes

• The nullable ObjectRef combined with the RECORD_EVENT macro provides a clean zero-cost-when-disabled tracing facility. Engine actions do not need to branch on whether tracing is enabled -- the macro handles it uniformly.
• The event naming convention ("start X" / "finish X") is a simple string-based protocol that avoids the need for separate begin/end API methods while still supporting duration spans in the Chrome Trace Format.
• The header is protected by include guard MLC_LLM_SERVE_EVENT_TRACE_RECORDER_H_.