Skip to content

Logging

Emit structured task logs and tune how workflow clients export log records.

Tilebox collects workflow logs automatically. When a runner is created from a Client, logs emitted through the task execution context are exported to Tilebox and correlated with the active job, task, and trace.

Job Logs View

Write task logs

Use context.logger inside Task.execute. It supports standard log levels and structured attributes.

Structured attributes become searchable log attributes. Bind shared attributes to a logger when records need the same context.

What Tilebox adds automatically

Logs emitted from a task include workflow metadata without extra code. Tilebox attaches job ID, job name, task ID, task display name, parent task data, task identifier name and version, runner service data, SDK version, host, OS, and process ID. When a log is emitted inside an active span, Tilebox also attaches trace_id and span_id.

Logs are also added as events on the active trace span, so a trace view can show important log messages inline with task execution.

Configure local console logging

Python runners started directly from a script or notebook print logs to the console automatically. Calling get_logger() also enables console output unless you have disabled it. Built-in Tilebox export does not require configuration.

Console output includes a colored log level, a local timestamp with its timezone offset, the message, and structured attributes as key=JSON pairs. For example, context.logger.info("Scene processed", scene_id="S2A_001", bands=3) prints the following in a UTC+1 timezone, shown without colors:

text
INFO 2026-10-30 12:23:57.394GMT+1 Scene processed scene_id="S2A_001" bands=3

Timestamps use the system’s local timezone, including daylight-saving time. UTC timestamps end in Z; fractional offsets appear as, for example, GMT+5:45.

Attributes added with bind() appear in console output too. Strings are JSON-quoted, nested values retain their structure, and embedded newlines are escaped. Top-level attributes named task_id, trace_id, and span_id are omitted from the console but remain available to exporters and CLI streaming. Console formatting does not change the original message or attributes.

In Python, configure_log_level() sets the minimum level of task logs emitted to the console and exporters. Task logs default to INFO. The automatic console handler follows this level, so enabling DEBUG logs takes one call.

In Go, call workflows.ConfigureConsoleLogging() to print workflow logs to standard output at the given level.

Keep the Python console quieter than exports

Use configure_console_logging(filter_level=...) when you want the console to print fewer logs than you export. Its filter applies only to console output; it does not change which task logs are emitted or exported. External exporters may apply their own filters.

For example, emit DEBUG and above to Tilebox, but print only WARNING and above locally:

python
import logging

from tilebox.workflows.observability.logging import (
    configure_console_logging,
    configure_log_level,
)

configure_log_level(logging.DEBUG)
configure_console_logging(filter_level=logging.WARNING)

The task log level is checked first. If it is INFO, setting the console filter to DEBUG cannot recover the discarded DEBUG records.

The console filter defaults to logging.NOTSET, which adds no filtering beyond the originating logger’s level. Call configure_console_logging() to remove a custom console filter without changing task verbosity. You can also pass stream=... to change the output stream; the default is standard output. These settings apply within the current Python process.

If you previously passed level=... to configure_console_logging(), rename that keyword to filter_level=.... Positional calls such as configure_console_logging(logging.WARNING) still work.

Disable Python console output

Call disable_console_logging() to remove Tilebox-managed console handlers. You can call it before creating a runner or logger; later initialization keeps console output disabled in the current process.

python
from tilebox.workflows.observability.logging import (
    configure_console_logging,
    disable_console_logging,
)

disable_console_logging()

# To restore console output later:
configure_console_logging()

configure_console_logging(enabled=False) remains supported and has the same effect as disable_console_logging().

Disabling console output does not disable Tilebox export, external exporters, CLI log streaming, or application-installed handlers. If your application already configures logging handlers, disable Tilebox’s console output to avoid printing the same record twice. Managed CLI streaming does not add the automatic direct-runner console handler.

Query logs

You can retrieve logs for a job through the jobs client. Python results can also be converted to a pandas DataFrame.

See Query telemetry for the log and span query APIs.

Export to another backend

Tilebox stores logs by default. To export logs to your own observability backend as well, configure an OpenTelemetry or Axiom integration when the runner process starts.

Type to search…