Log Streaming

Log streaming lets you access and process logs of a running process in real time, or retrieve a snapshot of all logs produced so far. Use streaming for long-running or background commands. Use snapshots when you only need the current output.

Every process started through the process module writes its output to a cursor-addressed log ledger. Each log frame carries a channel (stdout and stderr for commands, pty for PTY processes), the data, and a cursor you can use to resume reading from where you left off. See log frames for the full list of fields and channels.

For entrypoint log streaming, see entrypoint process. To stream logs while sending input to a running command, see execute interactive commands.

Use cases

Log streaming is used when an application needs the output of a process while the process still runs.

• Live output in a UI. Build, test, or training output appears in a web application as the process writes it. Each frame carries a timestamp, so the UI shows when the output was written. A PTY process sends its merged terminal output on one channel, escape sequences included.

• Agent feedback. An agent reads the output of a long command as it arrives and stops the command early on an error. A stream sends new output as it is written and ends once the process exits. Its state event reports the exit code, signal, and reason of the process.

• Reconnects. A client that loses its connection resumes from its last cursor. No frame is delivered twice, and no retained frame is missed. An SSE client sends the ID of the last event it received, and the daemon uses that ID as the cursor.

• Server logs. The output of a background web server or worker is followed for as long as the process runs. When the server writes nothing, the daemon sends a keepalive every 15 seconds. The CLI follows the logs until the process exits, then exits with the exit code of the process. If the CLI timeout passes first, the CLI stops following and the process keeps running.

• Error handling. Stdout and stderr arrive on separate channels, so an application handles errors apart from regular output. Order is kept within a channel, not across channels. The CLI writes stdout frames to its standard output and stderr frames to its standard error.

Stream logs

Stream the logs of a process. A stream replays the retained output from the beginning or from a cursor, then new output as it is written. It ends once the process exits and all output is delivered. While the process is silent, the daemon sends a keepalive every 15 seconds.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

handle = sandbox.process.start(
    'for i in {1..5}; do echo "Step $i"; echo "Error $i" >&2; sleep 1; done'
)

for event in handle.stream_logs():
    if event.type == "log":
        print(f"[{event.frame.channel.upper()}]: {event.frame.data}", end="")

Stream events

Handle the events of a log stream. Each event carries a cursor, also sent as the event ID, so a client can resume after any event. A stream ends after its end event or its error event.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

handle = sandbox.process.start("for i in {1..3}; do echo \"Step $i\"; sleep 1; done")

# The generator returns after the eof event; a stream error is raised
for event in handle.stream_logs():
    if event.type == "log":
        print(f"[{event.frame.channel.upper()}]: {event.frame.data}", end="")
    elif event.type == "state":
        print(f"Exit code: {event.result.exit_code}, reason: {event.result.reason}")
    elif event.type == "warning":
        print(f"Older logs were evicted, resuming from {event.first_available_cursor}")
    elif event.type == "eof":
        print(f"Stream complete at cursor {event.cursor}")

Resume a stream

Resume a stream from a cursor. A stream opened with a cursor starts strictly after that position, so no frame is delivered twice. An SSE client that reconnects sends the ID of the last event it received, and the daemon uses that ID in place of the cursor. If retention evicted the position, the stream warns and continues from the oldest retained frame.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

handle = sandbox.process.start("for i in {1..5}; do echo \"Step $i\"; sleep 1; done")

# Stop early, remembering the cursor of the last frame processed
last_cursor = None
for event in handle.stream_logs():
    if event.type != "log":
        continue
    print(event.frame.data, end="")
    last_cursor = event.cursor
    if event.frame.data.startswith("Step 3"):
        break

# Resume strictly after the last frame seen
for event in handle.stream_logs(cursor=last_cursor):
    if event.type == "log":
        print(event.frame.data, end="")

Retrieve all existing logs

Read the logs a process has produced so far. A read returns one page and does not wait for new output. Output longer than one page needs pagination.

# Logs produced up to the current point in time
page = handle.logs()
for frame in page.items:
    print(f"[{frame.channel.upper()}]: {frame.data}", end="")

Paginate logs

Read logs page by page. Pass the next cursor of a page to read the page after it. An empty page means the read has caught up with the output; a process that is still running can produce more.

from daytona import Daytona
from daytona.v2 import LogFrame

daytona = Daytona()
sandbox = daytona.v2.create()

handle = sandbox.process.start("seq 1 5000")
handle.wait()

frames: list[LogFrame] = []
cursor = None
while True:
    page = handle.logs(cursor=cursor, limit=500)
    frames.extend(page.items)
    if not page.items or page.next_cursor == cursor:
        break
    cursor = page.next_cursor

stdout = "".join(frame.data for frame in frames if frame.channel == "stdout")
print(f"{len(frames)} frames, {len(stdout)} bytes of stdout")

Binary output

Read binary output without loss. The default text encoding replaces bytes that are not valid UTF-8. Base64 encoding returns the raw bytes of each frame as standard base64 with padding.

import base64

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

handle = sandbox.process.start("head -c 1024 /dev/urandom")
handle.wait()

page = handle.logs(encoding="base64")
raw = b"".join(
    base64.b64decode(frame.data)
    for frame in page.items
    if frame.channel == "stdout"
)
print(f"{len(raw)} bytes")

Log frames

Log retention

Control how long a process record and its logs are kept. The retention policy is set when the process starts. Independent of the policy, retained output is capped in size; output beyond the cap evicts the oldest frames. A page read from an evicted position fails with an error that names the oldest retained position; a stream warns and continues from that position.

from daytona import Daytona
from daytona.v2 import CursorExpiredError

daytona = Daytona()
sandbox = daytona.v2.create()

# Keep the logs of an unnamed process until delete()
handle = sandbox.process.start("seq 1 5000", keep_logs="until_cleanup")
handle.wait()

saved_cursor = "..."  # a cursor stored from an earlier read
try:
    page = handle.logs(cursor=saved_cursor)
except CursorExpiredError as e:
    # The position was evicted; restart from the oldest retained frame
    page = handle.logs(cursor=e.first_available_cursor)

handle.delete()

Permissions

Log streaming runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an organization role or an API key.

A sandbox access token with the toolbox:exec operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access.