Event Schema Reference
This schema applies to MTE Relay v5 (MRS and MAR). It is the contract every monitoring integration on this site builds against.
MTE Relay emits all logs as one JSON object per line on stderr (zerolog). No custom parsing rules are needed in Datadog, New Relic, Loki, CloudWatch Logs Insights, Splunk, or Elastic.
Configuration
| Env var | Default | Effect |
|---|---|---|
LOG_LEVEL | info | Filters all output including events. Security/error events emit at warn/error and survive LOG_LEVEL=warn. |
USE_CONSOLE_LOGS | false | Pretty console output for local dev. Never enable where an aggregator ingests logs. |
PERF_EVENT_SAMPLE_PERCENT | 100 | Percentage of per-request performance events emitted (0–100). Security, error, and encryption events are never sampled. |
Envelope fields (every line)
| Field | Description |
|---|---|
time | RFC3339 timestamp |
level | trace debug info warn error fatal panic |
message | Human-readable summary |
service | Always mte-relay |
product | mrs (client→server) or mar (server→server gateway) |
relay_version | e.g. 5.0.0 |
instance | Hostname of the emitting container |
correlation_id | Present on request-scoped lines |
Structured events add exactly one nested object under one of these keys: encryption_event, security_event, performance_event, error_event. The same correlation_id appears on every line and event a single request produces.
performance_event
Two event types, both subject to PERF_EVENT_SAMPLE_PERCENT:
request_timing— every request (including pass-through and errors):total_time_ms,status_code,request_path,request_method.phase_breakdown— every relayed request: addsdecryption_ms,validation_ms,proxy_ms,encryption_ms,encrypted_data_bytes,decrypted_data_bytes,client_id,pair_id.
security_event
Fields: event_type, severity (low/medium/high/critical), origin (client IP), reason, client_id, pair_id, success. Severity maps to log level: low → info, medium → warn, high/critical → error.
event_type | Severity | Meaning |
|---|---|---|
auth_invalid_token | low | Invalid client ID signature during auth; new ID generated |
keepalive_invalid_client_id | medium | Invalid client ID signature on keepalive |
pair_invalid_client_id | high | Invalid client ID signature during pairing |
invalid_client_id | medium | Client ID signature validation failed on a relay request |
client_pairs_exhausted | low | No pairs for client; full re-pair required (capacity signal) |
pair_not_found | medium | Pair state missing — expired or never created (possible replay) |
state_restore_failed | high | Encoder/decoder state restore failed — potential corruption |
state_not_found | high | State missing from the state store |
state_save_failed | high | Failed to persist state (Redis health signal) |
encryption_event
Audit trail of MTE operations. Plaintext is never logged — only SHA-256 hashes.
event_type: decryption,direction: inbound_request— after request decodeevent_type: encryption,direction: outbound_response— after response encode
Fields: correlation_id, eeid (unique event ID), url_payload_hash (SHA-256), url_payload_length, decryption_time_ms / encryption_time_ms, mte_type (MKE/MTE), data_size_bytes, client_id, pair_id, origin, upstream_host, success. Streaming payloads are not audit-hashed (no full body is ever buffered).
error_event
Fields: event_type, severity, message, reason, error_code, stack_trace. Current catalog: panic (critical) — a recovered handler panic with full stack trace.
Operational lines worth dashboarding
"Request completed"— per-request:method,path,status_code,duration_ms,correlation_id."Perf stats."— interval-aggregated stage histograms, only whenENABLE_PERF_STATS=true.