Logging¶

The Strands SDK provides logging infrastructure to give visibility into its operations.

PythonTypeScript

Strands SDK uses Python's standard logging module. The SDK implements a straightforward logging approach:

Module-level Loggers: Each module creates its own logger using logging.getLogger(__name__), following Python best practices for hierarchical logging.
Root Logger: All loggers are children of the "strands" root logger, making it easy to configure logging for the entire SDK.
Default Behavior: By default, the SDK doesn't configure any handlers or log levels, allowing you to integrate it with your application's logging configuration.

Strands SDK provides a simple logging infrastructure with a global logger that can be configured to use your preferred logging implementation.

Logger Interface: A simple interface (debug, info, warn, error) compatible with popular logging libraries like Pino, Winston, and the browser/Node.js console.
Global Logger: A single global logger instance configured via configureLogging().
Default Behavior: By default, the SDK only logs warnings and errors to the console. Debug and info logs are no-ops unless you configure a custom logger.

Configuring Logging¶

PythonTypeScript

To enable logging for the Strands Agents SDK, you can configure the "strands" logger:

import logging

# Configure the root strands logger
logging.getLogger("strands").setLevel(logging.DEBUG)

# Add a handler to see the logs
logging.basicConfig(
    format="%(levelname)s | %(name)s | %(message)s",
    handlers=[logging.StreamHandler()]
)

To enable logging for the Strands Agents SDK, use the configureLogging function. The SDK's logger interface is compatible with standard console and popular logging libraries.

Using console:

// Use the default console for logging
configureLogging(console)

Using Pino:

import pino from 'pino'

const pinoLogger = pino({
  level: 'debug',
  transport: {
    target: 'pino-pretty',
    options: {
      colorize: true
    }
  }
})

configureLogging(pinoLogger)

Default Behavior:

By default, the SDK only logs warnings and errors using console.warn() and console.error()
Debug and info logs are no-ops by default (zero performance overhead)
Configure a custom logger with appropriate log levels to enable debug/info logging

Log Levels¶

The Strands Agents SDK uses standard log levels:

DEBUG: Detailed operational information for troubleshooting. Extensively used for tool registration, discovery, configuration, and execution flows.
INFO: General informational messages. Currently not used.
WARNING: Potential issues that don't prevent operation, such as validation failures, specification errors, and compatibility warnings.
ERROR: Significant problems that prevent specific operations from completing successfully, such as execution failures and handler errors.
CRITICAL: Reserved for catastrophic failures.

Key Logging Areas¶

PythonTypeScript

The Strands Agents SDK logs information in several key areas. Let's look at what kinds of logs you might see when using the following example agent with a calculator tool:

from strands import Agent
from strands.tools.calculator import calculator

# Create an agent with the calculator tool
agent = Agent(tools=[calculator])
result = agent("What is 125 * 37?")

When running this code with logging enabled, you'll see logs from different components of the SDK as the agent processes the request, calls the calculator tool, and generates a response.

Tool Registry and Execution¶

Logs related to tool discovery, registration, and execution:

# Tool registration
DEBUG | strands.tools.registry | tool_name=<calculator> | registering tool
DEBUG | strands.tools.registry | tool_name=<calculator>, tool_type=<function>, is_dynamic=<False> | registering tool
DEBUG | strands.tools.registry | tool_name=<calculator> | loaded tool config
DEBUG | strands.tools.registry | tool_count=<1> | tools configured

# Tool discovery
DEBUG | strands.tools.registry | tools_dir=</path/to/tools> | found tools directory
DEBUG | strands.tools.registry | tools_dir=</path/to/tools> | scanning
DEBUG | strands.tools.registry | tool_modules=<['calculator', 'weather']> | discovered

# Tool validation
WARNING | strands.tools.registry | tool_name=<invalid_tool> | spec validation failed | Missing required fields in tool spec: description
DEBUG | strands.tools.registry | tool_name=<calculator> | loaded dynamic tool config

# Tool execution
DEBUG | strands.event_loop.event_loop | tool_use=<calculator_tool_use_id> | streaming

