# reported.json (/docs/reference/reported-state) 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](https://raw.githubusercontent.com/ilbertt/nibrunner/main/crates/protocol/schema/reported-state.schema.json) ## HostReportedState [#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](#hostid) | | | `reportedAt` | [Timestamp](#timestamp) | | | `state` | [HostState](#hoststate) | | | `capacity` | [HostCapacity](#hostcapacity) | What the machine has. | | `allocatable` | [HostCapacity](#hostcapacity) | What is left once every booted app is taken off. | | `versions` | [HostVersions](#hostversions) | | | `volumes` | array of [ReportedVolume](#reportedvolume) | | | `instances` | array of [ReportedInstance](#reportedinstance) | | | `checkpoints` | array of [ReportedCheckpoint](#reportedcheckpoint) | | | `exports` | array of [ReportedExport](#reportedexport) | | | `message` *optional* | [StateMessage](#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 [#hostid] an identifier string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$` ## Timestamp [#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 [#hoststate] One of `"registering"`, `"ready"`, `"draining"`, `"unreachable"`. ## HostCapacity [#hostcapacity] | Name | Type | Description | | ------------ | ------------------- | ----------- | | `vcpuCount` | integer, at least 0 | | | `memoryMib` | integer, at least 0 | | | `cacheBytes` | integer, at least 0 | | ## HostVersions [#hostversions] | Name | Type | Description | | ------------- | ------ | ----------- | | `agent` | string | | | `guestImage` | string | | | `zerofs` | string | | | `firecracker` | string | | ## ReportedVolume [#reportedvolume] | Name | Type | Description | | -------------------------- | ------------------------------------------- | ----------- | | `volumeId` | [VolumeId](#volumeid) | | | `appId` | [AppId](#appid) | | | `state` | [VolumeState](#volumestate) | | | `sizeBytes` | integer, at least 0 | | | `devicePath` *optional* | string \| null | | | `message` *optional* | [StateMessage](#statemessage) \| null | | | `storagePrefix` *optional* | [ObjectKey](#objectkey) \| null | | | `usage` *optional* | [FilesystemUsage](#filesystemusage) \| null | | ## ReportedInstance [#reportedinstance] | Name | Type | Description | | -------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `appId` | [AppId](#appid) | | | `deploymentId` | [DeploymentId](#deploymentid) | | | `state` | [InstanceState](#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](#computeusage) \| null | | | `convergedAt` *optional* | [Timestamp](#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](#ipv4address) \| null | | | `hostPort` *optional* | [HostPort](#hostport) \| null | | | `lastExitCode` *optional* | integer \| null | | | `lastHealthyAt` *optional* | [Timestamp](#timestamp) \| null | | | `lastRestart` *optional* | [ReportedRestart](#reportedrestart) \| null | The last of those restarts. Absent until there has been one. | | `layerDigests` *optional* | array of [Sha256Digest](#sha256digest) | The layers the running microVM was booted from, bottom first. Empty until one has been. | | `message` *optional* | [StateMessage](#statemessage) \| null | | | `meters` *optional* | [UsageMeters](#usagemeters) | | | `startedAt` *optional* | [Timestamp](#timestamp) \| null | | ## ReportedCheckpoint [#reportedcheckpoint] | Name | Type | Description | | ---------------------- | ------------------------------------- | ----------- | | `checkpointId` | [CheckpointId](#checkpointid) | | | `volumeId` | [VolumeId](#volumeid) | | | `state` | [CheckpointState](#checkpointstate) | | | `message` *optional* | [StateMessage](#statemessage) \| null | | | `readyAt` *optional* | [Timestamp](#timestamp) \| null | | | `reference` *optional* | [StateMessage](#statemessage) \| null | | ## ReportedExport [#reportedexport] | Name | Type | Description | | ------------------------- | ------------------------------------- | ----------- | | `exportId` | [ExportId](#exportid) | | | `state` | [ExportState](#exportstate) | | | `checkpointId` *optional* | [CheckpointId](#checkpointid) \| null | | | `message` *optional* | [StateMessage](#statemessage) \| null | | | `readyAt` *optional* | [Timestamp](#timestamp) \| null | | | `sizeBytes` *optional* | integer, at least 0 \| null | | ## StateMessage [#statemessage] string, at most 512 characters ## VolumeId [#volumeid] an identifier string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$` ## AppId [#appid] an identifier string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$` ## VolumeState [#volumestate] One of `"pending"`, `"ready"`, `"detached"`, `"deleted"`, `"failed"`. ## ObjectKey [#objectkey] between 1 and 1024 characters string, 1 to 1024 characters ## FilesystemUsage [#filesystemusage] | Name | Type | Description | | ------------ | ----------------------- | ----------- | | `totalBytes` | integer, at least 0 | | | `usedBytes` | integer, at least 0 | | | `measuredAt` | [Timestamp](#timestamp) | | ## DeploymentId [#deploymentid] an identifier string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$` ## InstanceState [#instancestate] One of `"pending"`, `"starting"`, `"running"`, `"unhealthy"`, `"stopping"`, `"stopped"`, `"idle"`, `"failed"`. ## ComputeUsage [#computeusage] | Name | Type | Description | | --------------------- | ----------------------- | ----------- | | `memoryTotalBytes` | integer, at least 0 | | | `memoryUsedBytes` | integer, at least 0 | | | `measuredAt` | [Timestamp](#timestamp) | | | `cpuShare` *optional* | number \| null | | ## Ipv4Address [#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 [#hostport] integer, 1 to 65535 ## ReportedRestart [#reportedrestart] A tenant restart as the host heard of it: what the guest said, and when it said it. | Name | Type | Description | | ----------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ | | `at` | [Timestamp](#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](#tenantexit) | | | `reason` | [StateMessage](#statemessage) | | | `backoffMs` | integer, at least 0 | | ## Sha256Digest [#sha256digest] a lowercase hex sha-256 string, matching `^[0-9a-f]{64}$` ## UsageMeters [#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 [#checkpointid] an identifier string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$` ## CheckpointState [#checkpointstate] One of `"pending"`, `"ready"`, `"deleted"`, `"failed"`. ## ExportId [#exportid] an identifier string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$` ## ExportState [#exportstate] One of `"pending"`, `"preparing"`, `"ready"`, `"failed"`, `"expired"`. ## TenantExit [#tenantexit] How a tenant process ended: the code it exited with, or the signal that killed it. One of the following: ### code [#code] | Name | Type | Description | | ------ | ------- | ----------- | | `code` | integer | | ### signal [#signal] | Name | Type | Description | | -------- | ------- | ----------- | | `signal` | integer | |