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 Level | When to use | What 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.
WARNlevel: Deprecated features and non-breaking validation warningsDEBUGlevel: Parameter validation resultsTRACElevel: Internal method call execution states
Log entry structure
Each log entry from PubNub SDKs includes these essential components:
| Component | Description |
|---|---|
| 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 Option | Description |
|---|---|
| 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
| Environment | Recommended 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: