Logging

This guide explains how to manage the Aerospike Python client’s logging interface, including setting log levels and implementing custom callbacks. It covers default behavior, log level constants, and when to enable logging for cluster tend troubleshooting.

The client provides a logging interface for handling log messages. Most log messages come from the background cluster tend thread created for each client instance. Messages include node additions and removals and any errors when retrieving node status, peers, partition maps, and racks. This information is critical for debugging command failures resulting from cluster tend errors.

By default, the client log level is aerospike.LOG_LEVEL_ERROR and the default log handler prints messages to the console.

Enable client log

Configure logging at application start, before connecting to the server.

To use the default console log handler:

import aerospike

aerospike.set_log_handler()
aerospike.set_log_level(aerospike.LOG_LEVEL_INFO)

To use a custom callback:

import aerospike

def log_callback(level, func, path, line, msg):
    print(f"[{func}] {msg}")

aerospike.set_log_handler(log_callback)
aerospike.set_log_level(aerospike.LOG_LEVEL_DEBUG)

The callback must accept five parameters in this order: level, function, path, line, and message.

Disable client log

To disable logging, set the log level to aerospike.LOG_LEVEL_OFF or clear the log handler:

import aerospike

aerospike.set_log_level(aerospike.LOG_LEVEL_OFF)

# Or clear the saved log handler
aerospike.set_log_handler(None)

Setting the log level to aerospike.LOG_LEVEL_OFF does not reset the saved log handler.

Log level

Client log messages can be filtered by log level. Each level includes the levels above it, so aerospike.LOG_LEVEL_INFO includes INFO, WARN, and ERROR messages.

Level	Constant	Description
Trace	aerospike.LOG_LEVEL_TRACE	Most verbose output
Debug	aerospike.LOG_LEVEL_DEBUG	Extra debug data, including partition map updates
Info	aerospike.LOG_LEVEL_INFO	Informational cluster changes, such as node add/remove
Warn	aerospike.LOG_LEVEL_WARN	Cluster tend warnings that may lead to command failures
Error	aerospike.LOG_LEVEL_ERROR	Serious errors (default threshold)
Off	aerospike.LOG_LEVEL_OFF	Disable log output

Example:

import aerospike

aerospike.set_log_level(aerospike.LOG_LEVEL_DEBUG)

When to enable logging

Enable logging when troubleshooting:

• Connection or TLS handshake failures
• Intermittent timeouts or MaxErrorRateExceeded errors
• Unexpected node add/remove events during cluster changes
• Query or batch job failures after cluster maintenance

For mTLS connections, combine debug logging with TLS configuration checks on both client and server. See Managing mTLS with the Python client.

See the logging API reference for additional details.