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.
| Field | Type | Description |
|---|---|---|
Id | long | Auto-generated primary key |
Name | string | Train name (canonical interface FullName) |
ExternalId | string | GUID for external references |
Executor | string? | Assembly that ran the train |
TrainState | TrainState | Pending / InProgress / Completed / Failed / Cancelled |
StartTime | DateTime | When the train started |
EndTime | DateTime? | When the train finished |
Input | string? | Serialized input (jsonb) |
Output | string? | Serialized output (jsonb) |
FailureJunction | string? | Which junction failed |
FailureException | string? | Exception type |
FailureReason | string? | Error message |
StackTrace | string? | Stack trace if failed |
FailureClass | FailureClass | Unclassified / Transient / Conflict / Permanent, from the registered failure classifier. Unclassified when the run did not fail or nothing classified it |
ParentId | long? | 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 |
IsChild | bool | True when ParentId has a value. Computed, not stored |
ManifestId | long? | Links to manifest for scheduled trains |
ReplayDecisionsOf | long? | 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 |
DecisionsRecorded | bool | True 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 |
ReplayAbandoned | bool | True 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 |
ResumeFrom | long? | 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 |
ResumeAt | string? | The node id the resumed run skipped to, or null for after the latest checkpoint of ResumeFrom |
InvokingMachine | string? | The state machine whose invoking state queued this run; null for every other run. Such a run cannot be requeued |
InvokingInstanceId | Guid? | The instance of InvokingMachine that queued it |
InvokingOwnerKind | SnapshotOwnerKind? | Whether a user or the system owns that instance |
ScheduledTime | DateTime? | Scheduled execution time |
CancellationRequested | bool | Cross-server cancellation flag |
JunctionStartedAt | DateTime? | Current junction start timestamp (requires AddJunctionProgress) |
CurrentlyRunningJunction | string? | Name of the currently running junction (requires AddJunctionProgress) |
HostName | string? | Machine hostname where the train ran |
HostEnvironment | string? | Environment type (lambda, ecs, kubernetes, server) |
HostInstanceId | string? | Instance identifier (pod name, Lambda stream, etc.) |
HostLabels | string? | 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
| Member | Description |
|---|---|
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:
| Field | Source | Example |
|---|---|---|
FailureJunction | Junction class name where the throw occurred | "ValidateInputJunction" |
FailureException | Exception type short name | "InvalidOperationException" |
FailureReason | Original exception message (unmodified) | "Input 'email' was null" |
StackTrace | Stack trace from the original throw site | Points to the junction's Run method |
FailureClass | The 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 answer | Conflict |
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.