Reference

Metadata

Source Metadata.cs

Every run of a ServiceTrain produces a metadata row (trax.metadata): when it started and ended, what it carried, where it ran, and whether it completed, failed or was cancelled.

FieldTypeDescription
IdlongAuto-generated primary key
NamestringTrain name (canonical interface FullName)
ExternalIdstringGUID for external references
Executorstring?Assembly that ran the train
TrainStateTrainStatePending / InProgress / Completed / Failed / Cancelled
StartTimeDateTimeWhen the train started
EndTimeDateTime?When the train finished
Inputstring?Serialized input (jsonb)
Outputstring?Serialized output (jsonb)
FailureJunctionstring?Which junction failed
FailureExceptionstring?Exception type
FailureReasonstring?Error message
StackTracestring?Stack trace if failed
FailureClassFailureClassUnclassified / Transient / Conflict / Permanent, from the registered failure classifier. Unclassified when the run did not fail or nothing classified it
ParentIdlong?The parent run's metadata id. Nothing in Trax sets it at present, so it is null for every run, including a train dispatched from a junction; see Nested Trains
IsChildboolTrue when ParentId has a value. Computed, not stored
ManifestIdlong?Links to manifest for scheduled trains
ReplayDecisionsOflong?The run whose recorded decisions this run replays, following that run's own link back for questions it never reached. Set by a re-queue, and by a manifest's retry or dead-letter requeue when the scheduler's checks allow it (Retries replay decisions); null for a run that asks its deciders afresh. Not a foreign key: a run whose chain names a run that no longer exists, belongs to another train, or ran without recording its decisions fails before its first junction, Permanent, rather than asking afresh, unless it is a manifest's run, which asks afresh and is marked ReplayAbandoned
DecisionsRecordedboolTrue when the run started on a host that records decisions (AddDecisionRecording), set on its first write, so a replay can tell a run that reached no questions from one whose decisions were never recorded
ReplayAbandonedboolTrue when the run named a run to replay in ReplayDecisionsOf and asked its deciders afresh instead, because the replay could not be honoured (the host does not record decisions, or the chain is broken). Only a manifest's run does that; any other run fails. ReplayDecisionsOf is kept as the record of what the run was queued to do, and a later replay of this run stops here: it replays this run's own answers, or fails, as for a run that did not record its decisions, when there are none
ResumeFromlong?The run this run resumed from a checkpoint of, copied from its work queue entry; null for a run that started from the top. Not a foreign key: the run checks it before trusting any checkpoint, and the metadata cleanup keeps a run while something resumes it
ResumeAtstring?The node id the resumed run skipped to, or null for after the latest checkpoint of ResumeFrom
InvokingMachinestring?The state machine whose invoking state queued this run; null for every other run. Such a run cannot be requeued
InvokingInstanceIdGuid?The instance of InvokingMachine that queued it
InvokingOwnerKindSnapshotOwnerKind?Whether a user or the system owns that instance
ScheduledTimeDateTime?Scheduled execution time
CancellationRequestedboolCross-server cancellation flag
JunctionStartedAtDateTime?Current junction start timestamp (requires AddJunctionProgress)
CurrentlyRunningJunctionstring?Name of the currently running junction (requires AddJunctionProgress)
HostNamestring?Machine hostname where the train ran
HostEnvironmentstring?Environment type (lambda, ecs, kubernetes, server)
HostInstanceIdstring?Instance identifier (pod name, Lambda stream, etc.)
HostLabelsstring?User-provided labels as JSON (region, service, team)

The TrainState tracks the lifecycle: Pending -> InProgress -> Completed, Failed, or Cancelled. If a train fails, the metadata record captures the exception, stack trace, and which junction it happened at.

Infrastructure members

MemberDescription
SetInputObject(value), SetOutputObject(value)Hold the run's deserialized input and output in memory. Not stored; methods rather than properties, so log serializers skip them
AssemblyExtensions.GetAssemblyProject(assembly)The assembly's simple name. Executor is the entry assembly's

Failure Fields

When a junction throws, Trax captures structured context without modifying the original exception. The junction name, exception type, original message, and stack trace from the throw site are attached to the exception via Exception.Data["TrainExceptionData"]. When the train finishes, Metadata.AddException() reads this structured data and populates:

FieldSourceExample
FailureJunctionJunction class name where the throw occurred"ValidateInputJunction"
FailureExceptionException type short name"InvalidOperationException"
FailureReasonOriginal exception message (unmodified)"Input 'email' was null"
StackTraceStack trace from the original throw sitePoints to the junction's Run method
FailureClassThe registered IFailureClassifier's answer, set before the failure is recorded. Cancelled runs are not classified; a cancellation nothing asked for, such as an HttpClient timeout, is a failure and records Transient when the classifier has no answerConflict

FailureClass is also read back from a failure that already carries one: from TrainExceptionData, attached to the exception, which is how a remote failure arrives, or from the message of an exception whose type is exactly TrainException. Another exception type's message, a type derived from TrainException included, is never read as a record, even when it is JSON: a failure raised outside any junction with such a message is recorded with its own type, message and stack trace, and no class. A carried value outside the FailureClass vocabulary is recorded as Unclassified, so the row stays writable on Postgres and readable on SQLite.

The original exception is rethrown to callers with its type, message, and stack trace intact. TrainExceptionData rides along in Exception.Data for any code that wants structured context (e.g., logging, monitoring). Its TrainName is the train's canonical name, the interface FullName its metadata row's Name holds, whether the failure happened inside a junction or outside any; for a plain Core Train run without Trax.Effect it is the class name.

Host Tracking

HostName, HostEnvironment, HostInstanceId and HostLabels are detected at startup and stamped on each run. Host tracking covers detection, labels and the builder calls.

Nested Trains

A train dispatched from a junction gets a row of its own, not linked to the parent's: ParentId is not set. Nested trains covers dispatching one.

Execution Flow

Effect architecture has a diagram of a run, from the request through the row's creation to SaveChanges.