nibrunnerreported.json
Every field of the document a host writes back, from its JSON Schema.
What the host is running, written to reported.json in paths.state_dir after every pass, and
rendered as the metrics page from the same builder. A control plane that only reads this file
learns what became of its last write, and why.
Schema: reported-state.schema.json
HostReportedState
What one host is running, as the daemon last wrote it to reported.json in its paths.state_dir.
| Name | Type | Description |
|---|---|---|
hostId | HostId | |
reportedAt | Timestamp | |
state | HostState | |
capacity | HostCapacity | What the machine has. |
allocatable | HostCapacity | What is left once every booted app is taken off. |
versions | HostVersions | |
volumes | array of ReportedVolume | |
instances | array of ReportedInstance | |
checkpoints | array of ReportedCheckpoint | |
exports | array of ReportedExport | |
message optional | StateMessage | null | Set when the last document this host was handed was refused — malformed, or not the document this host reads — and cleared when a readable one is taken up. A control plane that only reads this file learns from it that its last write did not land, and why. |
HostId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
Timestamp
an ISO 8601 instant with an offset
string, matching ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$
HostState
One of "registering", "ready", "draining", "unreachable".
HostCapacity
| Name | Type | Description |
|---|---|---|
vcpuCount | integer, at least 0 | |
memoryMib | integer, at least 0 | |
cacheBytes | integer, at least 0 |
HostVersions
| Name | Type | Description |
|---|---|---|
agent | string | |
guestImage | string | |
zerofs | string | |
firecracker | string |
ReportedVolume
| Name | Type | Description |
|---|---|---|
volumeId | VolumeId | |
appId | AppId | |
state | VolumeState | |
sizeBytes | integer, at least 0 | |
devicePath optional | string | null | |
message optional | StateMessage | null | |
storagePrefix optional | ObjectKey | null | |
usage optional | FilesystemUsage | null |
ReportedInstance
| Name | Type | Description |
|---|---|---|
appId | AppId | |
deploymentId | DeploymentId | |
state | InstanceState | |
restartCount | integer, at least 0 | Times the supervisor inside the guest has restarted the tenant since this host last booted the app afresh. A restore from a snapshot keeps the count; a cold boot starts it over. |
compute optional | ComputeUsage | null | |
convergedAt optional | Timestamp | null | When the instance first became what the document asks of it, for the deploymentId and desiredState it now carries. Absent while it is still on its way there, and for a deployment this host was not there to see arrive. |
guestIpv4 optional | Ipv4Address | null | |
hostPort optional | HostPort | null | |
lastExitCode optional | integer | null | |
lastHealthyAt optional | Timestamp | null | |
lastRestart optional | ReportedRestart | null | The last of those restarts. Absent until there has been one. |
layerDigests optional | array of Sha256Digest | The layers the running microVM was booted from, bottom first. Empty until one has been. |
message optional | StateMessage | null | |
meters optional | UsageMeters | |
startedAt optional | Timestamp | null |
ReportedCheckpoint
| Name | Type | Description |
|---|---|---|
checkpointId | CheckpointId | |
volumeId | VolumeId | |
state | CheckpointState | |
message optional | StateMessage | null | |
readyAt optional | Timestamp | null | |
reference optional | StateMessage | null |
ReportedExport
| Name | Type | Description |
|---|---|---|
exportId | ExportId | |
state | ExportState | |
checkpointId optional | CheckpointId | null | |
message optional | StateMessage | null | |
readyAt optional | Timestamp | null | |
sizeBytes optional | integer, at least 0 | null |
StateMessage
string, at most 512 characters
VolumeId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
AppId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
VolumeState
One of "pending", "ready", "detached", "deleted", "failed".
ObjectKey
between 1 and 1024 characters
string, 1 to 1024 characters
FilesystemUsage
| Name | Type | Description |
|---|---|---|
totalBytes | integer, at least 0 | |
usedBytes | integer, at least 0 | |
measuredAt | Timestamp |
DeploymentId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
InstanceState
One of "pending", "starting", "running", "unhealthy", "stopping", "stopped", "idle", "failed".
ComputeUsage
| Name | Type | Description |
|---|---|---|
memoryTotalBytes | integer, at least 0 | |
memoryUsedBytes | integer, at least 0 | |
measuredAt | Timestamp | |
cpuShare optional | number | null |
Ipv4Address
an IPv4 address
string, matching ^((25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9][0-9]|[0-9])$
HostPort
integer, 1 to 65535
ReportedRestart
A tenant restart as the host heard of it: what the guest said, and when it said it.
| Name | Type | Description |
|---|---|---|
at | Timestamp | |
attempt | integer, at least 0 | 1 for the first restart since the tenant last stayed up long enough to earn its budget back, up to budget. |
budget | integer, at least 0 | |
exit | TenantExit | |
reason | StateMessage | |
backoffMs | integer, at least 0 |
Sha256Digest
a lowercase hex sha-256
string, matching ^[0-9a-f]{64}$
UsageMeters
What an app has used since this host first saw it. Every field only ever grows, so what it cost over any stretch is the difference between two readings of it, and a reading that was missed costs nothing but resolution. A field that went down is a counter this host restarted.
Time is metered in two, because a running app holds the memory it was promised and an idle one holds only the disk its snapshot sits on. Which of those is worth what, this does not say.
| Name | Type | Description |
|---|---|---|
runningMs | integer, at least 0 | |
idleMs | integer, at least 0 | |
cpuMs | integer, at least 0 | Summed across the vCPUs the app was given, so a two-vCPU app that stayed busy for a second spent two seconds of it. |
rxBytes | integer, at least 0 | What reached the guest, and what it put back on the wire. Only what was let out is counted as sent: a packet the ruleset rejected never left, so nobody is charged for it. |
txBytes | integer, at least 0 | |
diskProvisionedMibSeconds | integer, at least 0 | Disk is a level rather than a flow, so what is metered is the level multiplied by the time it was held: what was set aside for the app, and what its guest reported having filled. Mebibyte-seconds, because byte-milliseconds of a large volume outrun a u64 in months. |
diskUsedMibSeconds | integer, at least 0 |
CheckpointId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
CheckpointState
One of "pending", "ready", "deleted", "failed".
ExportId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
ExportState
One of "pending", "preparing", "ready", "failed", "expired".
TenantExit
How a tenant process ended: the code it exited with, or the signal that killed it.
One of the following:
code
| Name | Type | Description |
|---|---|---|
code | integer |
signal
| Name | Type | Description |
|---|---|---|
signal | integer |