Logging for Java SDK

This page explains how to configure logging in the PubNub Java Software Development Kit (SDK) using SLF4J and custom loggers.

Logging architecture

You can configure logging for different environments and use cases:

• SLF4J integration: All logs route through SLF4J, allowing you to use any SLF4J-compatible backend (logback, log4j, slf4j-simple, commons-logging, java.util.logging)
• Custom loggers: Optionally add custom logger implementations via the customLoggers configuration parameter. Use it if your slf4j implementation doesn't meet your needs.

The SDK sends all log entries to both slf4j and any configured custom loggers simultaneously.

Log levels

SLF4J uses standard log levels:

Level	Purpose
TRACE	Internal operations: serialization, encryption, subscription lifecycle, and detailed execution flow
DEBUG	User inputs, API parameters, HTTP requests and responses, and configuration properties
INFO	Significant events like successful initialization and configuration changes
WARN	Deprecation warnings, unusual conditions, and non-breaking validation warnings
ERROR	Errors, exceptions with stack traces, and failed operations

The SDK logs all configuration properties at DEBUG level during initialization. Secret keys are masked.

Custom loggers

You can implement the CustomLogger interface to implement your specific logging requirements, for example, route logs to external monitoring services, databases, or analytics platforms.

CustomLogger interface

The CustomLogger interface supports string messages and structured LogMessage objects:

1public interface CustomLogger {
2    String getName();
3    
4    // String-based logging methods
5    void trace(String message);
6    void debug(String message);
7    void info(String message);
8    void warn(String message);
9    void error(String message);
10    
11    // Structured logging methods
12    void trace(LogMessage logMessage);
13    void debug(LogMessage logMessage);
14    void info(LogMessage logMessage);
15    void warn(LogMessage logMessage);
16    void error(LogMessage logMessage);
17}

show all 17 lines

The SDK calls both overloads for each log entry:

• String version - a simplified, human-readable message
• LogMessage version - structured data including instance ID, timestamp, location, and typed content

All methods have default no-op implementations, so you only need to override the ones you plan to use.

Structured logging with LogMessage

LogMessage provides structured information for each log entry:

Field	Description
message	The log content (one of: Text, Object, Error, NetworkRequest, or NetworkResponse)
details	Optional additional context
type	Automatically inferred from message content (TEXT, OBJECT, ERROR, NETWORK_REQUEST, NETWORK_RESPONSE)
location	Source class or method generating the log
pubNubId	PubNub instance identifier
logLevel	The SLF4J log level (TRACE, DEBUG, INFO, WARN, ERROR)
timestamp	When the log was created with millisecond precision (format: HH:mm:ss.SSS)

Custom logger example

1

Configure the SDK with your custom logger:

1

Enable logging

Logging is automatically enabled when you create a PubNub instance. The SDK logs configuration details at the DEBUG level during initialization. SLF4J routes all logs to your configured backend.

1

The SDK automatically logs the complete configuration at initialization, including:

• User ID and subscribe key
• Publish key (if set)
• Secret key status (masked as "set: *****" if configured)
• Connection timeouts and retry settings
• Presence and heartbeat configuration
• Custom logger count (if configured)
• Instance identifier

Secret keys are masked

Secret keys and authentication tokens are never logged in plain text. The SDK logs only "set: *****" to indicate they are configured.

Logged information

The Java SDK logs information at various stages of operation. This provides complete visibility into SDK behavior.

Configuration at initialization

When you create a PubNub instance, the SDK logs all configuration properties at the DEBUG level. The SDK also logs any subsequent changes to these properties.

Each configuration log entry includes:

• Instance identifier (unique ID)
• SDK version information
• All configuration property names and values
• Masked sensitive values (secret keys, authentication tokens)

API call parameters

The SDK logs user-provided input data for each API call at the DEBUG level.

Logged parameters include:

• Channel names and channel groups
• Messages and metadata
• Timetoken values
• Filter expressions
• Custom query parameters
• Operation-specific parameters

These logs help identify mismatches. You can compare expected input with actual data passed to endpoints.

Network requests and responses

The SDK logs complete HTTP transaction information at the DEBUG level:

Request logs include

• HTTP method (GET, POST, PATCH, DELETE)
• Complete URL with origin and path
• Query parameters as key-value pairs
• Request headers
• Request body content (for POST, PUT, or PATCH requests)
• Request identifier (if configured)

Response logs include

