Agent SDK
ISLog Configuration from JSON

Table of Contents


Overview

Loggers can be created and configured from a JSON configuration file or from a string in memory using a factory singleton provided in the ISLog module. The factory singleton is ISLogFactory.


Example Usage

To create a logger, all you need to do is call a single function on the ISLogFactory singleton. Once the logger is created, you would normally want to set it as the global logger via ISLog::setSingleton().

Typical configuration example:

#include "ISLog.h"
// create a logger from specified JSON configuration file
ISLogBase * pLogger = ISLogFactory::getInstance().createFromConfigFile("MyConfigurationFile.json");
if (pLogger != NULL)
{
// set the logger to be the global logger
ISLog::setSingleton(pLogger);
// write a sample log (optional!)
ISLOG_INFO("MyApplicationChannel", "We configured the logger successfully!");
}
else
{
// there was an error in the JSON configuration file. the error can be queried
// from the log factory
std::cout << "Error creating logger from JSON configuration file: "
<< ISLogFactory::getInstance().getError() << std::endl;
}

Vanilla 'C' example:

#include "ISLog.h"
// create a logger from specified JSON configuration file
int rc = ionic_log_setup_from_config_file("MyConfigurationFile.json", "MyRootLoggerPath");
if(rc == ISC_OK)
{
// write a sample log (optional!)
ISLOG_INFO("MyApplicationChannel", "We configured the logger successfully!");
}
else
{
// there was an error in the JSON configuration file. the error can be queried
// from the log factory
printf("Error creating logger from JSON configuration file: %d\r\n", rc);
}

Python example:

import ionicsdk
from inspect import currentframe, getframeinfo
# create a logger from specified JSON configuration file
ionicsdk.log.setup_from_config_file("MyConfigurationFile.json")
# write a sample log (optional!)
frameinfo = getframeinfo(currentframe().f_back)
ionicsdk.log.log(ionicsdk.log.SEV_ERROR, "MyApplicationChannel", frameinfo.lineno, frameinfo.filename, "We configured the logger successfully!")
else:
# there was an error in the JSON configuration file.
print("Error creating logger from JSON configuration file")

ObjectiveC example:

#import <IonicAgentSDK/IonicAgentSDK.h>
// create a logger from specified JSON configuration file
IonicLogBase * pLogger = [[IonicLogFactory getSingleton] createFromConfigFile:@"MyConfigurationFile.json" withBaseFileWriterPath:nil];
if (pLogger != NULL)
{
// set the logger to be the global logger
[IonicLog setSingleton:pLogger];
// write a sample log (optional!)
IonicLog_Info(@"MyApplicationChannel", @"We configured the logger successfully!");
}
else
{
// there was an error in the JSON configuration file. the error can be queried
// from the log factory
NSLog(@"Error creating logger from JSON configuration file: %@", [IonicLogFactory getSingleton].lastError);
}

C# example:

using IonicSecurity.SDK;
// create a logger from specified JSON configuration file
LogBase logger = LogFactory.GetInstance.CreateFromConfigFile("MyConfigurationFile.json")
if(logger != null)
{
Log.SetSingleton(logger);
// write a sample log (optional!)
Log.LogInfo("MyApplicationChannel", "We configured the logger successfully!")
}
else
{
// there was an error in the JSON configuration file. the error can be queried
// from the log factory
Console.WriteLine("Error creating logger from JSON configuration file: " + LogFactory.GetInstance.Error);
}


JSON Configuration Schema

The JSON schema that is expected by the logger factory is defined below.

Root Schema

Property Required Value Type Default Value Comment
sinks yes Array of Sinks (see Sink Schema)   Array of sink objects

Sink Schema

Property Required Value Type Default Value Comment
channels yes Array   Array of channel names (strings) that the sink should capture. To capture all channels, you can use "*".
Typically, each module in Ionic code has its own channel name. At the time of writing, the channel names are ("ISAgent", "ISAgentSDK", "ISAgentTool", "ISChunkCrypto", "ISCrypto", "ISFileCrypto", "ISFingerprint", "ISHTTP", "ISIpc", "ISKeyVault", "ISXml"). Also, the following platforms add their own channel ("C" -> "ISAgentSDKC", Python -> "ISPython", Java-JNI -> "ISJniUtils")
filter no Filter (see Filter Schema)   Specifies a filter for the sink. If none is set, no filter will be applied (ALL log messages allowed through)
writers yes Array of Writers (see Writer Schema)   Array of writer objects

