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.
| Log Level | When to use | What it captures |
|---|---|---|
NONE | Production with no monitoring | Logging completely disabled. Optimizes performance. |
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 (Hypertext Transfer Protocol) 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. |
The hierarchy flows from most to least severe: ERROR → WARN → INFO → DEBUG → TRACE. When you set a log level, the SDK automatically includes messages from all higher severity levels. For example, setting INFO will also capture WARN and ERROR messages.
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.
Instance identifiers vary by SDK but follow a consistent pattern:
- Format:
PubNub-{instanceId} - Length: Typically 6-8 characters
- Content: Alphanumeric characters or UUID (Universally Unique Identifier) substring
- Uniqueness: Random per SDK instance creation
Example instance identifiers: PubNub-a1b2c3, PubNub-d4e5f6g7h8
Configure logging behavior
Most 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 | Rationale |
|---|---|---|
| Production | ERROR or WARN | Captures critical issues without performance impact. Protects sensitive data. |
| Staging | INFO | Monitors operational events and configuration for pre-production validation. |
| Development | DEBUG | Provides detailed information for active development and issue investigation. |
| Deep troubleshooting | TRACE | Use only when working with PubNub support on complex issues. Generates very high log volume. |
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, include comprehensive logging information:
| Step | Action | Details |
|---|---|---|
| 1 | Enable appropriate logging | Set log level to DEBUG or TRACE before reproducing the issue |
| 2 | Capture the full sequence | SDK initialization and configuration (shows SDK version and settings) The complete operation sequence leading to the issue Any error messages or exceptions |
| 3 | Include environment details | SDK version, platform, runtime version |
| 4 | Preserve timestamps | Maintain timestamp information to help correlate logs with server-side data |
| 5 | Sanitize sensitive data | Remove or mask any credentials, user data, or message content before sharing logs |
Complete logs significantly reduce resolution time by providing PubNub support with the necessary context to diagnose issues quickly.
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.
Optimize logging performance
Logging can impact application performance, especially at DEBUG and TRACE levels:
- Use appropriate log levels: Higher levels (
ERROR,WARN) have minimal performance impact - Avoid expensive operations (network calls, database writes) in the logger's hot path
- When possible, buffer and write logs asynchronously to avoid blocking your application
- In high-throughput applications, consider sampling verbose logs rather than capturing everything
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: