What Is the Runtime Event Log in Apache Maka? A Complete Technical Guide

The Runtime Event Log in Apache Maka is an append-only, persistent log that records every significant event occurring during runtime execution—including timestamps, event types, JSON payloads, correlation IDs, and optional state snapshots—to enable deterministic replay, crash recovery, and full auditability of agent and workflow executions.

The Runtime Event Log serves as the backbone of Apache Maka's execution engine, providing a comprehensive record of activities within the runtime host that executes skills, agents, and LLM-driven workflows. As implemented in apache/maka, this component ensures that every state transition, task lifecycle event, and error condition is captured with nanosecond precision for later analysis or recovery.

What Information Does the Runtime Event Log Store?

The log captures five distinct categories of data, each designed to support specific debugging, auditing, and recovery scenarios.

Core Event Structure

Every entry in the Runtime Event Log contains precise monotonic timestamps measured in nanoseconds. These timestamps allow the system to reconstruct the exact chronological order of events, which is critical for latency analysis and time-travel debugging.

The event type field stores a short string identifier describing the nature of the occurrence. Common event types defined in the architecture include workspace.created, checkpoint.saved, task.started, task.completed, error.thrown, and resource.leak.

Each event carries a JSON-serialized payload containing type-specific metadata. For example, a checkpoint.saved event includes the checkpoint ID, data size, and checksum, while an error.thrown event captures the full stack trace and originating component name.

Correlation and Distributed Tracing

The log assigns UUID-based correlation IDs to link related events across the system. These identifiers connect lifecycle events such as a task.started event with its corresponding task.completed event, enabling developers to trace the complete execution path of a single logical operation through complex multi-agent workflows.

Optional Runtime State Snapshots

For performance-sensitive deployments, the Runtime Event Log can optionally store runtime state snapshots. These periodic captures include the current workspace graph, active agent registrations, and resource quota allocations. While these snapshots increase storage overhead, they reduce recovery time by providing known-good restoration points. According to docs/architecture/runtime-host-architecture.md, this feature can be toggled via configuration to balance durability against performance requirements.

How the Runtime Event Log Enables Crash Recovery

The durability guarantees of the Runtime Event Log are formally specified in docs/architecture/runtime-resume-phase0-crash-contract.md. This document establishes the invariant that the log must survive process crashes and serve as the source of truth for recovery operations.

When a Maka runtime host writes to the event log, it does so atomically. This ensures that even if the host process terminates unexpectedly, the log remains consistent without partial writes or corruption. During recovery, the runtime reads the log from the last known checkpoint and resumes execution from that point, guaranteeing at-least-once processing semantics for all tasks and agent operations.

The docs/architecture/runtime-resume-architecture.md file details how the replay mechanism reconstructs the runtime state by feeding recorded events back into a fresh host instance. This deterministic replay capability allows developers to recreate exact execution paths for debugging or compliance verification.

Working with the Runtime Event Log in Code

The @maka/runtime SDK provides TypeScript interfaces for consuming, parsing, and replaying event logs.

Subscribing to Live Events

You can attach listeners to observe events as they occur in real time:

import { Runtime, RuntimeEvent } from '@maka/runtime';

const runtime = new Runtime();

// Subscribe to all runtime events
runtime.eventLog.on('event', (ev: RuntimeEvent) => {
  console.log(`[${ev.timestamp}] ${ev.type}`, ev.payload);
});

await runtime.start();

Reading Persisted Log Files

The default log location is <runtime-data-dir>/event.log, though this path is configurable. Each line represents a single JSON object:

import { readFileSync } from 'fs';
import { parseEventLog } from '@maka/runtime';

const rawLog = readFileSync('/var/lib/maka/event.log', 'utf-8');
const events = parseEventLog(rawLog);

// Locate the most recent checkpoint
const lastCheckpoint = events
  .filter(e => e.type === 'checkpoint.saved')
  .pop();

console.log('Recovery point:', lastCheckpoint?.payload?.checkpointId);

Replaying Logs for Recovery

To resume a crashed workspace from its event log:

import { Runtime, ReplayOptions } from '@maka/runtime';
import { readFileSync } from 'fs';

const logData = readFileSync('/var/lib/maka/event.log', 'utf-8');
const replayOpts: ReplayOptions = { fromCheckpoint: 'latest' };

const recoveredRuntime = await Runtime.replay(logData, replayOpts);
await recoveredRuntime.resume();

Key Architecture Documents

The following files in the apache/maka repository define the Runtime Event Log's behavior and integration points:

• docs/architecture/runtime-host-architecture.md – Describes how the host routes events to the log and how UI and diagnostic tools subscribe to the event stream.
• docs/architecture/runtime-resume-phase0-crash-contract.md – Establishes the formal durability contract and crash recovery protocol.
• docs/architecture/runtime-resume-architecture.md – Details the checkpoint and replay logic used during runtime resume operations.
• docs/architecture/runtime-managed-workspace-owner-v1.md – Specifies how workspace ownership metadata is stored in the log for multi-tenant isolation.
• docs/architecture/llm-compaction-events-log-projection-draft.md – Explains projections of LLM-generated events into the log format for downstream analysis.

Summary

• The Runtime Event Log is an append-only, atomic log that stores timestamps (nanoseconds), event types, JSON payloads, correlation UUIDs, and optional state snapshots.
• It enables deterministic replay for debugging and time-travel analysis by feeding recorded events into fresh runtime hosts.
• Crash recovery relies on the log's durability guarantees defined in runtime-resume-phase0-crash-contract.md, ensuring at-least-once processing semantics.
• Developers interact with the log via the @maka/runtime SDK using RuntimeEvent listeners, parseEventLog() for file reading, and Runtime.replay() for recovery scenarios.
• The log supports multi-tenant scenarios through workspace ownership metadata and can be configured to exclude state snapshots in performance-critical deployments.

Frequently Asked Questions

How does the Runtime Event Log ensure data consistency during a crash?

The log is written atomically by the runtime host, ensuring that partial writes cannot occur even if the process terminates unexpectedly. According to docs/architecture/runtime-resume-phase0-crash-contract.md, this atomicity guarantee ensures the log remains consistent and readable for recovery operations, serving as the single source of truth for restoring runtime state.

What is the difference between a checkpoint and a regular event in the log?

A checkpoint (event type checkpoint.saved) represents a deliberate persistence point that includes a full state snapshot and unique checkpoint ID, allowing the runtime to resume from that specific point. Regular events such as task.started or error.thrown represent incremental state changes that are replayed sequentially from the last checkpoint during recovery.

Can the Runtime Event Log be used for performance monitoring?

Yes. By aggregating the nanosecond-precision timestamps stored in event payloads, developers can calculate detailed latency breakdowns between task.started and task.completed events. The correlation IDs enable tracing request flows across distributed agents, while the optional state snapshots help identify resource utilization patterns over time.

Where is the Runtime Event Log physically stored?

By default, the log is written to <runtime-data-dir>/event.log as a newline-delimited JSON file. The storage path is configurable through the runtime host settings, as documented in docs/architecture/runtime-host-architecture.md. For production deployments, this directory should reside on durable storage to satisfy the crash contract's durability requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}