Set Up Client Logging

You can hook into the logging API if you want to know what's happening in your client app.

Log Levels

The logging API outputs messages with one of the following possible severity levels. The severity level indicates the importance of the message. The levels are, from most severe to least severe:

Fatal: A fatal app error. The app needs to shut down and no recovery actions are possible.
Error: A normal app error such as timeouts or bad user input. When this happens, the app can still run.
Warn: An abnormal event occurred without negatively affecting the app. This logging level indicates unexpected values, deprecations, or abnormal app states.
Info: A trace message that describes what's going on in the SDK.
Debug: A diagnostic message that's similar to the Info message. This logging level outputs detailed parameters or "spammy" messages.
None: This suppresses all log messages.

Note

About the code examples on this page:

For Xamarin Android, Xamarin iOS, and Xamarin macOS, use the C# code.
For Java, use the Android code.
For macOS, use the iOS code.

Output Log Message

You can output a log message by invoking a log-level method on the Log class. The methods use the same name as the severity level of the logs they output.

The following code example shows how to output a Debug and a Fatal log message.

FM.LiveSwitch.Log.Debug("This is a DEBUG message.");
FM.LiveSwitch.Log.Fatal("This is a FATAL message.");

fm.liveswitch.Log.debug("This is a DEBUG message.");
fm.liveswitch.Log.fatal("This is a FATAL message.");

FMLiveSwitchLog.debug(message: "This is a DEBUG message.")
FMLiveSwitchLog.fatal(message: "This is a FATAL message.")

fm.liveswitch.Log.debug("This is a DEBUG message.");
fm.liveswitch.Log.fatal("This is a FATAL message.");

FM.LiveSwitch.Log.Debug("This is a DEBUG message.");
FM.LiveSwitch.Log.Fatal("This is a FATAL message.");

Set Log Levels

You can set the level of logs you want to display. By default, it displays the Info, Warn, Error, and Fatal messages. In production, you probably don't want to display any message; in development, you might want to display the diagnostic messages. To accomplish this, set the DefaultLogLevel property of the Log class.

// for development
FM.LiveSwitch.Log.DefaultLogLevel = FM.LiveSwitch.LogLevel.Debug;

// for production
FM.LiveSwitch.Log.DefaultLogLevel = FM.LiveSwitch.LogLevel.None;
// or
FM.LiveSwitch.Log.DefaultLogLevel = FM.LiveSwitch.LogLevel.Error;

// for development
fm.liveswitch.Log.setDefaultLogLevel(fm.liveswitch.LogLevel.Debug);

// for production
fm.liveswitch.Log.setDefaultLogLevel(fm.liveswitch.LogLevel.None);
// or
fm.liveswitch.Log.setDefaultLogLevel(fm.liveswitch.LogLevel.Error);

// for development
FMLiveSwitchLog.setDefaultLogLevel(FMLiveSwitchLogLevelDebug)

// for production
FMLiveSwitchLog.setDefaultLogLevel(FMLiveSwitchLogLevelNone)
// or
FMLiveSwitchLog.setDefaultLogLevel(FMLiveSwitchLogLevelError)

// for development
fm.liveswitch.Log.setDefaultLogLevel(fm.liveswitch.LogLevel.Debug);

// for production
fm.liveswitch.Log.setDefaultLogLevel(fm.liveswitch.LogLevel.None);
// or
fm.liveswitch.Log.setDefaultLogLevel(fm.liveswitch.LogLevel.Error);

// for development
FM.LiveSwitch.Log.DefaultLogLevel = FM.LiveSwitch.LogLevel.Debug;

// for production
FM.LiveSwitch.Log.DefaultLogLevel = FM.LiveSwitch.LogLevel.None;
// or
FM.LiveSwitch.Log.DefaultLogLevel = FM.LiveSwitch.LogLevel.Error;

Register a Provider

By default, nothing happens when a log message is generated. To specify what should happen when outputting a log message, register a log provider instance with the Log class. Each provider has a specific method of outputting a log message. The default provider outputs messages to the log console but you can create providers that output messages to files or to a cloud logging provider.

Each provider has an associated severity level. These severity levels are used in combination with the global severity level to determine whether or not a log message should be output. This allows you to specify that some log providers with an expensive logging mechanism such as a cloud log provider should only log error messages, while log providers with a fast logging mechanism can output everything, including debug messages.

To add a provider, invoke the RegisterProvider method of the Log class.

The following code example uses the default log provider that outputs log messages to the console. When instantiating the provider, you can specify the provider's log level.

FM.LiveSwitch.Log.DefaultLogLevel = FM.LiveSwitch.LogLevel.Debug;
FM.LiveSwitch.Log.RegisterProvider(new FM.LiveSwitch.ConsoleLogProvider());

fm.liveswitch.Log.setDefaultLogLevel(fm.liveswitch.LogLevel.Debug);
fm.liveswitch.Log.registerProvider(new fm.liveswitch.android.LogProvider());

