Skip to content
tracestax
TraceStax Docs

Event schema

This page provides a complete reference for all three TraceStax event types: task_event, heartbeat, and snapshot. For a conceptual overview of what each event type is used for, see Event model.

Events are delivered to the Ingest API individually — one event per request.

TaskEvent

Section titled “TaskEvent”

A task_event is emitted for each notable state transition in a job’s lifecycle.

interface TaskEvent {
  type: "task_event";
  framework: string;
  language: string;
  sdk_version: string;
  worker: WorkerInfo;
  task: TaskInfo;
  status: TaskStatus;
  metrics?: TaskMetrics;
  error?: TaskError;
  logs?: LogEntry[];
}


interface WorkerInfo {
  key: string;
  hostname: string;
  pid: number | string;
  concurrency?: number;
  queues: string[];  // max 100
}


interface TaskInfo {
  name: string;
  id: string;
  queue: string;
  attempt: number;
  parent_id?: string;
  chain_id?: string;
}


type TaskStatus =
  | "started"
  | "succeeded"
  | "failed"
  | "retried"
  | "stalled"
  | "timeout";


interface TaskMetrics {
  duration_ms?: number;
  queued_ms?: number;
}


interface TaskError {
  type: string;
  message: string;
  stack_trace?: string;
}


interface LogEntry {
  level: "info" | "warn" | "error";
  message: string;
  ts?: string;  // ISO 8601
}

Field reference

Section titled “Field reference”
FieldTypeRequiredDescription
type"task_event"YesMust be the literal string task_event
frameworkstringYesJob framework name
languagestringYesRuntime language
sdk_versionstringYesTraceStax SDK version (semver)
worker.keystringYesStable worker process identifier
worker.hostnamestringYesMachine hostname
worker.pidinteger or stringYesOS process ID. Accepts a positive integer or a non-empty string (some runtimes report PID as a string)
worker.concurrencyintegerNoMax simultaneous jobs. Minimum 0
worker.queuesstring[]YesQueues this worker consumes (max 100 entries)
task.namestringYesFully-qualified job name or class
task.idstringYesUnique job execution ID
task.queuestringYesQueue the job was dispatched to
task.attemptintegerYesAttempt number (0-indexed)
task.parent_idstringNoParent job ID, if spawned by another job
task.chain_idstringNoWorkflow chain identifier
statusstringYesstarted succeeded failed retried stalled timeout
metricsobjectNoTiming metrics for the task execution
metrics.duration_msnumberNoExecution time in milliseconds
metrics.queued_msnumberNoTime spent waiting in queue in milliseconds
error.typestringNo*Exception class name. Required when status is failed or retried
error.messagestringNo*Exception message. Required when status is failed or retried
error.stack_tracestringNoFull stack trace as a string (max 16,384 characters)
logsarrayNoUp to 10 structured log entries attached to the event
logs[].levelstringYesinfo, warn, or error
logs[].messagestringYesLog message (max 500 characters)
logs[].tsstringNoISO 8601 timestamp of the log entry

HeartbeatPayload

Section titled “HeartbeatPayload”

A heartbeat is sent by a running worker to confirm it is alive.

interface HeartbeatPayload {
  framework: string;
  worker: WorkerInfo;  // same as TaskEvent
  timestamp: string;   // ISO 8601
  language?: string;
  sdk_version?: string;
}

Field reference

Section titled “Field reference”
FieldTypeRequiredDescription
frameworkstringYesJob framework name
worker.keystringYesStable worker process identifier
worker.hostnamestringYesMachine hostname
worker.pidinteger or stringYesOS process ID
worker.concurrencyintegerNoMax simultaneous jobs. Minimum 0
worker.queuesstring[]YesQueues this worker consumes (max 100 entries)
timestampstringYesISO 8601 datetime of when the heartbeat was generated
languagestringNoRuntime language
sdk_versionstringNoTraceStax SDK version

SnapshotPayload

Section titled “SnapshotPayload”

A snapshot reports queue statistics at a point in time.

interface SnapshotPayload {
  type: "snapshot";
  framework: string;
  worker_key: string;
  queues: QueueSnapshot[];
  timestamp: string;  // ISO 8601
}


interface QueueSnapshot {
  name: string;
  depth: number;
  active: number;
  failed: number;
  throughput_per_min: number;
}

Field reference

Section titled “Field reference”
FieldTypeRequiredDescription
type"snapshot"YesMust be the literal string snapshot
frameworkstringYesJob framework name
worker_keystringYesThe worker key of the process that collected these statistics
queuesarrayYesOne entry per monitored queue (max 200 entries)
queues[].namestringYesQueue name
queues[].depthintegerYesJobs waiting to be processed
queues[].activeintegerYesJobs currently being processed
queues[].failedintegerYesJobs in the failed / dead-letter state
queues[].throughput_per_minnumberYesCompleted jobs per minute over the last measurement window
timestampstringYesISO 8601 datetime of when the snapshot was taken

Size limits

Section titled “Size limits”
LimitValue
Maximum request body size256 KB
Maximum worker.queues entries100
Maximum logs entries per event10
Maximum snapshot queues entries200