BudgethostAPI DOCUMENTATION
API v1OpenAPI
LOGGING PILOTREST / JSON

Search your application logs

Search collected container output across a slice, inspect source coverage and download a bounded history.

When retained logging is available for your workspace, open Logs in Portal and choose a slice with logging enabled to search container stdout/stderr across its applications and components. By default, logging retains seven days of newly collected output. Existing slices require explicit enablement by a workspace manager; older output is not backfilled.

The timeline orders entries by received time. Hover the received time to see the source time, which can differ when delivery is delayed. Collection status, usage and gap notices distinguish missing history from an empty search. Applications can print secrets or personal information; avoid doing so even though supported credential patterns are redacted. Disabling collection stops new forwarding; existing history expires normally. It does not delete previously retained logs.

URL query strings in container output are omitted by default before they are retained. A workspace manager can enable Include URL query strings in Logging settings, or set include_query_strings: true with a version-checked settings request. This explicitly keeps every query parameter, including credentials and personal information; parameters are not classified by name. Other credential redaction still applies outside URL queries. The setting changes future capture only. Omitted values cannot be recovered, and disabling the setting does not rewrite previously stored entries. Unclassified legacy queries are omitted from API responses, but their original stored payloads expire under normal retention.

Each new stored entry records sensitive_logging_enabled, whether an explicit sensitive logging option was enabled at capture time, and sensitive_logging_reasons, which identifies those options. Query inclusion currently produces true with ["url_query_strings"]; without that opt-in, the values are false and []. Future log sources can add reasons without renaming the marker. These fields are assigned automatically.

Query-string disclosure requires the url_query_strings reason; other sensitive logging options do not enable it. Older entries may have unknown capture settings. These fields describe the capture policy, not the message contents: even false does not guarantee that application output contains no secrets. Changing settings does not sanitize historical entries.

History and collection settings#

In Slice settings > Logging, a manager can choose one or seven days of history. Shortening retention hides older entries immediately and queues asynchronous storage deletion. Increasing retention applies to future collection and cannot recover earlier history. The ingestion allowance is measured over seven days regardless of the history setting. Disabling collection does not purge history.

Collection settings applied shows whether your requested settings have taken effect for each source. Pending or unavailable sources are shown separately. Contact support to request deletion of retained history; customer tokens cannot request a purge. Deleting history does not reset the logging allowance.

Follow new logs polls for newly admitted entries in the selected rolling time range. It preserves filters and repeated messages, pauses when you scroll into older history or hide the page, and retries after interruptions. Custom fixed ranges use Search/Refresh instead. The view is capped at 5,000 entries.

API access#

Slice tokens need the explicit logs:read permission. A service token with that permission sees only its application's family, including attached services. Existing read grants do not include retained logs. logs:manage allows a slice token to change collection settings and does not grant log-read access.

  • GET /v1/deploy/slices/{sliceId}/logs: entries and continuation cursor.
  • GET /v1/deploy/slices/{sliceId}/logs/status: collection, quota and gaps.
  • GET /v1/deploy/slices/{sliceId}/logs/sources: authorized log sources.
  • GET /v1/deploy/slices/{sliceId}/logs/settings: collection settings.
  • PATCH /v1/deploy/slices/{sliceId}/logs/settings: version-checked settings.
  • GET /v1/deploy/slices/{sliceId}/logs/download: bounded NDJSON download.

The service-token routes use /v1/deploy/services/{serviceId}/logs and the same read-only suffixes. Service tokens cannot change slice collection settings. Deployment/build logs remain separate under the existing deployment endpoints.

Filters include RFC3339 since inclusive and until exclusive, service_id, root_service_id, component, source, stream, severity, literal case-insensitive q, order=asc|desc, and limit (default 200, maximum 1,000). The default time range is one hour; the maximum follows the selected one- or seven-day retention setting. For continuation, send only cursor. For live follow, send order=asc and after=<receipt_watermark> to fetch entries strictly after the prior admission position. Keep the time range within retention and drain every next_cursor page before advancing to the new receipt_watermark. Repeat the old position after failure and deduplicate by entry_id, never by message text. Refresh the search if the cursor expires or settings/ownership change. Downloads are limited to 10 MiB; narrow the range if the server rejects it. X-Log-Partial: true indicates incomplete source coverage.

Examples#

Linux / macOS - Bash
curl --fail-with-body -H "Authorization: Bearer $SLICE_TOKEN" \
  --get "$API_URL/v1/deploy/slices/$SLICE_ID/logs" \
  --data-urlencode 'q=connection refused' --data-urlencode 'limit=100'
curl --fail-with-body -X PATCH -H "Authorization: Bearer $SLICE_TOKEN" \
  -H 'Content-Type: application/json' -H 'X-Idempotency-Key: enable-logs-1' \
  --data '{"expected_version":0,"enabled":true}' \
  "$API_URL/v1/deploy/slices/$SLICE_ID/logs/settings"
Windows - PowerShell 7.4+
$headers = @{ Authorization = "Bearer $env:SLICE_TOKEN" }
$uri = "$env:API_URL/v1/deploy/slices/$env:SLICE_ID/logs?limit=100"
$page = Invoke-RestMethod -Uri $uri -Headers $headers
$page.data.entries
if ($page.data.next_cursor) {
  $cursor = [uri]::EscapeDataString($page.data.next_cursor)
  Invoke-RestMethod -Uri "$env:API_URL/v1/deploy/slices/$env:SLICE_ID/logs?cursor=$cursor" -Headers $headers
}
Node.js
const base = `${process.env.API_URL}/v1/deploy/slices/${encodeURIComponent(process.env.SLICE_ID)}/logs`;
const headers = { Authorization: `Bearer ${process.env.SLICE_TOKEN}` };
let query = 'limit=100';
do {
  const response = await fetch(`${base}?${query}`, { headers });
  const result = await response.json();
  if (!response.ok) throw new Error(result.error?.message || `HTTP ${response.status}`);
  for (const entry of result.data.entries) console.log(entry.received_at, entry.component, entry.message);
  query = result.data.next_cursor ? `cursor=${encodeURIComponent(result.data.next_cursor)}` : '';
} while (query);

Settings changes require X-Idempotency-Key and the current expected_version. Read settings first; do not reuse version zero after an earlier change. If a settings update fails, retry the identical body and key. Quota limits stop additional collection while application output continues; rejected output is not replayed when the allowance recovers. A logging outage returns 503, not an empty success.

Secret redaction boundaries#

Recognized password arguments (--admin_password=x and --admin_password x) and known values from the application's bound secrets are redacted before logs are retained. If safe collection is unavailable, source status reports that gap. Historical output is not rewritten when redaction behavior changes.

Arbitrary application output, transformed credentials and partially echoed input cannot be assumed secret-free. sensitive_logging_enabled:false describes logging policy, not a guarantee that an application has emitted no secret. Avoid credentials in command arguments/output and rotate any exposed credential. Disabling logging or changing a redaction flag does not invalidate previously exposed credentials.