Concepts
Expressions
The ExprStr grammar for dynamic values in scenarios and jobs.
Tracemill uses a lightweight expression language called ExprStr for dynamic value generation in scenario state, emit fields, and job bindings.
| Syntax | Meaning | Example |
|---|
literal | String, number, bool, null, or nested object/array | "us-east-1", 443, true |
gen.<type>() | Built-in generator | gen.uuid(), gen.ipv4() |
gen.<type>(k=v, ...) | Generator with parameters | gen.int(min=0, max=100) |
ref.<var> | Read a resolved state variable | ref.source_ip |
ref.<var>.<path> | Dot-path into an object variable | ref.user.name |
pool.<id> | Draw a full record from a pool | pool.iam-users |
pool.<id>.<field> | Draw a record, extract a field | pool.iam-users.email |
- State variables are resolved once per run in topological order
- Circular references are detected at compile time
- All
ref.* targets must be declared in the same state block — undefined references are a compile-time error
pool.* expressions are only valid in job bindings, not in scenario state or fields
Generators produce realistic random values on each run. Parameters are optional unless noted; (d) marks the default.
| Generator | Description | Example output |
|---|
gen.uuid() | Random UUID v4 | f47ac10b-58cc-4372-a567-0e02b2c3d479 |
| Generator | Description | Example output |
|---|
gen.ipv4() | Random IPv4 address | 192.168.1.42 |
gen.ipv6() | Random IPv6 address | 2001:db8::1 |
gen.mac() | Random MAC address | 00:1a:2b:3c:4d:5e |
gen.port() | Random port (1024–65535) | 8443 |
gen.domain() | Random domain name | example.org |
gen.url() | Random URL | https://example.com/path |
gen.hostname() | Random hostname (see Hostname classes) | DESKTOP-A1B2C3D |
| Generator | Description |
|---|
gen.timestamp() | Current time in RFC3339 (default) |
gen.timestamp(format=...) | Named format: iso8601, RFC3339Nano, unix, millis, micros, nanos, epoch_float, RFC1123, ANSIC, wineventlog, sysmon, syslog, apache, kitchen, or a custom Go layout string |
| Generator | Description |
|---|
gen.username() | Random username |
gen.email() | Random email address |
gen.user_agent() | Random HTTP User-Agent string |
gen.country() | Random country name |
gen.timezone() | Random IANA timezone |
| Generator | Description |
|---|
gen.int() | Random integer 0–1,000,000 |
gen.int(min=N, max=N) | Random integer in custom range |
gen.float() | Random float 0.0–1.0 |
gen.float(min=N, max=N) | Random float in custom range |
| Generator | Description |
|---|
gen.http_method() | Random HTTP method |
gen.http_status() | Random HTTP status code |
gen.http_status(class=2xx|4xx|5xx) | Status code from a specific class |
| Generator | Description |
|---|
gen.aws_region() | Random AWS region (e.g. us-east-1) |
gen.aws_account_id() | Random 12-digit AWS account ID |
gen.aws_arn(class=...) | Random AWS ARN. Classes: user(d), role, assumed-role, lambda, instance, bucket, log-group, ecs-task. Optional name=<str> to pin the resource name. |
gen.aws_identity(type=...) | CloudTrail userIdentity map. Types: IAMUser(d), AssumedRole, AWSService, FederatedUser, Root, AWSAccount. Optional accountId, userName. |
gen.aws_access_key(...) | AWS access key object. Params: userName, accountId, status=Active(d)|Inactive, type=Permanent(d)|Temporary. |
gen.hostname() generates realistic hostnames for different platform styles via the class parameter.
| Class | Example | Params |
|---|
windows-workstation (default) | DESKTOP-A1B2C3D | domain — append domain for FQDN (e.g. domain=corp.local → DESKTOP-A1B2C3D.corp.local) |
windows-server | DC01, SQL14 | domain — append domain for FQDN |
ec2-private | ip-10-0-1-42.ec2.internal | region — AWS region (default: us-east-1). Uses ip-...ec2.internal for us-east-1, ip-...REGION.compute.internal for others. |
ec2-resource | i-0a3f7c9e12b456d89.ec2.internal | region — AWS region (default: us-east-1). Uses instance-ID-based naming. |
ec2-public-ipv4 | ec2-54-201-100-1.compute-1.amazonaws.com | region — AWS region (default: us-east-1). Uses compute-1 for us-east-1, REGION.compute for others. |
linux | web-prod-us-east-07 | — |
state:
# Windows workstation FQDN
computer: gen.hostname(class=windows-workstation, domain=corp.local)
# EC2 private DNS in us-west-2
ec2_host: gen.hostname(class=ec2-private, region=us-west-2)
# Linux infrastructure hostname
server: gen.hostname(class=linux)