Logging for Unity SDK

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

Logging architecture

The Unity 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 Unity logger (UnityPubNubLogger) automatically outputs to the Unity console
• Custom loggers allow you to add custom logger implementations via the SetLogger() method
• Multiple logger support enables simultaneous logging to different destinations
• Configuration via PNConfigAsset (Unity Editor) or programmatically in code

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

Log levels

The SDK uses five log levels. Each level controls the amount of detail captured. Each level also includes messages from all higher severity levels.

Level	Purpose
PubnubLogLevel.Trace	Internal operations: serialization, encryption, and detailed execution flow
PubnubLogLevel.Debug	User inputs, API (Application Programming Interface) parameters, HTTP (Hypertext Transfer Protocol) requests and responses, and configuration properties
PubnubLogLevel.Info	Significant events like successful initialization and configuration changes
PubnubLogLevel.Warn	Deprecation warnings, unusual conditions, and non-breaking validation warnings
PubnubLogLevel.Error	Errors, exceptions with stack traces, and failed operations

Additional levels:

• PubnubLogLevel.All enables all log levels (equivalent to Trace)
• PubnubLogLevel.None disables logging (default)

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

Enable logging

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.

The Unity SDK provides two primary ways to configure logging: using PNConfigAsset in the Unity Editor or configuring logging with code.

Use PNConfigAsset in the Unity Editor

The easiest way to configure logging is through the PNConfigAsset in the Unity Editor:

1. In your Unity project, create a PNConfigAsset by right-clicking in the Project window and selecting Create > PubNub > PubNub Config Asset
2. Select the created asset and in the Inspector panel:
   • Set LogLevel to an appropriate level like PubnubLogLevel.Debug to control detail level
   • Optionally enable LogToUnityConsole if supported by your configuration

You can now assign the config to a manager instance inheriting from PNManagerBehaviour and will receive PubNub logs of the level specified in LogLevel in the Unity console.

Configure logging with code

You can also configure logging directly in your code:

1

Custom loggers

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

IPubnubLogger interface

The IPubnubLogger interface defines five methods:

1public interface IPubnubLogger
2{
3    void Trace(string logMessage);
4    void Debug(string logMessage);
5    void Info(string logMessage);
6    void Warn(string logMessage);
7    void Error(string logMessage);
8}

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

Built-in Unity logger

UnityPubNubLogger is the default implementation of IPubnubLogger provided with the package. This logger outputs to the Unity console with appropriate Unity log methods (UnityEngine.Debug.Log, UnityEngine.Debug.LogWarning, UnityEngine.Debug.LogError).

Custom logger example

1

Multiple custom loggers

You can add multiple custom loggers for different purposes:

1

Each logger receives the same log entries based on the configured log level.

View logs

When logging is enabled, messages appear in the Unity console. The logs include:

• Timestamps for each log entry
• A unique instance identifier for the PubNub instance
• The log level (Trace, Debug, Info, Warn, or Error)
• The actual log message

Example log entry:

11/10/2025 10:30:45.123 PubNub-a1b2c3d4 Debug Publish request: channel=my-channel

For development builds, these logs are also saved to log files that can be accessed as described in the Unity documentation on log files.

Logged information

The Unity 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. 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

No secret keys in logs

Secret keys are never logged.

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

Response logs include:

• HTTP status code
• 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.

Logging best practices

Use these recommendations for effective logging in Unity applications.

Choose the right log level

Environment	Recommended Log Level
Production builds	Enable Error and Warn to catch issues without performance impact. Set LogLevel to PubnubLogLevel.Error or PubnubLogLevel.None.
Staging/Testing	Use Info to monitor operational events.
Development in Unity Editor	Enable Debug when actively developing or investigating issues.
Deep troubleshooting	Use Trace only when working with PubNub support on complex issues.

Protect sensitive data

Never enable Debug or Trace logging in production builds that handle sensitive information.

These levels may expose:

• API keys
• User identifiers
• Message content

Optimize performance in production

Disable logging or limit it to errors in production builds. This optimizes performance and reduces storage usage:

1

Use Unity Editor features

During development in the Unity Editor, use the console filters to focus on specific log types or search for specific instance identifiers.

Filter logs from multiple instances

When you create multiple PubNub instances, use the instance identifier to filter logs. This simplifies debugging in complex Unity applications.

Provide logs to support

When reporting issues to PubNub support, include complete logs:

1. Set the log level to PubnubLogLevel.Debug or PubnubLogLevel.Trace.
2. Reproduce the issue in the Unity Editor or a development build.
3. Collect logs from initialization through the problem occurrence.
4. Include the PubNub SDK version and Unity version.

For more information about configuration parameters, refer to Configuration.