On this page

Logging practices

Logging helps you monitor activity, troubleshoot issues, and maintain audit trails. The PubNub Software Development Kits (SDKs) follow unified logging practices. This means you get consistent, actionable information across all platforms.

This guide covers logging concepts that apply to all PubNub SDKs. For platform-specific steps, see your SDK's Logging documentation:

Enable logging

Logging is disabled by default. This optimizes performance in production environments.

To see log output, enable logging in your SDK configuration. Then choose a log level to control the amount of detail captured.

Log levels

PubNub SDKs support standard log levels. Each level controls the amount of detail captured. Each level also includes messages from all higher severity levels.

Log LevelWhen to useWhat it captures
TRACE
Deep troubleshooting for complex issues
All internal operations: serialization, encryption, and detailed execution flow. Generates high volume output.
DEBUG
Development and bug investigation
User inputs, API (Application Programming Interface) channel parameters, HTTP request and response details, and configuration values.
INFO
Monitor significant events
Important operational events: successful initialization and configuration changes.
WARN
Identify potential issues
Deprecated features, unusual conditions, and non-breaking validation warnings.
ERROR
Troubleshoot failures
Errors, exceptions with stack traces, and failed operations.
Logging sensitive information

DEBUG and TRACE levels may log sensitive information. This includes API keys, user identifiers, and message content. Use these levels only in development environments. Never enable DEBUG or TRACE logging in production with sensitive data.

Logged information

PubNub SDKs log 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. The SDK also logs any subsequent changes to these properties.

Each configuration log entry includes:

  • Instance identifier (unique ID or memory location)
  • SDK version information
  • All configuration property names and values
  • Optional: Client IP address and platform details (where platform permits)
No secret keys in logs

Secret keys are never logged.

Configuration logs help you verify settings. Configuration logs also help troubleshoot issues across multiple instances in the same application.

API call parameters

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

Logged parameters include:

  • Channel names and channel groups
  • Messages and metadata
  • Timetoken values
  • Filter expressions
  • Custom query 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:

  • HTTP method (GET, POST, PATCH, DELETE)
  • Complete URL with query parameters
  • Request headers as key-value pairs
  • Request body content (for POST, PUT, or PATCH requests)
  • Timestamp with millisecond precision

Response logs include:

  • HTTP status code
  • Response body content
  • Request URL for correlation
  • Timestamp when response was received

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

Real time messaging activity

The SDK logs subscription-related operations at the TRACE level.

Subscription logs include:

  • State transitions during subscription lifecycle
  • Invocations and their parameters
  • Effect dispatching and processing

These logs help you trace the execution flow of real time messaging operations.

Encryption and decryption

When you use encryption features, the SDK logs crypto module activity.

Initialization logs (DEBUG level)

  • Crypto module type (for example, AesCbcCryptoModule)
  • Cipher key identifier (not the actual key value)

Operation logs (TRACE level)

  • Encryption or decryption start
  • Successful completion
  • Failure exceptions with error details

Data transformation

The SDK logs serialization and deserialization operations at the TRACE level.

Data transformation logs include:

  • Message serialization before sending
  • Response deserialization after receiving
  • Success confirmations
  • Failure exceptions with error details

Execution flow and validation

Throughout API request execution, the SDK logs different types of information at different levels.

  • WARN level: Deprecated features and non-breaking validation warnings
  • DEBUG level: Parameter validation results
  • TRACE level: Internal method call execution states

Log entry structure

Each log entry from PubNub SDKs includes these essential components:

ComponentDescription
Timestamp
Human-readable date and time with at least millisecond precision.
Instance identifier
Format like PubNub-{instanceId}. Distinguishes logs from multiple SDK instances.
Log level
TRACE, DEBUG, INFO, WARN, or ERROR.
Callsite
Optional information about the class or method generating the log. Included when it adds value.
Message
The log content describing the operation or event.

The specific format varies by platform and programming language. However, all SDKs include these components to ensure consistent, filterable logs.

Filter logs from multiple instances

Your application may create multiple PubNub instances. Multiple sources may also write to the same log destination (such as the console).

The instance-specific identifier helps you filter and differentiate logs. This simplifies troubleshooting and analysis in complex applications.

Configure logging behavior

Most the PubNub SDKs provide configuration parameters to control logging.

Available configuration options:

Configuration OptionDescription
Log level
Specify the minimum log level to enable. Options: TRACE, DEBUG, INFO, WARN, ERROR, or NONE.
Custom loggers
Provide your own logging implementation. Route logs to specific destinations.
Output destinations
Direct logs to console, files, or external systems. Examples include databases and monitoring services.
Standard library integration
Some SDKs integrate with platform-standard logging frameworks. Examples include SLF4J for Java and Kotlin, and OSLog for Swift.

The specific configuration syntax varies by platform. Refer to your SDK's Configuration documentation for implementation details, for example JavaScript SDK.

Custom loggers

Most PubNub SDKs allow you to implement custom loggers. Language or platform restrictions may apply.

Custom loggers enable you to:

  • Send logs to external monitoring services
  • Store logs in databases for long-term analysis
  • Filter or transform log messages before output
  • Integrate with existing logging infrastructure

When custom loggers are supported, you typically implement a logger interface. Then pass your implementation to the SDK through configuration.

Some SDKs support registering multiple loggers simultaneously. This allows you to maintain default console logging while directing logs to additional destinations.

For implementation details and code examples, refer to your SDK's Logging documentation, for example JavaScript SDK.

Logging best practices

Use these recommendations for effective logging.

Choose the right log level

EnvironmentRecommended Log Level
Production
Enable ERROR and WARN to catch issues without performance impact.
Staging
Use INFO to monitor operational events.
Development
Enable DEBUG when actively developing or investigating issues.
Deep troubleshooting
Use TRACE only with guidance from PubNub support.

Filter logs by instance

Applications with multiple PubNub instances can become difficult to debug. Use the instance identifier to filter logs. Focus on specific instances during troubleshooting.

Protect sensitive data

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

These levels may expose:

  • API keys
  • User identifiers
  • Message content

Provide complete context to support

When reporting issues to PubNub support, provide complete logs:

  • SDK initialization and configuration
  • The complete sequence leading to the issue

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.

Disable logging when not needed

Turn off logging in production or set the log level to ERROR only. This optimizes performance and reduces storage costs.

SDK-specific implementation guides

Each SDK implements these logging concepts using platform-appropriate patterns and syntax.

For detailed implementation instructions, see your SDK's Logging documentation:

Last updated on