Host Tracking

When trains run across distributed infrastructure (Lambda functions, ECS tasks, Kubernetes pods, multiple servers), every metadata record captures WHERE the train executed. Since all hosts share the same Postgres database, you can query exactly which machine ran any given train.

How It Works

At startup, AddTrax() auto-detects the host environment and stores it as a process-wide singleton (TraxHostInfo.Current). Every Metadata record is stamped with this identity when the train starts executing.

For remote workers: the metadata row is initially created by the dispatcher, but when the worker picks up the job and calls StartServiceTrain(), the host fields are overwritten with the actual execution host’s identity.

Auto-Detection

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

Environment	Detection	HostEnvironment	HostInstanceId
AWS Lambda	AWS_LAMBDA_FUNCTION_NAME	"lambda"	AWS_LAMBDA_LOG_STREAM_NAME
AWS ECS	ECS_CONTAINER_METADATA_URI_V4	"ecs"	HOSTNAME (container ID)
Kubernetes	KUBERNETES_SERVICE_HOST	"kubernetes"	HOSTNAME (pod name)
Azure App Service	WEBSITE_SITE_NAME	"azure-app-service"	WEBSITE_INSTANCE_ID
Default	(none of the above)	"server"	{MachineName}-{PID}

HostName is always Environment.MachineName.

Builder API

Host tracking works with zero configuration. To override or add labels:

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 JSONB in the host_labels column and can be queried with PostgreSQL containment operators.

Database Columns

All columns are nullable and added to trax.metadata:

Column	Type	Description
host_name	varchar	Machine hostname
host_environment	varchar	Environment type
host_instance_id	varchar	Instance-level identifier
host_labels	jsonb	User-provided key-value labels

Indexes: host_name, host_environment, and a GIN index on host_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

Host fields are available on both queries and subscriptions:

• getExecutions / getExecution: returns hostName, hostEnvironment, hostInstanceId
• Lifecycle subscriptions (onTrainStarted, onTrainCompleted, etc.): include hostName, hostEnvironment

Dashboard

The metadata detail page shows an “Execution Host” card with hostname, environment, instance ID, and labels. The metadata list page includes optional (hidden by default) Host Env and Host columns that can be enabled via the column picker.

SDK Reference

Host Tracking

AddTrax / AddEffects

UsePostgres

AddMediator