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.

Write task logs
Use context.logger inside Task.execute. It supports standard log levels and structured attributes.
from tilebox.workflows import ExecutionContext, Task
class ProcessScene(Task):
scene_id: str
def execute(self, context: ExecutionContext) -> None:
context.logger.info("Started scene processing", scene_id=self.scene_id)
log = context.logger.bind(component="atmospheric-correction")
log.debug("Fetching auxiliary data")
try:
# process the scene
log.info("Scene processed", output_format="cog")
except Exception:
context.logger.exception("Scene processing failed", scene_id=self.scene_id)
raisepackage tasks
import (
"context"
"log/slog"
)
type ProcessScene struct{}
func (t *ProcessScene) Execute(ctx context.Context) error {
slog.InfoContext(ctx, "started scene processing", slog.String("scene_id", "S2A_001"))
slog.DebugContext(ctx, "fetching auxiliary data", slog.String("component", "atmospheric-correction"))
return nil
}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:
INFO 2026-10-30 12:23:57.394GMT+1 Scene processed scene_id="S2A_001" bands=3Timestamps 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.
import logging
from tilebox.workflows import Client
from tilebox.workflows.observability.logging import configure_log_level
from my_workflow import ProcessScene
configure_log_level(logging.DEBUG)
client = Client()
runner = client.runner(tasks=[ProcessScene])
runner.run_forever()package main
import (
"context"
"log/slog"
"github.com/tilebox/tilebox-go/workflows/v1"
)
type ProcessScene struct{}
func (t *ProcessScene) Execute(ctx context.Context) error {
slog.InfoContext(ctx, "processing scene")
return nil
}
func main() {
ctx := context.Background()
workflows.ConfigureConsoleLogging(slog.LevelDebug)
client := workflows.NewClient()
runner, err := client.NewTaskRunner(ctx)
if err != nil {
slog.ErrorContext(ctx, "failed to create runner", slog.Any("error", err))
return
}
if err := runner.RegisterTasks(&ProcessScene{}); err != nil {
slog.ErrorContext(ctx, "failed to register tasks", slog.Any("error", err))
return
}
runner.Run(ctx)
}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:
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.
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.
from tilebox.workflows import Client
client = Client()
job = client.jobs().submit("process-scene", ProcessScene(scene_id="S2A_001"))
logs = client.jobs().query_logs(job)
for record in logs:
print(record.time, record.severity_text, record.body, record.attributes)
df = logs.to_pandas()package main
import (
"context"
"fmt"
"log/slog"
"time"
"github.com/google/uuid"
"github.com/tilebox/tilebox-go/workflows/v1"
)
func main() {
ctx := context.Background()
client := workflows.NewClient()
jobID := uuid.MustParse("019e07b1-916b-0630-f3ba-f1c33235d174")
logs, err := workflows.Collect(
client.Jobs.QueryLogs(ctx, jobID, workflows.WithSortDirection(workflows.Ascending)),
)
if err != nil {
slog.ErrorContext(ctx, "failed to query job logs", slog.Any("error", err))
return
}
for _, record := range logs {
fmt.Printf("%s %-5s %s\n",
record.Time.Format(time.RFC3339Nano),
record.Level,
record.Body,
)
}
}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.