FMLiveSwitchLog.setDefaultLogLevel(FMLiveSwitchLogLevel.debug)
FMLiveSwitchLog.registerProvider(provider: FMLiveSwitchNSLogProvider(logLevel: FMLiveSwitchLogLevel.debug))

fm.liveswitch.Log.setDefaultLogLevel(fm.liveswitch.LogLevel.Debug);
fm.liveswitch.Log.registerProvider(new fm.liveswitch.ConsoleLogProvider());

private Text txtLog;
txtLog = GetComponent<Text>();
.
.
.
FM.LiveSwitch.Unity.DebugLogProvider debugConsole = new FM.LiveSwitch.Unity.DebugLogProvider(LogLevel.Debug);
FM.LiveSwitch.Unity.TextLogProvider onScreenLog = new FM.LiveSwitch.Unity.TextLogProvider(txtLog, LogLevel.Info);
.
.
.
FM.LiveSwitch.Log.RegisterProvider(debugConsole);
FM.LiveSwitch.Log.RegisterProvider(onScreenLog);

Remove a Provider

Generally, you set up log providers on app start up and you probably won't change them during execution. However, you can remove a provider if required. You need to retain a reference to the specific provider and pass this reference into the RemoveProvider method of the Log instance.

FM.LiveSwitch.Log.RemoveProvider(consoleLogProvider);

fm.liveswitch.Log.removeProvider(consoleLogProvider);

FMLiveSwitchLog.removeProvider(provider:nsLogProvider)

fm.liveswitch.Log.removeProvider(consoleLogProvider);

FM.LiveSwitch.Log.RemoveProvider(consoleLogProvider);

Implement Your Own Log Provider

LiveSwitch provides some basic LogProvider implementations but you might want to create application-specific implementations. To do so, extend the LogProvider class and implement the DoLog method with the following parameters:

timestamp: Date and time when the message was logged.
level: Severity level of the message.
message: Log message.
tag: A value based on which component generated the log message.
ex: Exception instance if the log message is associated with an exception.

If you don't need to perform any custom formatting on the message, we recommend to use the inherited GenerateLogLine method. This returns a string in the same format as the other LiveSwitch log providers. You can then output the message in the way you want. The following example shows a re-implementation of the console log provider.

Note

The LogProvider base class defaults to the Info log level. To support a different logging level in your custom log provider, pass the logging level through in the constructor.

public class ConsoleLogProvider : FM.LiveSwitch.LogProvider
{
    protected override void DoLog(LogEvent logEvent)
    {
        Console.WriteLine(GenerateLogLine(logEvent));
    }
}

public class ConsoleLogProvider extends fm.liveswitch.LogProvider {
    @Override
    protected void doLog(java.util.Date timestamp, fm.liveswitch.LogLevel level, String tag, String message, Exception ex) {
        System.out.println(generateLogLine(timestamp, level, tag, message, ex));
    }
}

public class ConsoleLogProvider : FMLiveSwitchLogProvider {
    override func doLog(timestamp:NSDate, level:FMLiveSwitchLogLevel, tag:NSString, message:NSString, ex:NSException) {
        print(generateLogLine(timestamp: timestamp, level: level, tag: tag, message: message, ex: ex))
    }
}

function ConsoleLogProvider() {
    fm.liveswitch.LogProvider.call(this);
}
  
ConsoleLogProvider.prototype.doLog = function(timestamp, level, tag, message, ex) {
    console.log(this.generateLogLine(timestamp, level, tag, message, ex));
}

public class consoleLog : FM.LiveSwitch.LogProvider
{
    protected override void DoLog(LogEvent logEvent)
    {
        Debug.Log("FM.LiveSwitch.LogProvider consoleLog: " + GenerateLogLine(logEvent));
    }
}

To use other logging frameworks, create a custom log provider to send LiveSwitch log messages to the logging framework. You can then let the framework handle message output.

Improve Log Aggregation

Log aggregation functionality reports the first instance of any log event within the window immediately. If another log event occurs which matches exactly with the one that has already been reported within the window, it gets buffered instead of being reported. Any subsequent events which also match within the same window won't be logged, instead they get added to a counter. At the end of the window, these events are reported in a single, aggregate log event along with the number of times that event occurred. The threshold option can be used to filter events which occur less than the threshold value; though the first instance of any event within a window will always be reported.

To efficiently log information, following additional parameters are configured in the Deployment Configuration entity:

Deployments:{index}:LogAggregation:Enabled (boolean)
Deployments:{index}:LogAggregation:Window (integer, milliseconds)
Deployments:{index}:LogAggregation:Threshold (integer)

These parameters already have their default values set. Enabled is set to false by default so no aggregation occurs. If Enabled is set to true, then aggregation occurs using defaults of 5000 milliseconds for the window and a threshold of 2 unless these two deployment options are configured as well.