Machine JSON Logging

--machine-log-json makes mydumper and myloader emit one JSON object per line to stderr or to --logfile.

This mode is intended for automation, CI jobs, watchdogs, and log shippers.

Stability

The JSON contract is versioned by:

• schema_version
• event_version

Consumers should reject or explicitly handle unknown future versions.

Guaranteed Fields

Every machine-log event contains these fields:

• schema_version
• event_version
• seq
• run_id
• kind
• ts
• level
• tool
• program
• pid
• event
• phase
• status
• fatal

parent_seq is also present when the current event has a causal predecessor in the same thread.

Optional Fields

These fields are emitted only when relevant:

• thread
• domain
• message
• parent_seq
• retryable
• mysql_errno
• error_code
• sqlstate
• object_id
• job_id
• chunk_id

Domain-specific events may also add fields such as:

• db
• table
• filename
• part_index
• thread_id
• connection_id
• rows_done
• rows_total
• progress_pct
• tables_total
• tables_remaining
• duration_ms
• exit_code
• tables
• files
• bytes
• errors
• warnings
• retries
• skipped

Unknown extra fields must be ignored by consumers.

Status Contract

Structured machine events use these statuses:

• started
• progress
• finished
• failed
• cancelled
• warning

Event Types

Preferred events are domain events such as:

• process_config
• process_version
• dump_started
• dump_completed
• restore_completed
• restore_sql
• restore_file
• checksum_check

If a call site still uses a generic wrapper instead of a dedicated domain event, the fallback event name is:

• process_notice
• process_warning
• process_error

Those fallback events still carry the standard machine fields and may include source_api to indicate which wrapper emitted them.

Sequencing

• seq is a process-wide monotonically increasing event number.
• parent_seq points to the previous causal event on the same thread when available.
• run_id is a UUIDv7 identifying the whole process execution.

Completion Summary

Completion events currently include:

• dump_completed
• restore_completed

Their counters are intended for machine use and include:

• tables
• files
• bytes
• errors
• warnings
• retries
• skipped
• duration_ms
• exit_code

Consumer Guidance

• Parse JSON lines incrementally.
• Key off event, phase, and status instead of parsing message.
• Treat message as human-readable context, not as a stable machine contract.
• Ignore unknown fields.
• Preserve run_id, seq, and parent_seq when forwarding events downstream.