Logging for JavaScript SDK

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

Logging architecture

The JavaScript SDK provides a flexible logging system. You can configure the logging system for different environments and use cases:

• Log levels control logging verbosity from detailed trace logs to errors only
• Built-in console logger automatically outputs to the browser console or Node.js console
• Custom loggers allow you to add custom logger implementations via the loggers configuration parameter
• Structured logging includes instance IDs, timestamps, log levels, and typed content

The SDK sends all log entries to both the built-in console logger and any configured custom loggers simultaneously.

Log levels

The SDK uses six log levels. The levels range from most verbose to least verbose:

Level	Purpose
LogLevel.Trace	Logs every detail including function calls, full payloads, internal variables, and state-machine transitions
LogLevel.Debug	Logs SDK logic including inputs and outputs to public methods, HTTP (Hypertext Transfer Protocol) requests and responses, and configuration properties
LogLevel.Info	Logs significant events such as successful initialization and connection status changes
LogLevel.Warn	Logs non-fatal events including deprecation warnings, request retries, and unusual conditions
LogLevel.Error	Logs errors, exceptions with stack traces, and HTTP failures
LogLevel.None	Disables logging (default)

Enable logging

Set the logLevel parameter during SDK initialization to enable console logging:

1import PubNub from 'pubnub';
2

3// Initialize PubNub with debug-level logging
4const pubnub = new PubNub({
5  subscribeKey: 'mySubscribeKey',
6  publishKey: 'myPublishKey',
7  userId: 'myUniqueUserId',
8  logLevel: PubNub.LogLevel.Debug
9});

Required User ID

Always set the userId to uniquely identify the user or device that connects to PubNub. This userId should be persisted and should remain unchanged for the lifetime of the user or the device. If you don't set the userId, you won't be able to connect to PubNub.

Configure detailed network logging

Use LogLevel.Trace to log detailed network information. This log level includes full HTTP request and response bodies:

1const pubnub = new PubNub({
2  subscribeKey: 'mySubscribeKey',
3  publishKey: 'myPublishKey',
4  userId: 'myUniqueUserId',
5  logLevel: PubNub.LogLevel.Trace
6});

Contact support

When troubleshooting issues, set logLevel to LogLevel.Debug or LogLevel.Trace. Reproduce the issue, copy the console output, and submit the output to support@pubnub.com.

Custom loggers

Implement the Logger interface to route logs to external monitoring services, databases, or analytics platforms. Custom loggers work alongside the built-in console logger.

Logger interface structure

The Logger interface provides methods for all log levels:

1/**
2 * Custom logger interface
3 */
4interface Logger {
5  /**
6   * Process a trace-level message
7   * @param message - Structured log message
8   */
9  trace(message: LogMessage): void;
10  
11  /**
12   * Process a debug-level message
13   * @param message - Structured log message
14   */
15  debug(message: LogMessage): void;
16  
17  /**
18   * Process an info-level message
19   * @param message - Structured log message
20   */
21  info(message: LogMessage): void;
22  
23  /**
24   * Process a warn-level message
25   * @param message - Structured log message
26   */
27  warn(message: LogMessage): void;
28  
29  /**
30   * Process an error-level message
31   * @param message - Structured log message
32   */
33  error(message: LogMessage): void;
34}

show all 34 lines

The SDK calls only the methods that correspond to the configured log level and above. For example, if you set logLevel to LogLevel.Warn, the SDK calls only the warn() and error() methods.

Structured logging with LogMessage

Each LogMessage object provides structured information. The following table describes the common fields present in all log messages (the BaseLogMessage interface):

Field	Description
timestamp	JavaScript Date object representing when the log was created
pubNubId	PubNub instance identifier (hash of instance ID)
level	Log level as a LogLevel enum value
minimumLevel	Minimum configured log level (useful for conditional detailed logging)
location	Source class or method that generated the log (when available)
messageType	Type of message content: 'text', 'object', 'error', 'network-request', or 'network-response'
message	Actual log content (type depends on messageType)

Custom logger example

The following example shows a custom logger that sends errors and failed requests to a monitoring service. When using TypeScript, type narrowing enables IDE autocomplete for type-specific fields:

1import { Logger, LogMessage } from 'pubnub'
2

