Host Tracking

Methods on TraxBuilder for configuring host identity. All are optional. Host tracking works with zero configuration via auto-detection.

SetHostEnvironment

Overrides the auto-detected host environment type.

public TraxBuilder SetHostEnvironment(string environment)

Parameter	Type	Required	Description
`environment`	`string`	Yes	Environment identifier (e.g., `"lambda"`, `"ecs"`, `"my-custom-env"`)

SetHostInstanceId

Overrides the auto-detected host instance ID.

public TraxBuilder SetHostInstanceId(string instanceId)

Parameter	Type	Required	Description
`instanceId`	`string`	Yes	Instance identifier

AddHostLabel

Adds a custom key-value label to the host identity. Labels are stored as JSONB on every metadata record.

public TraxBuilder AddHostLabel(string key, string value)

Parameter	Type	Required	Description
`key`	`string`	Yes	Label key (e.g., `"region"`, `"service"`)
`value`	`string`	Yes	Label value (e.g., `"us-east-1"`)

AddHostLabels

Adds multiple custom labels at once.

public TraxBuilder AddHostLabels(Dictionary<string, string> labels)

Parameter	Type	Required	Description
`labels`	`Dictionary<string, string>`	Yes	Key-value pairs to add

Example

services.AddTrax(trax => trax
    .SetHostEnvironment("ecs")
    .AddHostLabel("region", "us-east-1")
    .AddHostLabel("service", "content-shield")
    .AddEffects(effects => effects
        .UsePostgres(connectionString)
    )
    .AddMediator(assemblies)
);

TraxHostInfo

The identity these methods build, readable from code.

namespace Trax.Effect.Models.Host;
 
public record TraxHostInfo
{
    public string HostName { get; init; }
    public string HostEnvironment { get; init; }
    public string HostInstanceId { get; init; }
    public Dictionary<string, string> Labels { get; init; }
 
    public static TraxHostInfo? Current { get; }
    public static TraxHostInfo AutoDetect();
}

Member	Description
`HostName`	The machine name, or `unknown` when it cannot be read
`HostEnvironment`	`lambda`, `ecs`, `kubernetes`, `azure-app-service` or `server`, unless `SetHostEnvironment` overrode it
`HostInstanceId`	The Lambda log stream, the ECS or Kubernetes `HOSTNAME`, the Azure `WEBSITE_INSTANCE_ID`, or `{MachineName}-{ProcessId}`, unless `SetHostInstanceId` overrode it
`Labels`	The labels added with `AddHostLabel` and `AddHostLabels`
`Current`	The identity `AddTrax` built, or `null` before `AddTrax` runs. Process-wide: a second `AddTrax` in the same process (two test hosts, say) replaces it.
`AutoDetect()`	Probes the environment and returns a new identity with no labels. It does not change `Current`.

Remarks

Host identity is detected once at startup and applied to all train executions in the process.
Auto-detection probes environment variables for Lambda, ECS, Kubernetes, and Azure App Service. See Host Tracking for the full detection table.
Duplicate label keys use last-write-wins semantics.
When a remote worker executes a train, host fields are overwritten when the run starts, so the metadata reflects the actual execution host, not the dispatcher.