# Tenant logs (/docs/reference/tenant-log)



Each line in `<paths.state_dir>/logs/<appId>.jsonl` is one event. All events identify the app,
deployment and source, with a sequence number and the time the host observed them. The `kind`
field identifies output, cron output, a buffering gap or a tenant restart.

[Logs and metrics](/docs/guides/logs-and-metrics) covers retention and file rotation.

Schema: [tenant-log.schema.json](https://raw.githubusercontent.com/ilbertt/nibrunner/main/crates/protocol/schema/tenant-log.schema.json)

## TenantLogEvent [#tenantlogevent]

| Name                                                                                  | Type                          | Description |
| ------------------------------------------------------------------------------------- | ----------------------------- | ----------- |
| <span id="tenantlogevent-appId" className="scroll-mt-28">`appId`</span>               | [AppId](#appid)               |             |
| <span id="tenantlogevent-deploymentId" className="scroll-mt-28">`deploymentId`</span> | [DeploymentId](#deploymentid) |             |
| <span id="tenantlogevent-sourceId" className="scroll-mt-28">`sourceId`</span>         | string                        |             |
| <span id="tenantlogevent-sequence" className="scroll-mt-28">`sequence`</span>         | integer, at least 0           |             |
| <span id="tenantlogevent-observedAt" className="scroll-mt-28">`observedAt`</span>     | [Timestamp](#timestamp)       |             |

One of the following, told apart by `kind`:

### data [#data]

| Name                                                            | Type                                | Description |
| --------------------------------------------------------------- | ----------------------------------- | ----------- |
| <span id="data-kind" className="scroll-mt-28">`kind`</span>     | `"data"`                            |             |
| <span id="data-stream" className="scroll-mt-28">`stream`</span> | [TenantLogStream](#tenantlogstream) |             |
| <span id="data-text" className="scroll-mt-28">`text`</span>     | string                              |             |

### cron-data [#cron-data]

| Name                                                                 | Type                                | Description |
| -------------------------------------------------------------------- | ----------------------------------- | ----------- |
| <span id="cron-data-kind" className="scroll-mt-28">`kind`</span>     | `"cron-data"`                       |             |
| <span id="cron-data-stream" className="scroll-mt-28">`stream`</span> | [TenantLogStream](#tenantlogstream) |             |
| <span id="cron-data-text" className="scroll-mt-28">`text`</span>     | string                              |             |
| <span id="cron-data-jobId" className="scroll-mt-28">`jobId`</span>   | string                              |             |
| <span id="cron-data-runId" className="scroll-mt-28">`runId`</span>   | string                              |             |

### gap [#gap]

| Name                                                                       | Type                | Description |
| -------------------------------------------------------------------------- | ------------------- | ----------- |
| <span id="gap-kind" className="scroll-mt-28">`kind`</span>                 | `"gap"`             |             |
| <span id="gap-droppedBytes" className="scroll-mt-28">`droppedBytes`</span> | integer, at least 0 |             |

### restart [#restart]

| Name                                                           | Type        | Description |
| -------------------------------------------------------------- | ----------- | ----------- |
| <span id="restart-kind" className="scroll-mt-28">`kind`</span> | `"restart"` |             |

[TenantRestart](#tenantrestart)

## AppId [#appid]

an identifier

string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$`

## DeploymentId [#deploymentid]

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})$`

## TenantLogStream [#tenantlogstream]

One of `"stdout"`, `"stderr"`.

## TenantRestart [#tenantrestart]

One restart of the tenant by the supervisor inside its guest, as the guest reported it. The host never sees the process, so this is the whole of what it knows about why the tenant went down and came back: which of the budget this restart was, how the tenant ended, the sentence the guest printed for it, and how long it waited before starting the tenant again.

| Name                                                                           | Type                          | Description                                                                                                  |
| ------------------------------------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| <span id="tenantrestart-attempt" className="scroll-mt-28">`attempt`</span>     | 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`. |
| <span id="tenantrestart-budget" className="scroll-mt-28">`budget`</span>       | integer, at least 0           |                                                                                                              |
| <span id="tenantrestart-exit" className="scroll-mt-28">`exit`</span>           | [TenantExit](#tenantexit)     |                                                                                                              |
| <span id="tenantrestart-reason" className="scroll-mt-28">`reason`</span>       | [StateMessage](#statemessage) |                                                                                                              |
| <span id="tenantrestart-backoffMs" className="scroll-mt-28">`backoffMs`</span> | integer, at least 0           |                                                                                                              |

## 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 |
| ----------------------------------------------------------- | ------- | ----------- |
| <span id="code-code" className="scroll-mt-28">`code`</span> | integer |             |

### signal [#signal]

| Name                                                              | Type    | Description |
| ----------------------------------------------------------------- | ------- | ----------- |
| <span id="signal-signal" className="scroll-mt-28">`signal`</span> | integer |             |

## StateMessage [#statemessage]

string, at most 512 characters
