Reference

Host Tracking

Package Trax.EffectNamespaces Trax.Effect.Configuration.TraxBuilder, Trax.Effect.Models.Host, Trax.Effect.Models.HostHeartbeatSource TraxBuilder.Host.cs, TraxHostInfo.cs, HostHeartbeat.cs

The methods on TraxBuilder that override or extend the host identity Trax stamps on every run, and TraxHostInfo, the identity they build. All are optional: without them the identity is auto-detected.

Signatures

public TraxBuilder SetHostEnvironment(string environment)
public TraxBuilder SetHostInstanceId(string instanceId)
public TraxBuilder AddHostLabel(string key, string value)
public TraxBuilder AddHostLabels(Dictionary<string, string> labels)
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();
}

Parameters

MethodParameterDescription
SetHostEnvironmentenvironmentReplaces the detected environment, such as "lambda", "ecs" or "my-custom-env"
SetHostInstanceIdinstanceIdReplaces the detected instance id
AddHostLabelkey, valueAdds one label, such as "region" = "us-east-1"
AddHostLabelslabelsAdds every pair in the dictionary

Each throws ArgumentNullException for a null argument, and returns the builder for chaining.

Members

MemberDescription
HostNameThe machine name, or unknown when it cannot be read
HostEnvironmentlambda, ecs, kubernetes, azure-app-service or server, unless SetHostEnvironment replaced it
HostInstanceIdThe Lambda log stream, the ECS or Kubernetes HOSTNAME, the Azure WEBSITE_INSTANCE_ID, or {MachineName}-{ProcessId}, unless SetHostInstanceId replaced it
LabelsThe labels added with AddHostLabel and AddHostLabels, stored as JSONB on every metadata row
CurrentThe 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.

Behavior

AddTrax builds the identity once, after its callback runs: it auto-detects, applies the overrides, and merges the labels. A label key added twice keeps the last value. Every run in the process is stamped with it when it starts, so a run executed by a remote worker carries the worker's identity, not the dispatcher's.

Heartbeat

A host with a data provider also writes that identity to trax.host_heartbeat when it starts and every 15 seconds after, whether or not it has work, so an idle host can be told from a dead one. The row is the model HostHeartbeat, read through IDataContext.HostHeartbeats:

MemberDescription
InstanceIdHostInstanceId, the primary key: one row per process
HostName, HostEnvironmentAs above
TraxVersionThe Trax version the process runs
StartedAtWhen the process began beating
LastHeartbeatAtWhen the process last wrote the row
RunsDispatcherWhether the process runs the scheduler's job dispatcher, switched on
RunsManifestManagerWhether the process runs the scheduler's manifest manager, switched on
WorkerSlotsHow many local workers the process runs, or null with none
WorkerSlotsInUseHow many of them were running a job at the last beat, or null with none

A host is offline once its last beat is 45 seconds old, three missed beats, and any host's beat deletes the rows whose last beat is a day old. operations.hosts reads the table. The migration is described in Schema migrations.

Example

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

See also