Metadata
Every train execution produces a metadata record. It captures everything about the run: when it started, what junctions it passed through, what it was carrying, and whether it completed or failed.
| 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 |
ParentId | long? | Links to parent metadata for nested trains |
ManifestId | long? | Links to manifest for scheduled trains |
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.
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 |
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).
Host Tracking
In distributed environments (Lambda, ECS, multiple servers), every metadata record captures where the train actually executed. Host information is auto-detected at startup and stamped on each execution. See Host Tracking for details on auto-detection, custom labels, and the builder API.
Nested Trains
A junction can dispatch another train mid-execution by injecting ITrainBus. Pass the current Metadata to the child train to link the executions. This creates a tree of metadata records you can query to trace execution across an entire network of trains.
See Mediator: Nested Trains for implementation details.
Execution Flow
For a diagram of the full ServiceTrain lifecycle, from client request through metadata initialization to SaveChanges, see Effect Architecture.