3class MonitoringLogger implements Logger {
4  /**
5   * Process error-level messages
6   */
7  error(logMessage: LogMessage) {
8    const { timestamp, pubNubId, location, messageType } = logMessage;
9    
10    if (messageType === 'error') {
11      // TypeScript narrows type to ErrorLogMessage
12      // IDE provides autocomplete for PubNubError fields
13      monitoringService.reportError({
14        message: logMessage.message.message,
15        name: logMessage.message.name,
16        stack: logMessage.message.stack,
17        category: logMessage.message.status?.category,
18        operation: logMessage.message.status?.operation,
19        instanceId: pubNubId,
20        timestamp: timestamp.toISOString(),
21        location
22      });
23    } else if (messageType === 'network-request') {
24      // TypeScript narrows type to NetworkRequestLogMessage
25      // IDE provides autocomplete for canceled, failed, and details fields
26      if (logMessage.canceled || logMessage.failed) {
27        const url = `${logMessage.message.origin}${logMessage.message.path}`;
28        
29        monitoringService.reportNetworkFailure({
30          url: url,
31          method: logMessage.message.method,
32          reason: logMessage.details,
33          instanceId: pubNubId,
34          timestamp: timestamp.toISOString()
35        });
36      }
37    }
38  }
39  
40  /**
41   * Process warning messages
42   */
43  warn(logMessage: LogMessage) {
44    if (logMessage.messageType === 'text') {
45      // TypeScript narrows type to TextLogMessage
46      // IDE provides autocomplete for string methods on message
47      if (logMessage.message.includes('deprecated')) {
48        analyticsService.trackDeprecation({
49          warning: logMessage.message,
50          instanceId: logMessage.pubNubId,
51          timestamp: logMessage.timestamp.toISOString()
52        });
53      }
54    }
55  }
56  
57  /**
58   * Process debug messages for configuration tracking
59   */
60  debug(logMessage: LogMessage) {
61    if (logMessage.messageType === 'object') {
62      // TypeScript narrows type to ObjectLogMessage
63      // IDE provides autocomplete for details and ignoredKeys fields
64      if (logMessage.details?.includes('configuration')) {
65        analyticsService.trackConfigChange({
66          config: logMessage.message,
67          instanceId: logMessage.pubNubId,
68          timestamp: logMessage.timestamp.toISOString()
69        });
70      }
71    }
72  }
73  
74  // No-op implementations for other levels if not needed
75  trace() {}
76  info() {}
77}
78

79// Configure SDK with custom logger
80const pubnub = new PubNub({
81  subscribeKey: 'mySubscribeKey',
82  publishKey: 'myPublishKey',
83  userId: 'myUniqueUserId',
84  logLevel: PubNub.LogLevel.Debug,
85  loggers: [new MonitoringLogger()]
86});

show all 86 lines

Multiple custom loggers

You can add multiple custom loggers for different purposes:

1const pubnub = new PubNub({
2  subscribeKey: 'mySubscribeKey',
3  publishKey: 'myPublishKey',
4  userId: 'myUniqueUserId',
5  logLevel: PubNub.LogLevel.Debug,
6  loggers: [
7    new MonitoringLogger(),  // Send errors to monitoring service
8    new AnalyticsLogger(),   // Track usage patterns
9    new FileLogger()         // Write detailed logs to file (Node.js)
10  ]
11});

Log message types

The SDK generates five types of log messages. Each type has a corresponding TypeScript interface with specific fields.

Text messages (TextLogMessage)

Text messages provide simple text for general logging. The message field contains a string:

{
  timestamp: Date,
  pubNubId: 'pn-abc123',
  level: LogLevel.Info,
  minimumLevel: LogLevel.Debug,
  location: 'PubNub',
  messageType: 'text',
  message: 'PubNub client initialized successfully'
}

Object messages (ObjectLogMessage)

Object messages provide structured objects such as configuration or internal state. The message field contains an object, array, or other value. Optional details and ignoredKeys fields provide additional context:

{
  timestamp: Date,
  pubNubId: 'pn-abc123',
  level: LogLevel.Debug,
  minimumLevel: LogLevel.Debug,
  location: 'Configuration',
  messageType: 'object',
  message: { subscribeKey: 'sub-c-...', ssl: true, ... },
  details: 'Client configuration:'
}

Error messages (ErrorLogMessage)

Error messages provide exception and error information. The message field contains a PubNubError object with error details and optional status information:

{
  timestamp: Date,
  pubNubId: 'pn-abc123',
  level: LogLevel.Error,
  minimumLevel: LogLevel.Debug,
  location: 'PublishRequest',
  messageType: 'error',
  message: {
    name: 'PubNubError',
    message: 'Publish failed',
    stack: '...',
    status: { category: 'PNNetworkIssuesCategory', ... }
  }
}

Network request messages (NetworkRequestLogMessage)

Network request messages provide HTTP request details. The message field contains a TransportRequest object. Optional details, canceled, and failed fields provide additional context about the request status:

{
  timestamp: Date,
  pubNubId: 'pn-abc123',
  level: LogLevel.Debug,
  minimumLevel: LogLevel.Debug,
  location: 'PublishRequest',
  messageType: 'network-request',
  message: {
    method: 'POST',
    origin: 'https://ps.pndsn.com',
    path: '/publish/...',
    headers: { 'Content-Type': 'application/json' },
    body: '{"message":"Hello"}',
    queryParameters: { uuid: 'myUserId' }
  },
  canceled: false,
  failed: false
}

show all 18 lines

