read_logs #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/read_logs, with a bearer credential and the action's payload as the JSON body. It also accepts GET. An MCP connection lists this action as the tool tzcloud_read_logs.
OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts (Sign-in, sessions, and tokens).
Build metadata: Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.
Contract description #
Read your application's logs for one environment.
container is stdout/stderr, app is logging-package output. router keeps 5xx responses whole within its cap, and read_status lists failed paths in server_errors. all or no source merges stored sources and console by time. On an all-source read, any of level, field, filter, contains or until excludes console lines.
For container, level and field give invalid_request, and until is ignored. It returns lines, without entries. Waiting needs since. Without compute, it can return kept failed-check lines. A version in flight, or an upload in progress on a deploy target with no history, gives deploy_in_flight. Other refusals use never_deployed.
More about this action #
The store sources, app, platform, router, egress, harness, and pool, are the records the logging service stores in the environment's stream. Every store source, app, platform, router, egress, harness, pool, and the whole stream, returns lines and adds entries, the same records parsed, each with its at, level, source, message, and any fields. The platform source contains the platform's entries about the application, including each scheduled run's outcome.
The router source contains the serving router's records. Each minute it writes one legs_ended record for each invocation kind and outcome, with the count and the duration's sum and maximum. It keeps whole each window_ended request, one that ran past the router's deadline, and each upstream_ended request, one that the end of the application's process cut off. It writes one source_refused record for each minute in which the per-source bound refused requests, with the bound, the count refused, and the number of distinct sources refused. It writes one sockets_ended record per minute for each reason WebSocket connections ended. That record has the router's close code, null where one side closed, the count, and the duration's sum and maximum in milliseconds.
A legs_ended record with the outcome answered also has its status_class, 2xx to 5xx, so a 500 is never counted with a 200. Each 5xx response is also kept whole, as an answered_5xx record with the request_id, the method, the path without its query, the status, the duration, and the serving version. A 504 for a request whose process had not started listening in time is kept as a start_timed_out record instead. At most twenty of these are kept per application and environment each minute, and the rest are counted only in the legs_ended records.
To find a failed request's records, read its response's x-request-id header. Set field: "request_id", value to that header, since to the request's start, wait_seconds: 10, and omit source. This finds its 5xx router record, where kept, and the app entries your code wrote with that field. A read by field: "request_id" with no source waits a few seconds more, until the router and app sources have each answered or no new entry comes. Console lines have no structured fields. Read source: "container" from the same since; add contains with the id only where your code prints it.
The egress source contains the outbound proxy's records. Each minute it writes one egress_establishments record for each host, port, outcome, and declared flag, with the count. For an observed host the manifest does not declare, that record also has the refusal name and, where one exists, its remedy. The proxy keeps each egress_refusal whole.
The harness source contains the connection-observer records of the runtime harness, the platform's code loaded into the application's process. The application's own process sends them under its own credential, so they are not attested platform records. Each minute it writes one egress_establishments record for each host, port, and outcome, with the proxied mark and the count. It keeps each failed egress_establishment whole.
The pool source contains a serverless application's function console lines and the pool entry's records of its calls.
Records arrive with a delay. A store source's entries arrive within a few seconds, when the logging client flushes on its interval. The per-minute records under router, egress, and harness arrive once their minute has ended. An empty answer has a detail that says why. So does an answer whose window ends inside its source's lag, since its newest records may not have arrived yet.
The container source is the one console read: the process's standard output and standard error. The console.log and console.error lines land there, and so do the harness's window_ended, process_ended, and harness_refusal lines. It is the process's own console, not a stream. For an environment whose grain is pod, it is the pod's console, read through the cluster's API server. After a restart it has the previous container's lines and then the current one's, or the previous container's alone while the current one waits to start.
A pod's live console ends with the pod, at a scale to zero or a replacement. The read then returns that pod's ended-pod lines: the first and last lines each of its processes wrote, marked [pod-ended] and placed before the standing pods' lines. A process ended by a crash, an out-of-memory kill, or a SIGKILL keeps none. For an environment whose grain is container, it is the provider's console log store, where the window's process_ended and harness_refusal lines and the logging client's fallback lines land. A container line from the version being replaced has [retiring].
A container read acts on the compute of the environment you name, production where you name none. Where that environment has no compute, the read can still return the lines a failed health or smoke check kept. It returns up to 40 of them, with failed_check, where nothing is in flight and the newest version failed its health or smoke check with no earlier version serving. Otherwise it is refused deploy_in_flight while a version is in flight, or while an upload to the deploy target is in progress and the environment has no history. Every other refusal is never_deployed. Where nothing is running and the environment's latest version failed, the detail identifies that failed deploy or promote and, where recorded, gives its step and error. The failure stays in that version's outcome in read_status, including the failed health check's last console lines where the check failed.
Where the grain is container and the platform has the direct read enabled, a container read also reads each running replica's console directly, once. Where that direct read succeeds, it returns the newest lines at once.
On a container read, contains searches the newest 1,000 lines, ignoring case, and the detail says what it searched. The search runs before the limit cut, which keeps whole matches newest first and a cut match's own line. A level or field is refused invalid_request, because a console line has neither.
With wait_seconds on a store source, the platform reads the store every two seconds. It replies once a matching entry exists or this many seconds have passed since the call arrived, with waited_ms. An entry already in the window ends the wait at once, so give since to wait for entries written after a moment. Each server holds one wait per application. This call's wait takes that place. A concurrent held read_status or held act for that application on the same server returns at once. A wait that finds another call waiting also returns at once, and its empty answer's detail starts with a sentence saying it did not wait.
On a container read, wait_seconds follows the console instead, up to 40 seconds, so give since. It follows the console of each running replica, three at most, or of the newest pod. The answer comes once a line that the call's filters accept is written at or after since, or at the earlier of wait_seconds and 40 seconds. It has every line read, and waited_ms. The wait needs the direct read enabled. It cannot wait where that server already holds a wait for the application. It also cannot wait where that server's waits or follows are full, or where the management API is near its limit. The read then returns at once as an ordinary container read, and its detail says why. Where the limit is reached during the wait, the read replies with the lines read so far. A crashed process's earlier lines are read without the wait.
The filter argument: declared or undeclared reads the outbound connections whose host the manifest declares, or does not, as the manifest is at the time of the read. It reads the proxy's and the harness's per-minute establishment records, and their whole refusals and failures, within the returned page: the named source's, or every source's where you name none. The platform's own endpoints, the loopback targets, and the harness's proxied records are left out either way. Use it to see what to add to the manifest before enforcement is turned on. Where a container read passes contains, the filter runs over the lines that matched, among those searched, before the limit cut.
The since argument: left out, this bound is open, except on a container read. For an environment that runs as a container, its window then starts 24 hours before the read; for one that runs as a pod, so does its read of the ended-pod lines. A null, empty, wrongly typed, or malformed value is refused 400 invalid_request, and the detail identifies the member. A since or until timestamp's calendar date must exist. Hours are 00–23, minutes and seconds 00–59, and the offset's hours and minutes 00–23 and 00–59. Leap seconds and 24:00 are not accepted. Values are converted to UTC at millisecond precision.
The source argument: container reads the process's console, its standard output and standard error, console.log and console.error among them. app reads only what the application writes through the logging package, and platform the platform's entries about it. router, egress, harness, and pool read the records of the serving router, the outbound proxy, the runtime harness's connection observer, and the function pool. all, or no source, reads every store source and, on development or production, the console's lines as container entries, merged by time within limit. A line from standard error is at level error and any other at info; a pod's console does not mark standard error, so every line from a pod is at info. Passing level, field, filter, contains, or until leaves the console's lines out. Over MCP, any other value is refused; over the HTTP API, it reads as all does.
The wait_seconds argument: the seconds, 1 to 45, that the call waits while a read with this call's filters finds no entry. A store source is read every two seconds, and a container read follows the console, 40 seconds at most. A value outside 1 to 45 is refused invalid_request, and its detail gives the bound.
The limit argument: 100 where none is given.
Where the detail says lines may still be in the ingestion, read again about a minute later.
Access and action metadata #
{
"name": "read_logs",
"resource": "environment",
"tier": "observe",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"clients": [
"bearer",
"browser_session"
],
"summary": "The environment's log entries written through the logging service, filterable by time, level, message, field, and source. `source` selects one of the stream's sources. `app` is only what the application writes through the logging package; standard output and standard error land under `container`. `platform` is the platform's entries about it, each scheduled run's outcome among them. `router` is the serving router's `legs_ended` records per invocation kind and outcome per minute, its `window_ended` requests whole, and its `upstream_ended` requests whole, each a request an application's process end cut. It also holds its `source_refused` records, one per minute the per-source bound refused requests in. Its `sockets_ended` records are one per minute and reason WebSocket connections ended, with the close code, the count, and the durations. `egress` is the tunnel seat's `egress_establishments` records per host and outcome per minute, an observed host's refusal name and remedy on them, and its refusals whole. `harness` is the runtime harness's connection observer's `egress_establishments` records and its failed `egress_establishment` records, shipped from the application's own process. `all` is every source the logging service stores, with the container's console output merged by time unless you pass `level`, `field`, `filter`, `contains`, or `until`. `container` is the one console read, the named environment's own compute (production where none is given; a pod's live console read through the cluster's API server, after the first and last lines of the environment's ended pods, marked `[pod-ended]`). It is where the process's standard output and standard error land, `console.log` and `console.error` lines among them, beside the `process_ended` and `harness_refusal` lines and the logging client's fallback lines. `filter` is the declared-versus-observed reading: `declared` or `undeclared` against the manifest's egress member, over the aggregated records with the platform endpoints and the loopback targets subtracted. The `legs_ended` record of a leg that got a response carries its `status_class`, and each 5xx response is kept whole as an `answered_5xx` record, under a per-minute cap. A 504 refusing a request whose process had not started listening in time is kept as a `start_timed_out` record instead, under the same cap. Store entries land within a few seconds, and on the container grain a `container` line reaches the log workspace up to about a minute after it is written. On the container grain, where the platform has the direct read enabled, the read also reads each running replica's console directly, once. Where that direct read succeeds, it returns the newest lines at once. A `container` answer is ordered by each line's write time, on the pod grain pod by pod with the ended pods' lines first, and a line from the environment's recorded previous compute carries `[retiring]`. An empty answer, or one whose window ends inside that lag, carries a `detail` saying why. On the container grain, where the direct read is enabled, that `detail` also reports it. It gives the time from which lines were read from the replica directly where any were kept. It says when lines may still be in the ingestion, and gives a failed read's reason. On a `container` read, `contains` searches its newest 1,000 lines, and a `level` or `field` is refused `invalid_request`, a console line carrying neither.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": true,
"idempotentHint": true
}
}
MCP catalog entry #
{
"name": "read_logs",
"title": "Read app logs",
"tier": "observe",
"scenario": "CHI-L0-09",
"summary": "Read your application's logs for one environment.\n\n`container` is stdout/stderr, `app` is logging-package output. `router` keeps 5xx responses whole within its cap, and `read_status` lists failed paths in `server_errors`. `all` or no `source` merges stored sources and console by time. On an all-source read, any of `level`, `field`, `filter`, `contains` or `until` excludes console lines.\n\nFor `container`, `level` and `field` give `invalid_request`, and `until` is ignored. It returns `lines`, without `entries`. Waiting needs `since`. Without compute, it can return kept failed-check lines. A version in flight, or an upload in progress on a deploy target with no history, gives `deploy_in_flight`. Other refusals use `never_deployed`.",
"owners": [
"EGW-L0-17",
"EGW-L0-15",
"HST-L0-03",
"PLD-L0-40",
"SVC-L0-07",
"SVC-L0-18",
"HST-L0-01",
"PLD-L0-136",
"PLD-L0-137",
"MAN-09"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["application"] |
| / |
Your account's application id from list_applications, not its name or label.Type: string |
| / |
Default production. local is the caller computer's stream. Without compute, container can return kept failed-check lines or refuse deploy_in_flight or never_deployed; read the detail for why. container with local gives invalid_request.Type: string |
| / |
Inclusive timestamp with a time zone: YYYY-MM-DDTHH:mm[:ss[.fraction]], then Z or ±HH:mm. Fraction has 1–9 digits, T/Z ignore case. Malformed gives invalid_request. Default open, except 24 hours back for a container environment's console.Type: string |
| / |
Newest entries retained, default 100. Type: integer Minimum: 1 Maximum: 1000 |
| / |
container: stdout/stderr. app: logging-package records. egress: outbound proxy. harness: runtime harness. pool: functions. Also platform and router. all or absent merges by time. On an all-source read, any of level, field, filter, contains or until excludes console lines.Type: string Allowed values: ["app","platform","router","egress","harness","pool","container","all"] |
| / |
Connections to hosts declared or undeclared in the manifest's egress at the read. Naming source selects its page: egress reads the proxy's records, harness connections made without the proxy. With no source, the returned page may hold neither.Allowed values: ["declared","undeclared"] |
| / |
Inclusive end, with since syntax and validation. Default open.Type: string |
| / |
Minimum level: debug, info, warn or error. Other values are ignored.Type: string |
| / |
Message text. On container, case-insensitive over the newest 1000 lines, with indented continuation lines, before limit.Type: string |
| / |
Structured field matched with value. Without value, any entry with the field. For a response's x-request-id, use request_id here, its header as value, and no source. This finds stored records, not console lines.Type: string |
| / |
JSON-typed equality with field, including null. Omitted matches any entry with the field.Type: ["string","number","boolean","null"] |
| / |
Wait for an entry, with since. For container, the console is followed for at most 40 seconds. Out of range gives invalid_request.Type: integer Minimum: 1 Maximum: 45 |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","lines"] |
| / |
Required value: 1 |
| / |
The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
The answer's lines, oldest first. From a store source each line renders one entry. From container a line is <time> <stream> <text>: the time the process wrote it, then stdout or stderr on the container grain, or - on the pod grain, whose log gives no stream. On the container grain the lines are ordered by that time; on the pod grain they come pod by pod, the ended pods' lines first. A line from the compute the environment records as previous, the version being replaced, carries [retiring] after its stream; a line of the new version never does. On the container grain a line the stopped replica wrote at or after the provider's scale to zero carries [idle-stop] there instead, and a [retiring] line never carries it; the pod grain marks no idle stop. A read whose window starts after the scale to zero, or one made before the provider's record of the stop arrives, leaves those lines unmarked. On the pod grain an ended-pod line, one of the first and last lines each process of an ended pod wrote, carries [pod-ended] after its stream, or after [retiring] where it carries both. Ended-pod lines come before the standing pods' lines, read from since, or from 24 hours back where it is absent. Where the environment has no compute, no version serves, and the newest version's failed health or smoke check kept lines, container returns those lines as the check kept them, at most 40, with no line written after the check.Type: array |
| / |
Type: string |
| / |
Present only on a container answer where at least one of lines carries the [retiring] mark the platform set: how many do. Those lines are the previous version's, from the compute being replaced, so where this equals the length of lines no line returned is the serving version's. A line the application wrote that opens with [retiring] is not counted.Type: integer Minimum: 1 |
| / |
Present on an empty answer, saying why nothing was found, and on any answer whose window ends within its source's lag of the read, saying the newest records may not have arrived yet. A read of all sources that holds entries also carries it, saying after any lag that it includes the container's console output, as an empty one says; on the local stream, which has no console to read, neither says so. Where the read passes level, field, filter, contains, or until, or its console read was refused, failed, timed out, or found no compute, it says instead that console output is not included and why. Where the entries of a read of all sources or of router hold the router's answered_5xx record, the detail gives the container read and its since. That since is the earliest such record's instant less its duration and five seconds. The detail also says that the read returns the newest lines after its since, so you raise limit or add contains, and this sentence takes the place of the console sentence. On the pod grain the read is given for a record of the serving version alone, and the sentence adds that an ended pod keeps its first and last lines. Where the records there are of another version, the detail gives that version and no read; where they carry none, it says so and gives no read. On a read of all sources that sentence follows the console sentence. A container read carrying contains carries it, opening with the lines searched and matched, what the egress filter kept where given, the number returned where limit cut them, and, on the container grain, their span. It says where the cut left a match's later frames out. A container answer with lines also carries it where the environment is idle now, saying after any lag that the last lines are an idle stop and that the next request starts the application. Where the platform marked a line of the answer [retiring], the detail ends by saying that such lines are the previous version's, unless that sentence would take it past its budget. Where a container detail would pass its budget, sentences are left out, in a fixed order, until it fits. The sentence on more instances than a wait followed goes first. Then go the sentences on missing lines, on the delay before lines reach the log store, on an idle environment, and on a replica not running, stopped, or just restarted. The [retiring] sentence goes next, and the sentence on how a wait ended goes last. A pod answer says so where a line longer than the 262,144 bytes its read holds was not returned. Idle is the container app's latest revision holding no replica, or the pod's Deployment scaled to zero, and a halted environment is never idle. Under app, only what the application writes through the logging package lands there, and standard output and standard error land under container. Under container, the compute may have scaled to zero, recent lines may still be in the ingestion, contains matched none, or filter kept none. Under any other source, no entry is in the window, or none matches the read's filters. The lag is a few seconds for the store's entries, up to a minute for the per-minute records under router, egress, and harness and for a container app's console, and none for a pod's console. On the container grain, where the platform has the direct read enabled, a container read also reads each running replica's console directly, once and bounded, and its detail says how that read went. Where the direct read kept lines, the detail gives the time from which the newest lines were read from the replica directly, and says a later read may return them again with the log workspace's stamp. The detail says lines may still be in the ingestion where that read reached no replica or did not complete, giving the reason where it failed. Where it did not complete, the sentence on the delay says instead that the log workspace's lines are those it held at the read, and the reason's sentence says a later read adds lines. A reason's word longer than 29 characters is cut to 29 characters, ending with …, in the detail, and reason carries it whole. It says so too where a replica is not running, stopped, or has just restarted, or where the answer may lack lines. Where none of those holds and the direct read kept no line, the detail says the replicas' newest lines are in this answer. An empty answer then says only that the compute may have scaled to zero and written nothing. Lines still in the ingestion reach the log workspace up to about a minute after the process writes them, so a later read returns them. A container read whose wait_seconds did not hold says why, unless its budget leaves that sentence out. The causes are the place taken, the platform's waits or follows full, the management API near its limit, the direct read off, or, on the pod grain, no pod running to follow. It also says where more instances run than the three followed. A container answer from a failed health check's kept lines opens with what happened and where read_status holds the same lines. Its contains, filter, and limit sentences give counts alone and no span, since those lines carry no time.Type: string |
| / |
Present only where a container read's direct read of the replicas did not complete: the reason's one word, whole at any length, such as timed_out, throttled, http_503, or a network error code. The detail gives the same reason, cutting a word longer than 29 characters. On an answer with lines, or one the filter emptied, it also says the log workspace's lines are those it held at the read, unless its budget leaves that sentence out. A reason beside lines, timed_out among them, applies to the direct read alone; a later read adds lines. The word comes from the platform's own read of your replicas through the hosting provider, and its cause may not be known. It does not say whether your application is healthy; read_status does. A stream that responded with a 5xx status, 501 and 505 aside, was asked once more where the read's bound allowed.Type: string |
| / |
Present only on a container answer where the environment has no compute, no version serves, and the newest version's failed health or smoke check kept a record. Its lines are that record's, at most 40, and none written after the check. Its version and kind identify the failed version, ended_at its end, since the instant the check read its lines from, and truncated whether the check's bound cut them.Type: object Required fields: ["version","kind","ended_at","since","truncated"] Additional properties: false |
| / |
Type: integer |
| / |
Type: string Allowed values: ["deploy","promote","restart"] |
| / |
Type: ["string","null"] |
| / |
Type: ["string","null"] |
| / |
Type: boolean |
| / |
Type: string |
| / |
Type: array |
| / |
Type: object Required fields: ["at","level","source","message"] |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: object |
| / |
Present where the request carried wait_seconds: the time the answer was held, in milliseconds. On a store source, the answer's lines and entries come from a fresh read after the wait, whatever ended it. A container answer on a container app merges the store's lines with every line its follows read, and on a pod it carries the followed lines alone. It carries no settled.Type: integer Minimum: 0 |
| / |
Present on a container answer where the environment runs as a pod, from a read that did not follow the console. It is where the live console the read covered begins: the start of the oldest standing pod's earliest container whose log the cluster keeps. A line written before it is not in the live console; it can answer only as an ended-pod line, marked [pod-ended], where its process kept it. Null where the environment has no pod, and absent on the container grain and on an answer a wait's follow composed.Type: ["string","null"] |
| / |
$ref: #/shapes/page |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"application"
],
"properties": {
"application": {
"type": "string",
"description": "Your account's application `id` from `list_applications`, not its name or label."
},
"environment": {
"type": "string",
"description": "Default production. `local` is the caller computer's stream. Without compute, `container` can return kept failed-check lines or refuse `deploy_in_flight` or `never_deployed`; read the detail for why. `container` with local gives `invalid_request`."
},
"since": {
"type": "string",
"description": "Inclusive timestamp with a time zone: `YYYY-MM-DDTHH:mm[:ss[.fraction]]`, then `Z` or `±HH:mm`. Fraction has 1–9 digits, T/Z ignore case. Malformed gives `invalid_request`. Default open, except 24 hours back for a container environment's console."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Newest entries retained, default 100."
},
"source": {
"type": "string",
"description": "`container`: stdout/stderr. `app`: logging-package records. `egress`: outbound proxy. `harness`: runtime harness. `pool`: functions. Also `platform` and `router`. `all` or absent merges by time. On an all-source read, any of `level`, `field`, `filter`, `contains` or `until` excludes console lines.",
"enum": [
"app",
"platform",
"router",
"egress",
"harness",
"pool",
"container",
"all"
]
},
"filter": {
"description": "Connections to hosts declared or undeclared in the manifest's `egress` at the read. Naming `source` selects its page: `egress` reads the proxy's records, `harness` connections made without the proxy. With no source, the returned page may hold neither.",
"enum": [
"declared",
"undeclared"
]
},
"until": {
"type": "string",
"description": "Inclusive end, with `since` syntax and validation. Default open."
},
"level": {
"type": "string",
"description": "Minimum level: `debug`, `info`, `warn` or `error`. Other values are ignored."
},
"contains": {
"type": "string",
"description": "Message text. On `container`, case-insensitive over the newest 1000 lines, with indented continuation lines, before `limit`."
},
"field": {
"type": "string",
"description": "Structured field matched with `value`. Without `value`, any entry with the field. For a response's `x-request-id`, use `request_id` here, its header as `value`, and no `source`. This finds stored records, not console lines."
},
"value": {
"type": [
"string",
"number",
"boolean",
"null"
],
"description": "JSON-typed equality with `field`, including null. Omitted matches any entry with the field."
},
"wait_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 45,
"description": "Wait for an entry, with `since`. For `container`, the console is followed for at most 40 seconds. Out of range gives `invalid_request`."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"lines"
],
"properties": {
"contract_version": {
"const": 1
},
"reference": {
"type": "string",
"pattern": "^[0-9a-f]{10}$",
"description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
},
"lines": {
"type": "array",
"description": "The answer's lines, oldest first. From a store source each line renders one entry. From `container` a line is `<time> <stream> <text>`: the time the process wrote it, then `stdout` or `stderr` on the container grain, or `-` on the pod grain, whose log gives no stream. On the container grain the lines are ordered by that time; on the pod grain they come pod by pod, the ended pods' lines first (PLD-L0-137). A line from the compute the environment records as previous, the version being replaced, carries `[retiring]` after its stream; a line of the new version never does. On the container grain a line the stopped replica wrote at or after the provider's scale to zero carries `[idle-stop]` there instead, and a `[retiring]` line never carries it; the pod grain marks no idle stop. A read whose window starts after the scale to zero, or one made before the provider's record of the stop arrives, leaves those lines unmarked. On the pod grain an ended-pod line, one of the first and last lines each process of an ended pod wrote, carries `[pod-ended]` after its stream, or after `[retiring]` where it carries both. Ended-pod lines come before the standing pods' lines, read from `since`, or from 24 hours back where it is absent. Where the environment has no compute, no version serves, and the newest version's failed health or smoke check kept lines, `container` returns those lines as the check kept them, at most 40, with no line written after the check.",
"items": {
"type": "string"
}
},
"retiring_lines": {
"type": "integer",
"minimum": 1,
"description": "Present only on a `container` answer where at least one of `lines` carries the `[retiring]` mark the platform set: how many do. Those lines are the previous version's, from the compute being replaced, so where this equals the length of `lines` no line returned is the serving version's. A line the application wrote that opens with `[retiring]` is not counted."
},
"detail": {
"type": "string",
"description": "Present on an empty answer, saying why nothing was found, and on any answer whose window ends within its source's lag of the read, saying the newest records may not have arrived yet. A read of all sources that holds entries also carries it, saying after any lag that it includes the container's console output, as an empty one says; on the `local` stream, which has no console to read, neither says so. Where the read passes `level`, `field`, `filter`, `contains`, or `until`, or its console read was refused, failed, timed out, or found no compute, it says instead that console output is not included and why. Where the entries of a read of all sources or of `router` hold the router's `answered_5xx` record, the detail gives the `container` read and its `since`. That `since` is the earliest such record's instant less its duration and five seconds. The detail also says that the read returns the newest lines after its `since`, so you raise `limit` or add `contains`, and this sentence takes the place of the console sentence. On the pod grain the read is given for a record of the serving version alone, and the sentence adds that an ended pod keeps its first and last lines. Where the records there are of another version, the detail gives that version and no read; where they carry none, it says so and gives no read. On a read of all sources that sentence follows the console sentence. A `container` read carrying `contains` carries it, opening with the lines searched and matched, what the egress filter kept where given, the number returned where `limit` cut them, and, on the container grain, their span. It says where the cut left a match's later frames out. A `container` answer with lines also carries it where the environment is idle now, saying after any lag that the last lines are an idle stop and that the next request starts the application. Where the platform marked a line of the answer `[retiring]`, the detail ends by saying that such lines are the previous version's, unless that sentence would take it past its budget. Where a `container` detail would pass its budget, sentences are left out, in a fixed order, until it fits. The sentence on more instances than a wait followed goes first. Then go the sentences on missing lines, on the delay before lines reach the log store, on an idle environment, and on a replica not running, stopped, or just restarted. The `[retiring]` sentence goes next, and the sentence on how a wait ended goes last. A pod answer says so where a line longer than the 262,144 bytes its read holds was not returned. Idle is the container app's latest revision holding no replica, or the pod's Deployment scaled to zero, and a halted environment is never idle. Under `app`, only what the application writes through the logging package lands there, and standard output and standard error land under `container`. Under `container`, the compute may have scaled to zero, recent lines may still be in the ingestion, `contains` matched none, or `filter` kept none. Under any other source, no entry is in the window, or none matches the read's filters. The lag is a few seconds for the store's entries, up to a minute for the per-minute records under `router`, `egress`, and `harness` and for a container app's console, and none for a pod's console. On the container grain, where the platform has the direct read enabled, a `container` read also reads each running replica's console directly, once and bounded, and its detail says how that read went. Where the direct read kept lines, the detail gives the time from which the newest lines were read from the replica directly, and says a later read may return them again with the log workspace's stamp. The detail says lines may still be in the ingestion where that read reached no replica or did not complete, giving the reason where it failed. Where it did not complete, the sentence on the delay says instead that the log workspace's lines are those it held at the read, and the reason's sentence says a later read adds lines. A reason's word longer than 29 characters is cut to 29 characters, ending with `…`, in the detail, and `reason` carries it whole. It says so too where a replica is not running, stopped, or has just restarted, or where the answer may lack lines. Where none of those holds and the direct read kept no line, the detail says the replicas' newest lines are in this answer. An empty answer then says only that the compute may have scaled to zero and written nothing. Lines still in the ingestion reach the log workspace up to about a minute after the process writes them, so a later read returns them. A `container` read whose `wait_seconds` did not hold says why, unless its budget leaves that sentence out. The causes are the place taken, the platform's waits or follows full, the management API near its limit, the direct read off, or, on the pod grain, no pod running to follow. It also says where more instances run than the three followed. A `container` answer from a failed health check's kept lines opens with what happened and where `read_status` holds the same lines. Its `contains`, `filter`, and `limit` sentences give counts alone and no span, since those lines carry no time."
},
"reason": {
"type": "string",
"description": "Present only where a `container` read's direct read of the replicas did not complete: the reason's one word, whole at any length, such as `timed_out`, `throttled`, `http_503`, or a network error code. The `detail` gives the same reason, cutting a word longer than 29 characters. On an answer with lines, or one the filter emptied, it also says the log workspace's lines are those it held at the read, unless its budget leaves that sentence out. A reason beside lines, `timed_out` among them, applies to the direct read alone; a later read adds lines. The word comes from the platform's own read of your replicas through the hosting provider, and its cause may not be known. It does not say whether your application is healthy; `read_status` does. A stream that responded with a 5xx status, 501 and 505 aside, was asked once more where the read's bound allowed."
},
"failed_check": {
"type": "object",
"description": "Present only on a `container` answer where the environment has no compute, no version serves, and the newest version's failed health or smoke check kept a record. Its lines are that record's, at most 40, and none written after the check. Its `version` and `kind` identify the failed version, `ended_at` its end, `since` the instant the check read its lines from, and `truncated` whether the check's bound cut them.",
"required": [
"version",
"kind",
"ended_at",
"since",
"truncated"
],
"properties": {
"version": {
"type": "integer"
},
"kind": {
"type": "string",
"enum": [
"deploy",
"promote",
"restart"
]
},
"ended_at": {
"type": [
"string",
"null"
]
},
"since": {
"type": [
"string",
"null"
]
},
"truncated": {
"type": "boolean"
}
},
"additionalProperties": false
},
"environment": {
"type": "string"
},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": [
"at",
"level",
"source",
"message"
],
"properties": {
"at": {
"type": "string"
},
"level": {
"type": "string"
},
"source": {
"type": "string"
},
"message": {
"type": "string"
},
"fields": {
"type": "object"
}
}
}
},
"waited_ms": {
"type": "integer",
"minimum": 0,
"description": "Present where the request carried `wait_seconds`: the time the answer was held, in milliseconds. On a store source, the answer's `lines` and `entries` come from a fresh read after the wait, whatever ended it. A `container` answer on a container app merges the store's lines with every line its follows read, and on a pod it carries the followed lines alone. It carries no `settled`."
},
"console_since": {
"type": [
"string",
"null"
],
"description": "Present on a `container` answer where the environment runs as a pod, from a read that did not follow the console. It is where the live console the read covered begins: the start of the oldest standing pod's earliest container whose log the cluster keeps. A line written before it is not in the live console; it can answer only as an ended-pod line, marked `[pod-ended]`, where its process kept it. Null where the environment has no pod, and absent on the container grain and on an answer a wait's follow composed."
},
"page": {
"$ref": "#/shapes/page"
}
}
}
}
Shared contracts #
- Refusals: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md