---
title: "Logging"
description: "Configure and enable logging in the Aerospike Python client to debug cluster errors and manage log verbosity."
---

# Logging

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

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:

```python
import aerospike

aerospike.set_log_handler()

aerospike.set_log_level(aerospike.LOG_LEVEL_INFO)
```

To use a custom callback:

```python
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:

```python
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:

```python
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](https://aerospike.com/docs/develop/client/python/mtls/).

See the [logging API reference](https://aerospike-python-client.readthedocs.io/en/latest/aerospike.html#logging) for additional details.