Client SDK Version 1.8.1
Ionic Security client SDK for Python users
Log Configuration from JSON


Overview

Loggers can be created and configured from a JSON configuration file or from a string in memory using the 'ionicsdk.log.setup_' family of functions.


Example Python Usage

To create a configured logger, all you need to do is call a single function, ionicsdk.log.setup_from_config_file.

Typical Python configuration 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")


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, megabytes, gigabytes, or terabytes. 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")

Gigabytes - Use "gb" postfix (e.g. "5gb", "10gb")

Terabytes - Use "tb" postfix (e.g. "1tb", "5tb")

maxTotalSize no String "50tb"

Only applicable for writers of type "RotatingFile"

The size-based rotation threshold for the set of files defined by filePattern. This value can be expressed in bytes, kilobytes, megabytes, gigabytes, or terabytes. Whenever a new rotation file is created and the threshold is reached, the oldest files in the set are deleted until the set is under the threshold.

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")

Gigabytes - Use "gb" postfix (e.g. "5gb", "10gb")

Terabytes - Use "tb" postfix (e.g. "1tb", "5tb")

maxAge no String "yearly"

Only applicable for writers of type "RotatingFile"

The time-based rotation schedule for the set of files defined by filePattern. The value can be expressed minutes, hours, days, weeks, or using a ISO 8601 string. Whenever a new rotation file is created, any other files in the set exceeding this age are deleted.

Seconds - use no postfix (e.g. 59 seconds as "59")

Minutes - use "m" postfix (e.g. 300 minutes as "300m")

Hours - use "h" postfix (e.g. 24 hours as "24h")

Days - use "d" postfix (e.g. 5 days as "5d")

Weeks - use "w" postfix (e.g. 1 week as "1w")

ISO 8601 - Use the duration syntax (e.g. 10 days, 2:30 hours as "P10DT2H30M")


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": "50mb",
"maxTotalSize": "4gb",
"maxAge": "30d" }
]
},
{
"channels": [ "SampleModuleName" ],
"filter": { "type": "Severity",
"level": "TRACE" },
"writers": [
{ "type": "File",
"filePattern": "my_app_trace_%Y-%m-%d_%H-%M-%S.log" }
]
} ] }
ionicsdk.log.setup_from_config_file
def setup_from_config_file(configFile, baseFileWriterPath=None)
Definition: log.py:136
ionicsdk.log.log
def log(severity, channelName, lineNumber, fileName, message)
Definition: log.py:253
ionicsdk.log.is_setup
def is_setup()
Determines if the Ionic logger has been set up.
Definition: log.py:235