Module: trace

Trace Module

Captures structured, replayable execution history as W3C-compatible spans and segments for auditing and debugging.

Status: Frozen

Usage Boundary: This page provides an evaluative summary and a canonical schema excerpt for convenience. The authoritative, versioned specification remains on docs.mplp.io. MPGC does not issue certifications, badges, or endorsements; adoption and conformance are self-assessed by the adopting organization.

Definition

Protocol Role

The normative responsibility of this module.

The Trace module provides the evidence-grade audit layer for all MPLP executions.

It captures the execution history — what actually happened during Plan execution — as W3C-compatible spans and segments.

Within the MPLP lifecycle, Trace is responsible for:

  • Recording what happened (actions, decisions, state changes),
  • Enabling replay and debugging of agent behavior,
  • Providing auditability for compliance and governance,
  • Supporting observability across distributed systems.

Trace does not control execution; it provides the normative record that makes MPLP observable and auditable.

Architecture

Interaction Model

Dependencies and event emissions.

The Trace module operates as the observability layer that records all execution activity.

Dependencies

  • Context: Every Trace MUST be anchored to a valid context_id.
  • Plan: Traces MAY reference a plan_id when recording plan execution.

Emissions & Observability

  • Trace segments are append-only during execution.
  • Terminal status Traces become stable and append-only (cannot be modified).
  • Traces emit events that can be consumed by external observability systems.

Usage in Golden Flows

The Trace module provides the audit trail for:

  • Golden Flow 01 — Single-Agent Task Execution
  • Golden Flow 03 — Multi-Agent Task Coordination
  • Golden Flow 06 — Post-Execution Audit & Review

Compliance

Normative Constraints

MUST / SHOULD / MUST NOT requirements.

The following constraints are normative and MUST be enforced by any MPLP-conformant implementation:

  1. A Trace MUST reference a valid context_id.
  2. A Trace MUST have a root_span that anchors all segments.
  3. Trace segments MUST be append-only during active execution.
  4. A Trace in terminal status (completed, failed, cancelled) MUST NOT be modified.
  5. Segment timestamps MUST be monotonically increasing within a trace.
  6. All Trace mutations MUST be traceable and auditable themselves.

Failure to meet these constraints results in a non-conformant execution.

Specification

Canonical Schema

The normative JSON structure for this module.

{
  "required": [
    "meta",
    "trace_id",
    "context_id",
    "root_span",
    "status"
  ],
  "optional": [
    "plan_id",
    "started_at",
    "finished_at",
    "segments",
    "events",
    "governance"
  ],
  "segmentObject": {
    "required": [
      "segment_id",
      "label",
      "status"
    ],
    "optional": [
      "parent_segment_id",
      "started_at",
      "finished_at",
      "attributes"
    ]
  }
}

Behavior

Lifecycle

Valid states and transitions.

Status Enum

pendingrunningcompletedfailedcancelled

Quick Links

View Full Spec← Back to Modules

Evaluation Path

Governance → Compliance → Golden Flows → Adoption Signals

Enterprise Guide Governance Compliance Golden Flows Adoption