Ping SDKs

Use and customize loggers

Applies to:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

About the default Ping SDK for Android logger

The Ping SDK for Android does all of its logging through a custom interface called FRLogger. The default implementation of this interface logs the messages through the native Android Log class. This displays messages from the SDK in real-time in the Logcat window in Android Studio.

The log severity levels defined in the Ping SDK for Android are as follows:

Log level Description

DEBUG

Show debug log messages intended only for development, as well as the message levels lower in this list; INFO, WARN, and ERROR.

In addition, all network activities of the SDK are included in the logs.

INFO

Show expected log messages for regular usage, as well as the message levels lower in this list, WARN, and ERROR.

WARN

Show possible issues that are not yet errors, as well as the messages of ERROR log level.

ERROR

Show issues that caused errors.

NONE

No log messages are shown.

The log levels are cumulative.

If you select a lower severity level, all messages logged at higher severity levels are also included. For example, if you select the DEBUG level, the log includes all events logged at the DEBUG, INFO, WARN, and ERROR levels.

By default, the log level of the Ping SDK for Android is set to Logger.Level.WARN.

Customize the Ping SDK for Android logger

The Ping SDK for Android allows developers to customize the default logger behavior:

  1. Create a class that implements the FRLogger interface:

    import androidx.annotation.Nullable;
import org.forgerock.android.auth.FRLogger;

public class MyCustomLogger implements FRLogger {
    @Override
    public void error(@Nullable String tag, @Nullable Throwable t, @Nullable String message, @Nullable Object... values) {
        /// Custom error message handling...
    }

    @Override
    public void error(@Nullable String tag, @Nullable String message, @Nullable Object... values) {
        /// Custom error message handling...
    }

    @Override
    public void warn(@Nullable String tag, @Nullable String message, @Nullable Object... values) {
        /// Custom warning message handling...
    }

    @Override
    public void warn(@Nullable String tag, @Nullable Throwable t, @Nullable String message, @Nullable Object... values) {
        /// Custom warning message handling...
    }

    @Override
    public void debug(@Nullable String tag, @Nullable String message, @Nullable Object... values) {
        /// Custom debug message handling...
    }

    @Override
    public void info(@Nullable String tag, @Nullable String message, @Nullable Object... values) {
        /// Custom info message handling...
    }

    @Override
    public void network(@Nullable String tag, @Nullable String message, @Nullable Object... values) {
        /// Custom network details handling...
    }

    @Override
    public boolean isNetworkEnabled() {
        return true; // include network call details in the logs
    }
}

  2. In your application, set the custom logger and desired log level:

    Logger.setCustomLogger(new MyCustomLogger()); // The default logger will no longer be active
Logger.set(Logger.Level.DEBUG);

  3. You can now use the Logger interface in your app.

    For example:

    String TAG = MainActivity.class.getSimpleName();
Logger.debug (TAG, "Happy logging!");

About the default Ping SDK for iOS logger

The Ping SDK for iOS does all of its logging through a custom protocol called FRLogger. The default implementation of the FRLogger protocol logs the messages through the native iOS FRConsoleLogger class. This displays messages from the SDK in real-time in the console window in Xcode.

Each log message has an associated log level that describes the type and the severity of the message. Log levels are helpful tool for tracking and analyzing events that take place in your app.

The log severity levels defined in the Ping SDK for iOS are as follows:

Log level Description

none

Prevent logging

verbose

Logs that are not important or can be ignored

info

Logs that maybe helpful or meaningful for debugging, or understanding the flow

network

Logs for network traffic, including request and response

warning

Logs that are a minor issue or an error that can be ignored

error

Logs that are a severe issue or a major error that impacts the SDK’s functionality or flow

all

Logs at all levels

The log levels are not cumulative. That is, you should explicitly specify all the log levels you want to record.

For example, if you select the debug level, the output only includes events logged at debug level.

To include other levels, you must specify an array of the required log levels.

By default, the log level of the Ping SDK for iOS is set to LogLevel.none.

Customize the Ping SDK for iOS logger

