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:
|
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:
|
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.