Configure logging

Applies to

• Aerospike Developer SDK (Java 21+ and Python 3.11+)
• Aerospike Database 8.2.0 or later, unless a section states otherwise

Code examples

Examples assume a connected session from Connect to Aerospike. Each usage guide lists shared imports in a tabbed block near the top of the page; snippet blocks add imports only for types not already shown. The first code block in each section includes dataset setup; later blocks in that section reuse those values. When a page includes a Complete example section, that block is fully self-contained.

Client-side logging helps you debug connection issues, monitor cluster health, and troubleshoot performance problems.

Why client logging matters

The Developer SDK runs background threads that:

• Maintain cluster topology (node discovery)
• Monitor connection health
• Handle failover events

These events are logged and crucial for diagnosing production issues.

Enable logging

Java

The Java SDK logs through SLF4J under short category names, not a package name: tend (cluster discovery and node changes), connection, command, query, behavior, info, metrics, ael, and serde. The constants are in com.aerospike.client.sdk.Loggers. Add a logging implementation to your project:

<!-- Logback (recommended) -->
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.4.14</version>
</dependency>

Configure logback.xml:

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Aerospike Java SDK categories -->
    <logger name="tend" level="INFO"/>
    <logger name="behavior" level="INFO"/>

    <root level="WARN">
        <appender-ref ref="STDOUT"/>
    </root>
</configuration>

Python

The Python SDK uses the standard logging module under three logger roots: aerospike_sdk (SDK commands, queries, and lifecycle), aerospike_native (the underlying native client), and aerospike_core (cluster tend, connection pools, and wire protocol):

import logging

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Set Aerospike client log levels
for name in ('aerospike_sdk', 'aerospike_native', 'aerospike_core'):
    logging.getLogger(name).setLevel(logging.INFO)

📖 PSDK Guide: Logging

Log levels

Level	When to Use	What’s Logged
ERROR	Production	Connection failures, unrecoverable errors
WARN	Production	Retries, temporary failures, deprecation notices
INFO	Staging	Cluster topology changes, connection events
DEBUG	Development	All operations, request/response details
TRACE	Troubleshooting	Wire protocol, internal state

Python’s logging module names the warning level WARNING and has no TRACE level.

Recommended settings

Java

<!-- Production -->
<logger name="tend" level="WARN"/>
<logger name="command" level="WARN"/>

<!-- Development -->
<logger name="command" level="DEBUG"/>
<logger name="query" level="DEBUG"/>

<!-- Troubleshooting connection issues -->
<logger name="tend" level="DEBUG"/>
<logger name="connection" level="DEBUG"/>

Python

# Production
logging.getLogger('aerospike_sdk').setLevel(logging.WARNING)

# Development
logging.getLogger('aerospike_sdk').setLevel(logging.DEBUG)

# Troubleshooting connection issues
logging.getLogger('aerospike_core.cluster').setLevel(logging.DEBUG)

📖 PSDK Guide: Logging

Disable logging

To completely disable client logging:

Java

<logger name="tend" level="OFF"/>
<logger name="connection" level="OFF"/>
<logger name="command" level="OFF"/>
<!-- Repeat for query, behavior, info, metrics, ael, and serde -->

Or programmatically:

import org.slf4j.LoggerFactory;
import ch.qos.logback.classic.Level;
import ch.qos.logback.classic.Logger;
import com.aerospike.client.sdk.Loggers;
import java.util.List;

for (String name : List.of(Loggers.AEL, Loggers.BEHAVIOR, Loggers.CONNECTION, Loggers.COMMAND,
        Loggers.INFO, Loggers.METRICS, Loggers.QUERY, Loggers.SERDE, Loggers.TEND)) {
    ((Logger) LoggerFactory.getLogger(name)).setLevel(Level.OFF);
}

📖 API reference: com.aerospike.client.sdk

Python

for name in ('aerospike_sdk', 'aerospike_native', 'aerospike_core'):
    logging.getLogger(name).setLevel(logging.CRITICAL + 1)

aerospike_native and aerospike_core messages come from native code, which caches each logger’s level when it first emits. Levels set before connect() always apply. To change them on a connected client, call aerospike_sdk.loggers.refresh_log_levels() after setLevel().

📖 PSDK Guide: Logging

Or stop the records from reaching your handlers. Add a NullHandler as well: a logger with no handlers that does not propagate still prints warnings to stderr through Python’s last-resort handler.

for name in ('aerospike_sdk', 'aerospike_native', 'aerospike_core'):
    logger = logging.getLogger(name)
    logger.addHandler(logging.NullHandler())
    logger.propagate = False

📖 PSDK Guide: Logging

Custom logger implementation

For advanced scenarios, you can provide a custom logger:

Java

// The client uses SLF4J, so any SLF4J-compatible logger works
// No custom implementation needed - just configure your logging framework

📖 API reference: com.aerospike.client.sdk

Python

import logging
class CustomHandler(logging.Handler):
    def emit(self, record):
        # Send to your monitoring system
        send_to_monitoring(record.getMessage(), record.levelname)

# Add custom handler
logger = logging.getLogger('aerospike_sdk')
logger.addHandler(CustomHandler())

📖 PSDK Guide: Logging

Log message reference

Cluster events

The Java SDK logs cluster events on its com.aerospike.client.sdk.tend logger, and the Python SDK on aerospike_core.cluster.

Event	Java SDK	Python SDK
Seeding starts	Add seed <host> <port> (DEBUG)	Seeding the cluster. Seeds count: <n> (INFO)
A seed host fails	Seed <host> <port> failed: <error> (WARN). By default, a connect() that reaches no seed throws instead.	Failed to validate seed host: <host>:<port> (ERROR)
A node joins	Add node <name> <host> <port> (INFO)	No message per node. Nodes [...] (DEBUG) lists the cluster’s nodes after each tend.
A node leaves	Remove node <name> <host> <port> (INFO)	Closing node <name>: <host>:<port> (DEBUG)
A node refresh fails	Node <name> <host> <port> refresh failed: <error> (WARN)	Node `<name>: <host>:<port>` refresh failed: <error> (WARN)

Error messages

Message Pattern	Likely Cause	Action
Failed to connect to [<n>] host(s), result code -8	No seed host answered: the server isn’t running, or the address, port, DNS or a firewall keeps the client from reaching it. Each host’s entry gives the reason, such as Connection refused (Python SDK) or Connection failed (Java SDK).	Check the server status, and that the client can reach each seed host on its service port
Result code 9 (TIMEOUT): Client timeout or Server timeout (Java SDK), TimeoutError (Python SDK)	Network latency or server overload	Check latency, adjust the Behavior’s timeouts

Next steps

Enable Metrics

Monitor client performance with metrics.

Metrics →

Handle Errors

Implement robust error handling.

Error Handling →