# Tool hot reloading
DEBUG | strands.tools.registry | tool_name=<calculator> | searching directories for tool
DEBUG | strands.tools.registry | tool_name=<calculator> | reloading tool
DEBUG | strands.tools.registry | tool_name=<calculator> | successfully reloaded tool

Event Loop¶

Logs related to the event loop processing:

ERROR | strands.event_loop.error_handler | an exception occurred in event_loop_cycle | ContextWindowOverflowException
DEBUG | strands.event_loop.error_handler | message_index=<5> | found message with tool results at index

Model Interactions¶

Logs related to interactions with foundation models:

DEBUG | strands.models.bedrock | config=<{'model_id': 'us.anthropic.claude-4-sonnet-20250219-v1:0'}> | initializing
WARNING | strands.models.bedrock | bedrock threw context window overflow error
DEBUG | strands.models.bedrock | Found blocked output guardrail. Redacting output.

The TypeScript SDK currently has minimal logging, primarily focused on model interactions. Logs are generated for:

Model configuration warnings: Unsupported features (e.g., cache points in OpenAI, guard content)
Model response warnings: Invalid formats, unexpected data structures
Bedrock-specific operations: Configuration auto-detection, unsupported event types

Example logs you might see:

# Model configuration warnings
WARN cache points are not supported in openai system prompts, ignoring cache points
WARN guard content is not supported in openai system prompts, removing guard content block

# Model response warnings
WARN choice=<null> | invalid choice format in openai chunk
WARN tool_call=<{"type":"function","id":"xyz"}> | received tool call with invalid index

# Bedrock-specific logs
DEBUG model_id=<us.anthropic.claude-sonnet-4-20250514-v1:0>, include_tool_result_status=<true> | auto-detected includeToolResultStatus
WARN block_key=<unknown_key> | skipping unsupported block key
WARN event_type=<unknown_type> | unsupported bedrock event type

Future versions will include more detailed logging for tool operations and event loop processing.

Advanced Configuration¶

PythonTypeScript

Filtering Specific Modules¶

You can configure logging for specific modules within the SDK:

import logging

# Enable DEBUG logs for the tool registry only
logging.getLogger("strands.tools.registry").setLevel(logging.DEBUG)

# Set WARNING level for model interactions
logging.getLogger("strands.models").setLevel(logging.WARNING)

Custom Handlers¶

You can add custom handlers to process logs in different ways:

import logging
import json

class JsonFormatter(logging.Formatter):
    def format(self, record):
        log_data = {
            "timestamp": self.formatTime(record),
            "level": record.levelname,
            "name": record.name,
            "message": record.getMessage()
        }
        return json.dumps(log_data)

# Create a file handler with JSON formatting
file_handler = logging.FileHandler("strands_agents_sdk.log")
file_handler.setFormatter(JsonFormatter())

# Add the handler to the strands logger
logging.getLogger("strands").addHandler(file_handler)

Custom Logger Implementation¶

You can implement your own logger to integrate with your application's logging system:

// Declare a mock logging service type for documentation
declare const myLoggingService: {
  log(level: string, ...args: unknown[]): void
}

const customLogger: Logger = {
  debug: (...args: unknown[]) => {
    // Send to your logging service
    myLoggingService.log('DEBUG', ...args)
  },
  info: (...args: unknown[]) => {
    myLoggingService.log('INFO', ...args)
  },
  warn: (...args: unknown[]) => {
    myLoggingService.log('WARN', ...args)
  },
  error: (...args: unknown[]) => {
    myLoggingService.log('ERROR', ...args)
  }
}

configureLogging(customLogger)

Best Practices¶

PythonTypeScript

Configure Early: Set up logging configuration before initializing the Agent
Appropriate Levels: Use INFO for normal operation and DEBUG for troubleshooting
Structured Log Format: Use the structured log format shown in examples for better parsing
Performance: Be mindful of logging overhead in production environments
Integration: Integrate Strands Agents SDK logging with your application's logging system

Configure Early: Call configureLogging() before creating any Agent instances
Default Behavior: By default, only warnings and errors are logged - configure a custom logger to see debug information
Production Performance: Debug and info logs are no-ops by default, minimizing performance impact
Compatible Libraries: Use established logging libraries like Pino or Winston for production deployments
Consistent Format: Ensure your custom logger maintains consistent formatting across log levels