Audit events

Reference for the structured audit events that every workflow action emits.

Every workflow action emits a structured JSON audit event. You don’t add logging – it’s already there. The gateway records what happened, when, and who did it, automatically.

Configuration

audit:
  sink: stderr

Four sink options:

File sink

audit:
  sink: file
  path: ./audit/
  rotation: daily

path is a directory, not a single file. The gateway creates it on first write if it doesn’t exist, then writes one JSON line per event into date-stamped .log files inside it.

Events are split into two categories per rotation window:

• {stamp}-transitions.log — events with event_type == "workflow.transition".
• {stamp}-audit.log — every other event.

audit.rotation controls the stamp granularity (defaults to daily):

Each write appends and flushes, so the trail survives a crash. Because rotation is built in, you don’t need an external rotator like logrotate.

Memory sink

audit:
  sink: memory

Keeps events in process memory. Useful in tests where you want to assert on what events were emitted without touching the filesystem.

Event shape

Every event has the same structure:

{
  "id": "evt_a1b2c3d4e5f6789012345678abcdef01",
  "timestamp": "2025-06-15T14:32:08.123456Z",
  "workflow_id": "wf_d4e5f6a1b2c3",
  "correlation_id": "cor_f6a1b2c3d4e5789012345678abcdef01",
  "actor": "agent@default",
  "event_type": "workflow.started",
  "payload": {}
}

Event types

Workflow lifecycle

Transitions

Deterministic chains

Executors

Guards

Example events

workflow.started

{
  "id": "evt_a1b2c3d4e5f6789012345678abcdef01",
  "timestamp": "2025-06-15T14:32:08.123456Z",
  "workflow_id": "wf_d4e5f6a1b2c3",
  "correlation_id": "cor_f6a1b2c3d4e5789012345678abcdef01",
  "actor": "agent@default",
  "event_type": "workflow.started",
  "payload": {
    "definitionId": "deploy_pipeline",
    "input": {
      "service": "payments",
      "environment": "staging"
    }
  }
}

transition.requested

{
  "id": "evt_b2c3d4e5f6a1789012345678abcdef02",
  "timestamp": "2025-06-15T14:32:09.456789Z",
  "workflow_id": "wf_d4e5f6a1b2c3",
  "correlation_id": "cor_a1b2c3d4e5f6789012345678abcdef02",
  "actor": "agent@default",
  "event_type": "transition.requested",
  "payload": {
    "transition": "deploy",
    "expectedVersion": 4,
    "fromState": "ready_to_deploy"
  }
}

transition.rejected

{
  "id": "evt_c3d4e5f6a1b2789012345678abcdef03",
  "timestamp": "2025-06-15T14:32:09.789012Z",
  "workflow_id": "wf_d4e5f6a1b2c3",
  "correlation_id": "cor_a1b2c3d4e5f6789012345678abcdef02",
  "actor": "agent@default",
  "event_type": "transition.rejected",
  "payload": {
    "transition": "deploy",
    "code": "GUARD_REJECTED",
    "message": "One or more guards rejected the transition."
  }
}

executor.succeeded

{
  "id": "evt_d4e5f6a1b2c3789012345678abcdef04",
  "timestamp": "2025-06-15T14:32:10.123456Z",
  "workflow_id": "wf_d4e5f6a1b2c3",
  "correlation_id": "cor_a1b2c3d4e5f6789012345678abcdef02",
  "actor": "agent@default",
  "event_type": "executor.succeeded",
  "payload": {
    "transition": "deploy",
    "candidate": 0,
    "attempt": 1,
    "kind": "cli"
  }
}

chain.completed

{
  "id": "evt_e5f6a1b2c3d4789012345678abcdef05",
  "timestamp": "2025-06-15T14:32:11.456789Z",
  "workflow_id": "wf_d4e5f6a1b2c3",
  "correlation_id": "cor_f6a1b2c3d4e5789012345678abcdef01",
  "actor": null,
  "event_type": "chain.completed",
  "payload": {
    "steps": 3,
    "finalState": "ready_to_deploy"
  }
}

Piping to your observability stack

Audit events are structured JSON, one line per event. They’re designed to be piped into whatever you already use:

• Vector – use a file source pointing at your audit log, or capture stderr with a stdin source.
• Prometheus – parse events into metrics (transitions per second, failure rate, latency histograms).
• Elasticsearch / OpenSearch – index the JSONL directly.
• CloudWatch / Datadog / Splunk – forward the log file or stderr stream through their agents.

The correlation_id field ties related events together across a single operation. The workflow_id groups everything for one workflow instance. Between the two, you can reconstruct the full story of any workflow run.

Filtering in dashboards

When querying audit records, remember: tool_name and event_type are different axes.

Filter by tool (which MCP call triggered the record):

WHERE tool_name = 'praxec.query'
  AND args->>'workflowId' IS NOT NULL

This finds all workflow-get and workflow-explain calls.

WHERE tool_name = 'praxec.command'
  AND args->>'definitionId' IS NOT NULL

This finds all workflow-start calls.

Filter by what happened (event_type in the payload):

WHERE event_type = 'workflow.started'

WHERE event_type = 'transition.requested'
  AND payload->>'transition' = 'deploy'

The two axes are complementary. tool_name answers “what did the model call?” — event_type answers “what did the runtime record as a result?”