Log messages API details

The AppConnect for iOS API provides properties and methods that allow an app to log messages at various severity levels to the device’s console or to files. For an overview of this feature, see Log messages.

The ACLogLevel enumeration

The ACLogLevel enumeration provides the possible log levels:

typedef enum {
    ACLOGLEVEL_ERROR   = 0, // Error messages
    ACLOGLEVEL_WARNING = 1, // Warning messages
    ACLOGLEVEL_STATUS  = 2, // Significant status messages such as app launch 
                            // and major user actions.
    ACLOGLEVEL_INFO    = 3, // Additional informational messages
    ACLOGLEVEL_VERBOSE = 4, // Verbose messages which may include sensitive information
    ACLOGLEVEL_DEBUG   = 5, // Debug messages which may include sensitive information
} ACLogLevel;

Log level descriptions and examples

The following table provides guidelines about when to use each log level:

 

Table 15.   Log level descriptions

Log level

Description

May contain sensitive data?

Examples of when to use

ACLOGLEVEL_ERROR

For events that block access to part or all of the app.

No

Uncaught exception

Corrupt or missing data

Network timeout

Digital signature validation error

Certificate error

Failed assertion

Exhausted retries

Error that is reported to the user

ACLOGLEVEL_WARNING

For events that are suspicious, but not quite failures like errors.

No

Caught exception that is ignored

Failed login due to bad user credentials

Unexpected data that is ignored

Network connection that is established just before timing out

Retrying

Attempted forward compatibility. For example, the app was developed with and tested against version 1 of the server, but the server reported version 2.

Feature disabled due to low battery

User attempted something that is not currently allowed or available

Warning that is reported to the user

ACLOGLEVEL_STATUS

For major changes in the state of the app

No

App launched

Version information

Successfully logged in

Successfully opened, saved or closed a user document

Successfully deleted sensitive data when authorization state changed to ACAUTHSTATE_RETIRED

Notification received from the server

Status that is reported to the user

ACLOGLEVEL_INFO

For minor changes in the state of the app

No

Changed views within the app

Heartbeat sent to server

App entered foreground or background, became active or inactive, and other UIApplicationDelegate app state changes

Interaction with device hardware, such as taking a photo

Changes to non-sensitive user preferences

ACLOGLEVEL_VERBOSE

For more extensive information, possibly including sensitive details

Yes

Server addresses of requests and resulting HTTP status codes

Sensitive details of messages of less verbose log levels, such as the name of a saved file

Device identifiers

ACLOGLEVEL_DEBUG

For the most information, possibly including sensitive details

Yes

Very precise user actions, such as touch events and keystrokes

URL request details

Memory and performance profiling information

Sensitive data examples

Include sensitive data only in messages logged at the verbose or debug levels. Examples of sensitive data are:

User data, including document contents, document names, contact lists, notes, bookmarks

Initial bytes of symmetric encryption keys, private encryption keys, passwords, certificates, signing identities, and cookies.

Only log initial bytes of these security-related values to ensure the values remain secure.

Complete URLs and POST data

Anything that may reveal the content of encrypted data, such as detailed error messages generated by parsing decrypted data

The logLevel property

+(ACLogLevel)logLevel;

The read-only logLevel class property on the AppConnect class contains an ACLogLevel value. The value reflects the current log level.

Use the following to get the logLevel value:

[AppConnect logLevel]

When your app calls the methods +logAtLevel:format:, +logAtLevel:format:args:, or +logAtLevel:message:, the AppConnect library logs a message only if the log level you pass to the method is less than or equal to the logLevel property’s current value.

Your app can use the logLevel property to determine what work to do before calling one of the logging methods. For example, if the app gathers and formats a lot of data when the log level is ACLOGLEVEL_DEBUG, it can skip that logic when the log level is less than ACLOGLEVEL_DEBUG.

Log level methods

Your app uses the following methods to receive log level updates and to log messages to the device’s console.

The -appConnect:logLevelChangedTo: callback method

You optionally implement this method to receive log level updates. The method is in the AppConnectDelegate protocol:

-(void) appConnect:(AppConnect *)appConnect logLevelChangedTo:
                                 (ACLogLevel)newLogLevel;

Implement this method only if your app logs messages using the methods +logAtLevel:format: or +logAtLevel:format:args:.

When a change has occurred to the log level on the Ivanti server, the AppConnect library:

1. Sets the logLevel property on the AppConnect object to the new ACLogLevel value.
2. Calls the -appConnect:logLevelChangedTo: method, which provides the new ACLogLevel value in its parameter.

Your app can use the notification to start or stop gathering additional data that the app uses in logging.

logAtLevel class methods

Use the following AppConnect class methods to log messages:

+(void)logAtLevel:(ACLogLevel)logLevel format:(NSString *)format, 
                                       ... NS_FORMAT_FUNCTION(2,3);
 
+(void)logAtLevel:(ACLogLevel)logLevel format:(NSString *)format 
                                       args:(va_list)args NS_FORMAT_FUNCTION(2,0);
 
+(void)logAtLevel:(ACLogLevel)logLevel message:(NSString *)message;

These class methods use the logLevel parameter to determine whether to log a message. If logLevel parameter is less than or equal to the logLevel property, the methods log a message.

The methods prepend the format or message string with one of the following strings depending on the logLevel parameter:

[Error]

[Warning]

[Status]

[Info]

[Verbose]

[Debug]

Then:

+logAtLevel:format: calls NSLog(), passing along the parameters.

+logAtLevel:format:args: calls NSLogv(), passing along the parameters.

+logAtLevel:message: calls NSLog(), passing along the parameter.

The following table describes the parameters of these methods:

 

Table 16.   Descriptions of log level methods’ parameters

Parameter

Description

logLevel

The ACLogLevel value for the message.

The AppConnect library logs the message only if the passed log level is less than or equal to the current value of the logLevel property.

format

A format string.

This parameter is an NSString, and can include format specifiers that NSString formatting methods support.

...

A comma-separated list of arguments to substitute into the format string in +logAtLevel:format:.

args

A va_list argument in +logAtLevel:format:args

Use +logAtLevel:format:args if you want to explicitly prepare a va_list argument that contains the list of arguments that you pass to the logging method. Preparing a va_list argument is useful when you want to wrap AppConnect logging functionality with your own function.

message

A string.

This parameter is an NSString, useful if you do not require format specifiers.

-logAtLevel:format:args: example

-(void)myDebugLogWithFormat:(NSString *)format, ... NS_FORMAT_FUNCTION(1,2) {
 
    va_list args;
    va_start(args, format);
    [AppConnect logAtLevel:ACLOGLEVEL_DEBUG format:format args:args];
    va_end(args);
}
 
-(void)someMethod {
 
    NSString *foo = @"FooValue";
    int bar = 4;
    [self myDebugLogWithFormat:@"Foo: %@ Bar: %i", foo, bar];
}

Log level methods and dual mode apps

A dual mode app can call the +logAtLevel:format:, +logAtLevel:format:args:, and +logAtLevel:message: methods and get the +(ACLogLevel)logLevel property even after calling -stop: on the AppConnect singleton object. When the AppConnect library is stopped, the log level is always ACLOGLEVEL_STATUS.

The notification method -appConnect:logLevelChangedTo: is not called when the AppConnect library is stopped.