The Ping SDK for iOS lets developers customize the default logger behavior:

  1. Create a class that conforms to the FRLogger protocol:

    class MyCustomLogger: FRLogger {
    func logVerbose(timePrefix: String, logPrefix: String, message: String) {
        /// Custom verbose message handling...
    }

    func logInfo(timePrefix: String, logPrefix: String, message: String) {
        /// Custom info message handling...
    }

    func logNetwork(timePrefix: String, logPrefix: String, message: String) {
        /// Custom network message handling...
    }

    func logWarning(timePrefix: String, logPrefix: String, message: String) {
        /// Custom warning message handling...
    }

    func logError(timePrefix: String, logPrefix: String, message: String) {
        /// Custom error message handling...
    }
}

  2. In your application, set the custom logger and desired log level:

    FRLog.setCustomLogger(MyCustomLogger()) // The default logger will no longer be active
FRLog.setLogLevel([.all])

  3. You can now use the FRLog class in your app.

    For example:

    FRLog.v("Happy logging!")

About the default Ping SDK for JavaScript logger

The Ping SDK for JavaScript performs logging through the native console class. This displays messages from the SDK in real-time in the console window provided in many browsers.

The default logLevel is none, which prevents the Ping SDK for JavaScript from logging any messages to the console.

To enable the output of log messages from the Ping SDK for JavaScript, specify a logLevel value other than none.

For example, use the following code to specify the debug level:

Setting the log level in the Ping SDK for JavaScript configuration
Config.set({
  serverConfig: {
    baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am/',
    timeout: 5000,
  },
  logLevel: 'debug',
});

The log severity levels defined in the Ping SDK for JavaScript are as follows:

Log level Description

debug

Show debug log messages intended only for development, as well as the message levels lower in this list; info, warn, and error.

In addition, all network activities of the SDK are included in the logs.

info

Show expected log messages for regular usage, as well as the message levels lower in this list, warn, and error.

warn

Show possible issues that are not yet errors, as well as the messages of error log level.

error

Show issues that caused errors.

none

No log messages are shown. This is the default setting.

The log levels are cumulative. If you select a lower severity level, all messages logged at higher severity levels are also included.

For example, if you select the debug level, the output includes all events logged by the SDK at debug, info, warn, and error levels.

For more information on configuring the Ping SDK for JavaScript, refer to Ping SDK for JavaScript Properties

Customize the Ping SDK for JavaScript logger

The Ping SDK for JavaScript allows developers to customize the default logger behavior. For example, you might want to redirect the logs to an external service.

  1. Create a function that implements the LoggerFunctions interface.

    For example, the following code adds a prefix to each log message from the SDK and logs it to the console:

    const customLogger = {
  warn: (msg) => console.warn(`[FR SDK] ${msg}`),
  error: (msg) => console.error(`[FR SDK] ${msg}`),
  log: (msg) => console.log(`[FR SDK] ${msg}`),
  info: (msg) => console.info(`[FR SDK] ${msg}`),
};

    The signature of the interface defaults to the following:

    (…​msgs: unknown[]) ⇒ void

    You can pass your own type definition into the Generic if required. For example:

    // typescript generic example
type YourAsyncLoggerType = LoggerFunctions<
  (...msgs: unknown[]) => Promise<void>,
  (...msgs: unknown[]) => Promise<void>,
  (...msgs: unknown[]) => Promise<void>,
  (...msgs: unknown[]) => Promise<void>
  >

const customLoggerWithApiCall: YourAsyncLoggerType = {
  warn: (msg) => yourAsyncLogFunction.warn(`[FR SDK] ${msg}`),
  error: (msg) => yourAsyncLogFunction.error(`[FR SDK] ${msg}`),
  log: (msg) => yourAsyncLogFunction.log(`[FR SDK] ${msg}`),
  info: (msg) => yourAsyncLogFunction.info(`[FR SDK] ${msg}`),
};

  2. In the SDK configuration of your app, specify the custom logger and required log level:

    Config.set({
    serverConfig: {
        baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am/',
        timeout: '5000'
    },
    logLevel: 'error',
    logger: customLogger,
});

    The SDK redirects its logging output to your custom handler.

Copyright © 2010-2024 ForgeRock, all rights reserved.