Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.podflare.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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). 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.