Reference

Host tracking

Source TraxHostInfo.cs, TraxBuilder.Host.cs

Every metadata row records the host the run executed on: its machine name, the kind of environment, an instance id and any labels the host adds. Hosts that share one database can be told apart by these columns.

Behavior

At startup, AddTrax() detects the host environment and stores it process-wide (TraxHostInfo.Current). A run stamps that identity on its row when it moves to InProgress.

A row the dispatcher created before a remote worker ran it is stamped again when the worker starts the run, so the row names the host that executed it.

Auto-Detection

Trax probes environment variables to determine where it's running:

EnvironmentDetectionHostEnvironmentHostInstanceId
AWS LambdaAWS_LAMBDA_FUNCTION_NAME"lambda"AWS_LAMBDA_LOG_STREAM_NAME
AWS ECSECS_CONTAINER_METADATA_URI_V4 or ECS_CONTAINER_METADATA_URI"ecs"HOSTNAME (container ID)
KubernetesKUBERNETES_SERVICE_HOST"kubernetes"HOSTNAME (pod name)
Azure App ServiceWEBSITE_SITE_NAME"azure-app-service"WEBSITE_INSTANCE_ID
Default(none of the above)"server"{MachineName}-{PID}

The variables are checked in the table's order, and the first one set wins. An instance id variable that is not set falls back to {MachineName}-{PID}. HostName is Environment.MachineName, or unknown when it cannot be read.

Builder API

Host tracking needs no configuration. These calls on the AddTrax builder override the detected values or add labels:

using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Mediator.Extensions;
 
services.AddTrax(trax => trax
    .SetHostEnvironment("my-custom-env")          // Override auto-detected environment
    .SetHostInstanceId("worker-42")                // Override auto-detected instance ID
    .AddHostLabel("region", "us-east-1")           // Add a custom label
    .AddHostLabel("service", "content-shield")     // Add another label
    .AddHostLabels(new Dictionary<string, string>  // Add multiple labels at once
    {
        ["team"] = "platform",
        ["version"] = "2.1.0",
    })
    .AddEffects(effects => effects
        .UsePostgres(connectionString)
    )
    .AddMediator(assemblies)
);

Labels are stored as JSON in the host_labels column, or null when the host adds none.

Database Columns

All columns are nullable and added to trax.metadata:

ColumnTypeDescription
host_namevarcharMachine hostname
host_environmentvarcharEnvironment type
host_instance_idvarcharInstance-level identifier
host_labelsjsonbUser-provided key-value labels

Postgres indexes host_name and host_environment, and host_labels with a GIN index over the rows that have labels, for containment queries.

Querying

-- Find all trains that ran on Lambda
SELECT name, host_name, host_instance_id, train_state
FROM trax.metadata
WHERE host_environment = 'lambda'
ORDER BY id DESC LIMIT 20;
 
-- Find trains that ran in a specific region
SELECT name, host_environment, host_instance_id
FROM trax.metadata
WHERE host_labels @> '{"region": "us-east-1"}'
ORDER BY id DESC;
 
-- Group failures by host to find a bad instance
SELECT host_instance_id, COUNT(*) as failures
FROM trax.metadata
WHERE train_state = 'failed'
  AND start_time > NOW() - INTERVAL '1 hour'
GROUP BY host_instance_id
ORDER BY failures DESC;

GraphQL

  • The executions and executionDetail queries under operations return hostName, hostEnvironment and hostInstanceId.
  • hosts lists the hosts that have run trains.
  • The lifecycle subscriptions (onTrainStarted, onTrainCompleted and the rest) carry hostName and hostEnvironment.

Dashboard

The metadata detail page shows an "Execution Host" card with the hostname, environment, instance id and labels. The metadata list has Host Env and Host columns, hidden until picked in the column picker.

SDK Reference

Host Tracking | AddTrax / AddEffects | UsePostgres | AddMediator