Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt

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

Logging for Python tools in watsonx Orchestrate is intended to help support debugging during tool execution in watsonx Orchestrate SaaS, with clearly defined limits and lifecycle behavior. The process describes the recommended approach for Python tool development. Start tool development without any dependency of Watson Orchestrate Developer edition or watsonx Orchestrate SaaS. Develop and run all tool unit tests with Python as the only required runtime, along with the open source watsonx Orchestrate ADK Python library and any additional dependencies used by the tool. When you are past the unit test phase, deploy your tool to Developer edition, where the developer has full access to the tool pod outputs. Afterward, deploy the tool to watsonx Orchestrate SaaS. In SaaS, use the ibm_watsonx_orchestrate.run.logging.SpanLogger class, provided logs are captured per tool invocation and are made available as part of trace data for the tool execution, subject to size constraints.

​
Overview

When a Python tool runs in watsonx Orchestrate, the platform records execution details for that tool invocation to support observability and troubleshooting. To prevent excessive tool logs, overloading the system and to avoid the collection of sensitive customer data, tool logging behaves as follows:
  • Logs are collected per tool invocation
  • Logs are associated with the individual execution record of that tool in observability and 20 KB of most recent log data is available.
  • To aid performance, logs are written after tool execution completes
  • Process crash in user Python tool code is unexpected and rare. However, in such unexpected cases, only the exit code of the process is available.

​
Supported logging mechanism

Additionally, Python tools can write logs to observability by using the capability that is provided by watsonx Orchestrate:
PYTHON
from ibm_watsonx_orchestrate.run.logging import SpanLogger

logger = SpanLogger()
logger.info("Starting validation step")
logger.error("Failed to fetch employee record")
This logger is designed specifically for tool‑level observability and integrates directly with the watsonx Orchestrate tracing infrastructure. Over and above this specific logger, a tool can write logs to its owned external storage without any restrictions.

​
How tool logging works

The logging lifecycle for a Python tool invocation is as follows:
  1. A tool invocation begins and an execution record for the tool is created.
  2. Log messages that are written during execution are buffered in memory.
  3. When the tool invocation completes, either successfully or with a handled exception, most recent buffered logs are written as part of the tool’s execution record.
  4. The logs can be retrieved together with the execution trace data for that request.

​
Association with tool execution

Log entries that are generated by a Python tool are:
  • Associated with the span that represents that tool invocation
  • Part of the overall trace for the request
  • Retrieved together with traces by using the Traces API
This association allows tool logs to be correlated with the surrounding workflow and other spans in the same request.

​
Error and failure behavior

If a tool raises an exception that is handled by the runtime:
  • The tool’s span is marked with status ERROR.
  • Recent buffered log entries are written to the tool span.
  • The trace remains available for the standard trace retention period.
This behavior provides visibility into both the error status and the tool logs associated with a failed invocation.
Tool logs are written only after execution completes or fails with a handled exception. If the process stops unexpectedly, only the exit code is recorded.

​
Log retention and limits

To prevent excessive tool logs overloading the system, ibm_watsonx_orchestrate.run.logging.SpanLogger logs are subject to the following constraints:
  • Only the most recent log entries are retained.
  • The total amount of log data per invocation is capped (approximately 20 KB).
  • Individual log entries have a maximum size.
  • When limits are exceeded, older log entries are discarded first.
This logging mechanism is intended to provide context around error paths and failures.

​
Intended usage

This logging capability is designed to:
  • Support edge‑case debugging for watsonx Orchestrate SaaS tool execution through observability.
  • Provide contextual information when tools fail.
  • Enable observability through trace inspection in development and production environments.

​
Recommendations for logging

Persistent, high‑volume, or detailed logging is handled by the tool writing to external storage such as S3 or dedicated logging services. To enable correlation with watsonx Orchestrate execution data, include the request thread identifier when you log in externally:
PYTHON
thread_id = context.request_context.get("thread_id")
External logs can be correlated with the corresponding tool execution.