• HTTP status code
• Response headers
• Response body content
• Request URL for correlation

Network logs help troubleshoot connectivity issues. Network logs also show exactly what data flows between your application and PubNub servers.

Errors and exceptions

The SDK logs errors and exceptions at the ERROR level with:

• Error type (exception class name)
• Error message
• Stack trace (up to 10 frames)
• Duration before failure (for network errors)
• Request details for failed operations

SLF4J backend configuration

The following sections explain how to configure different SLF4J backends. Choose the backend that best fits your environment and logging requirements.

For more information about configuration parameters, refer to Configuration.

Implement logging using log4j

To implement logging using log4j you need to add the following references to the project. Using log4j you can log to console or a file or both.

• log4j-slf4j2 file which acts as a bridge between slf4j and log4j.
• log4j-api file, which provides the underlying logging framework.
• log4j-core file.

Configure the log4j2.xml file:

1

See this example:

1

Implement logging using slf4j-simple

To implement logging using slf4j-simple you need to add the following references to the project:

• slf4j-simple jar file (for example, slf4j-simple-2.0.17.jar or the latest version) which provides the underlying logging framework.
• Along with these references you need to add the simplelogger.properties file in the CLASSPATH.

Example of simplelogger.properties:

1

Example usage of slf4j-simple

1

Implement logging using logback

To implement logging using logback, you need to add the following references to the project:

• logback-classic and logback-core jar files which provide the underlying logging framework.

See this example:

1

Example of the logback.xml file:

1

Implement logging using java.util.logging

To implement logging using java.util.logging you need to add the following reference to the project:

• slf4j-jdk14 jar file which acts as a bridge between slf4j and java.

JVM runtime provides the underlying logging framework.

Implement logging using commons-logging

To implement logging using commons-logging you need to add the following reference to the project:

• slf4j-jcl jar file (for example, slf4j-jcl-1.7.36.jar or the latest version) which acts as a bridge between slf4j and common-logging
• common-logging.jar file which acts as an abstraction layer.

The underlying logging framework is chosen dynamically by commons-logging.

No logging

To implement no logging, add a reference to slf4j-nop jar file (for example, slf4j-nop-1.7.5.jar or the latest version).

Logging best practices

Use these recommendations for effective logging.

Choose the right log level for your backend

Environment	Recommended SLF4J Level
Production	WARN or ERROR to capture issues without performance impact.
Staging	INFO to monitor operational events.
Development	DEBUG when actively developing or investigating issues.
Deep troubleshooting	TRACE only when working with PubNub support on complex issues.

Configure your SLF4J backend (log4j, logback, etc.) to set the appropriate level for the com.pubnub logger:

<!-- Example logback.xml configuration -->
<logger name="com.pubnub" level="INFO" additivity="false">
    <appender-ref ref="CONSOLE"/>
</logger>

Protect sensitive data

Never enable DEBUG or TRACE logging in production environments that handle sensitive information.

These levels may expose:

• API keys (publish and subscribe keys are visible in requests)
• User identifiers
• Message content
• Authentication tokens (masked as "set: *****" in configuration, but visible in network requests)

Use custom loggers for monitoring

Implement CustomLogger to route critical errors and metrics to external monitoring services without affecting SLF4J logging:

configBuilder.customLoggers(List.of(
    new MonitoringLogger(),  // Send errors to monitoring service
    new MetricsLogger()      // Track usage patterns
));

Custom loggers receive structured LogMessage objects that are easier to parse than string-based logs.

Monitor log volume

TRACE and DEBUG levels generate significant output. Ensure your logging infrastructure can handle the volume. This is especially important in high-throughput applications.

Network request and response logging at DEBUG level can be particularly verbose for applications with many API calls.

Optimize performance in production

Set your SLF4J backend to WARN or ERROR level for the com.pubnub logger. This optimizes performance and reduces storage costs:

<!-- Production logback.xml configuration -->
<logger name="com.pubnub" level="WARN" additivity="false">
    <appender-ref ref="CONSOLE"/>
</logger>

Provide complete logs to support

When reporting issues to PubNub support, provide complete logs:

1. Set your SLF4J backend to DEBUG or TRACE level for com.pubnub
2. Reproduce the issue
3. Collect logs from SDK initialization through the problem occurrence
4. Include the PubNub SDK version and Java version

The configuration is automatically logged at initialization, which helps support diagnose issues faster.