Network response messages (NetworkResponseLogMessage)

Network response messages provide HTTP response details. The message field contains a TransportResponse object with status code, headers, and response body:

{
  timestamp: Date,
  pubNubId: 'pn-abc123',
  level: LogLevel.Debug,
  minimumLevel: LogLevel.Debug,
  location: 'PublishRequest',
  messageType: 'network-response',
  message: {
    status: 200,
    url: 'https://ps.pndsn.com/publish/...',
    headers: { 'content-type': 'application/json' },
    body: '[1,"Sent","15234567890123456"]'
  }
}

Logging in different environments

Browser

The built-in console logger outputs to the browser JavaScript console:

1// Browser environment
2const pubnub = new PubNub({
3  subscribeKey: 'mySubscribeKey',
4  publishKey: 'myPublishKey',
5  userId: 'myUniqueUserId',
6  logLevel: PubNub.LogLevel.Debug
7});
8

9// Logs appear in browser console (F12 Developer Tools)

Node.js environment

The console logger outputs to the Node.js console:

1import PubNub from 'pubnub';
2

3const pubnub = new PubNub({
4  subscribeKey: 'mySubscribeKey',
5  publishKey: 'myPublishKey',
6  userId: 'myUniqueUserId',
7  logLevel: PubNub.LogLevel.Debug
8});
9

10// Logs appear in terminal or console

Node.js file logging

Implement a custom logger for Node.js file logging:

1import { Logger, LogLevel, LogMessage } from 'pubnub'
2import * as fs from 'fs';
3import path from 'path';
4

5class FileLogger {
6  constructor(private readonly logFilePath: string) {
7    this.stream = fs.createWriteStream(logFilePath, { flags: 'a' });
8  }
9  
10  log(logMessage: LogMessage) {
11    const level = LogLevel[logMessage.level];
12    const timestamp = logMessage.timestamp.toISOString();
13    const location = logMessage.location || 'Unknown';
14    const message = this.formatMessage(logMessage);
15    
16    this.stream.write(
17      `${timestamp} [${level.toUpperCase()}] ${location}: ${message}\n`
18    );
19  }
20  
21  formatMessage(logMessage: LogMessage) {
22    if (logMessage.messageType === 'text') {
23      return logMessage.message;
24    } else if (logMessage.messageType === 'object') {
25      return `${logMessage.details || ''}\n${JSON.stringify(logMessage.message, null, 2)}`;
26    } else if (logMessage.messageType === 'error') {
27      return `${logMessage.message.name}: ${logMessage.message.message}`;
28    }
29    // Handle other message types
30    return JSON.stringify(logMessage.message);
31  }
32  
33  trace(logMessage) { this.log('trace', logMessage); }
34  debug(logMessage) { this.log('debug', logMessage); }
35  info(logMessage) { this.log('info', logMessage); }
36  warn(logMessage) { this.log('warn', logMessage); }
37  error(logMessage) { this.log('error', logMessage); }
38}
39

40// Use FileLogger with PubNub
41const pubnub = new PubNub({
42  subscribeKey: 'mySubscribeKey',
43  publishKey: 'myPublishKey',
44  userId: 'myUniqueUserId',
45  logLevel: PubNub.LogLevel.Debug,
46  loggers: [new FileLogger('./pubnub.log')]
47});

show all 47 lines

The logVerbosity boolean parameter is deprecated. Use the logLevel parameter instead.

The following example shows the deprecated approach:

1// Deprecated approach
2const pubnub = new PubNub({
3  subscribeKey: 'mySubscribeKey',
4  publishKey: 'myPublishKey',
5  userId: 'myUniqueUserId',
6  logVerbosity: true  // Deprecated
7});

The following example shows the recommended approach:

1// Recommended approach
2const pubnub = new PubNub({
3  subscribeKey: 'mySubscribeKey',
4  publishKey: 'myPublishKey',
5  userId: 'myUniqueUserId',
6  logLevel: PubNub.LogLevel.Debug
7});

When you set logVerbosity to true, the SDK internally sets logLevel to LogLevel.Debug and emits a deprecation warning.

Migrate from logVerbosity

Best practices

Production environments

In production environments, use LogLevel.Warn or LogLevel.Error. These log levels minimize performance impact while capturing important issues.

Development environments

During development, use LogLevel.Debug or LogLevel.Trace. These log levels provide detailed information for debugging.

Custom logger performance

Implement custom loggers efficiently to avoid blocking the main thread. This consideration is especially important for network requests to external services.

Protect sensitive data

Use the ignoredKeys field in object log messages to filter sensitive data. Filter data such as secret keys or user credentials.

Implement log rotation

If you use file logging in Node.js, implement log rotation. Log rotation prevents unbounded log file growth.

Use structured logging

Take advantage of structured LogMessage objects. Structured logging enables searchable and queryable logs in your monitoring systems.

For more information about configuration parameters, refer to Configuration.