Filter Schema

Property Required Value Type Default Value Comment
type yes String   Possible values are ("Severity")
level yes  String   

Only applicable for filters of type "Severity"

Possible values are ("TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL")

This represents the lowest level of log severity that the filter will accept.

Writer Schema

Property Required Value Type Default Value Comment
type  yes  String    Possible values are ("Console", "File", "RotatingFile"). On Windows only, "VisualStudioConsole" is also supported.
filter no  Filter (see Filter Schema)    Specifies a filter for the writer. If none is set, no filter will be applied (ALL log messages allowed through)
filePattern yes String  

Only applicable for writers of type "File" and "RotatingFile"

The filename, optionally including time pattern symbols as defined by strftime(). Most notable and useful are these symbols:

 

Y - Four digit year (e.g. 2014)

m - Two digit month with range 01 - 12 (e.g. 05)

d - Two digit day with range 01 - 31 (e.g. 05)

H - Two digit hour with range 00 - 11 (e.g. 05)

M - Two digit minute with range 00 - 59 (e.g. 05)

S - Two digit second 00 - 59 (e.g. 05)

 

Examples:

"ionic_global.log"

"ionic_global_%Y-%m-%d.log" 

"ionic_debug_%Y-%m-%d_%H-%M-%S.log"

rotationSchedule no String "DAILY"

Only applicable for writers of type "RotatingFile"

The time-based rotation schedule for the file, if any. Possible values are ("NONE", "DAILY", "HOURLY", "MINUTELY")

rotationSize no String "50mb"

Only applicable for writers of type "RotatingFile"

The size-based rotation threshold for the file. This value can be expressed in bytes, kilobytes, or megabytes. The special value of "-1" will disable size-based rotation.

Bytes - Byte count only (e.g. "1024", "51200", "8000")

Kilobytes - Use "kb" postfix (e.g. "20kb", "100kb")

Megabytes - Use "mb" postfix (e.g. "50mb", "100mb")

JSON Configuration Example (Simple)

This example will configure the SDK logger to write logs to a single file. It will log messages that are INFO level or above (this means INFO, WARN, ERROR, FATAL). The filename uses symbols supported by strftime() (e.g. Y, m) in order to put a timestamp into the filename when it is created.

{ "sinks": [ {
"channels": [ "*" ],
"filter": { "type": "Severity",
"level": "INFO" },
"writers": [
{ "type": "File",
"filePattern": "my_app_%Y-%m-%d_%H-%M-%S.log" }
]
} ] }

JSON Configuration Example (Advanced)

This example will configure the SDK logger to have two sinks.

The first sink accepts all channels ("*") but only writes messages at INFO level and above. This sink has two writers (Console and RotatingFile) in order to push its logs to standard output streams (stdout/stderr) as well as to a file on disk. Additionally, the file on disk will be rotated after reaching 100mb and/or after a day change has been detected.

The second sink accepts only a specific channel defined by the application developer ("SampleModuleName") and writes absolutely all log messages because the severity filter is set to TRACE. This sink is useful for troubleshooting or otherwise getting deep logging for a specific module. This sink has one log writer which writes to a file. The application developer can examine this file in order to very easily see exactly what is going on in the "SampleModuleName" module.

{ "sinks": [ {
"channels": [ "*" ],
"filter": { "type": "Severity",
"level": "INFO" },
"writers": [
{ "type": "Console" },
{ "type": "RotatingFile",
"filePattern": "my_app_%Y-%m-%d_%H-%M-%S.log",
"rotationSchedule": "DAILY",
"rotationSize": "100mb" }
]
},
{
"channels": [ "SampleModuleName" ],
"filter": { "type": "Severity",
"level": "TRACE" },
"writers": [
{ "type": "File",
"filePattern": "my_app_trace_%Y-%m-%d_%H-%M-%S.log" }
]
} ] }