Observability

Every Podflare HTTP request gets a http_request tracing span. Every executor operation (create, exec, fork, merge_into, destroy) emits a nested event inside that span with structured fields. Pass a traceparent header (or SDK kwarg) and Podflare binds your upstream trace_id + parent_span_id to every log line.

Propagation

Supply a W3C Trace Context traceparent string (00-<trace>-<span>-<flags>) and the SDK forwards it on every HTTP request:

from podflare import Sandbox, Client

# Option 1: per-Sandbox
with Sandbox(traceparent="00-4bf92f35...4736-00f067aa0ba902b7-01") as s:
    s.run_code("...")

# Option 2: per-Client (reused across many sandboxes)
client = Client(traceparent="00-...-01")
sbx = Sandbox(client=client)

# Option 3: env var (picked up automatically)
# PODFLARE_TRACEPARENT=00-...-01

import { Sandbox, Client } from "podflare";

const sbx = await Sandbox.create({
  traceparent: "00-4bf92f35...4736-00f067aa0ba902b7-01",
});

// or per-client:
const client = new Client({ traceparent: "00-...-01" });
const sbx2 = await Sandbox.create({ client });

// PODFLARE_TRACEPARENT env var also works.

What shows up in hostd logs

Default (text) formatter:

2026-04-18T14:00:00Z INFO http_request method=POST path=/v1/sandboxes/sbx_x/exec trace_id=4bf92f35...4736 parent_span_id=00f067aa0ba902b7 message="agent connected" id=sbx_x connect_ms=0

Every nested log line carries the request’s trace_id + parent_span_id — ready for grep-based correlation or pipe-into-structured-log-aggregator. JSON formatter (PODFLARE_LOG_FORMAT=json):

{
  "timestamp": "2026-04-18T14:00:00Z",
  "level": "INFO",
  "message": "agent connected",
  "span": {"name": "http_request", "trace_id": "4bf92f35...4736", "parent_span_id": "00f067aa0ba902b7"},
  "sandbox_id": "sbx_x",
  "connect_ms": 0
}

Ship those JSON lines to Langfuse, LangSmith, Braintrust, Datadog, Loki, or your log aggregator of choice.

Fields Podflare emits

span

http_request

Per-HTTP-request root span. Fields:

method — HTTP method.
path — request path, e.g. /v1/sandboxes/:id/exec.
trace_id — from incoming traceparent, empty if not provided.
parent_span_id — ditto.

Inner events use names like sandbox claimed, VM booted, fork complete, agent connected, etc., with the operation’s relevant fields (template, sandbox id, durations in ms, source = pool/on_demand/snapshot).

Recommended: ship logs as OTel events

Podflare emits structured tracing spans. You can bridge those to OTLP by running hostd with tracing-opentelemetry configured (planned; contributions welcome). Until then the simplest path is: set PODFLARE_LOG_FORMAT=json, pipe stdout to vector / otel-collector / fluent-bit configured as an OTLP exporter.

Environment

PODFLARE_LOG_FORMAT

string

default:"text"

Set to json for one-line-per-event JSON (span fields + message).

PODFLARE_TRACEPARENT

string

SDK-side: fallback value for Client(traceparent=...) / Sandbox(traceparent=...) when none is passed explicitly. Useful for quick experimentation.

RUST_LOG

string

default:"info,tower_http=info"

hostd-side: tracing-subscriber EnvFilter syntax. trace / debug levels surface more detail per operation.

Get Started

Concepts

SDKs

Examples

Integrations

Propagation

What shows up in hostd logs

Fields Podflare emits

Recommended: ship logs as OTel events

Environment

​Propagation

​What shows up in hostd logs

​Fields Podflare emits

​Recommended: ship logs as OTel events

​Environment

Propagation

What shows up in hostd logs

Fields Podflare emits

Recommended: ship logs as OTel events

Environment