Logging

Logging can be used for many different things: debugging, gathering statistics, monitoring and so on. We all know that a useful log message can save you hours of hard debugging. So logging is something a cloud app should be able to do. For logging you can simply use NSLog as you are used to. The main problem with NSLog is that you won't see the log messages once your cloud app is running on Objective-Cloud. But don't worry: This is what the simple and easy to use logging aspect of Objective-Cloud is there for. The logging aspect of Objective-Cloud consists of several parts that work together.

Tutorial

Step 1: Create a Database for your Cloud App

The log statements that are created will be stored in the database that belongs to your cloud app. So the first step is to create a database for your cloud app. If you don't know how to do that you should read "Using a Database". Basically you only have to create a database for your app and that's it. The logging aspect of Objective-Cloud will create the database table for the log statements for you.

Step 2: Activate Logging

Support for logging is disabled by default. You enable logging for your cloud app by overriding +persistsLogStatements in your OCFCloudApp subclass (which is called CloudApp by default). It looks like this:

@implementation CloudApp

+ (BOOL)persistsLogStatements {
      return YES;
}
    
@end

Step 3: Use OCFLog(…)

Now that logging is enabled you can use OCFLog(…). OCFLog(…) is a C function with the following prototype:

void OCFLog(NSString *tag, NSString *message, ...);

So you would use OCFLog like this:

OCFLog(@"DEBUG", @"This will be logged.");

By the way: OCFLog(…) is always calling NSLog(…) under the hood (before it tries to save the log statement to your database). This means that you can use OCFLog(…) when working locally on your Mac: You will simply see the log statements in Console.app or in Xcode.

OCFLog: tag

tag is a string that allows you to categorize your log statements. If you don't plan to use categories simply pass @"". There are no predefined categories. You could use the following categories to categorize your log statements depending on severity: ERROR, DEBUG, INFO. Tags only exist to improve the search-ability and readability of the log statements. Tags have to be short: The maximum length of a tag is 128.

OCFLog: message

message is a format string that forms the actual log message that you want to log. Individual log messages cannot exceed 5120 bytes.

Step 4: View log messages

Once you have created a few log messages you can view them by using Objective-Cloud Connect. First you have to go to the applications view which lists all of your cloud applications. Then click on "Show Logs".

You should then see the last 500 log statements (most recently created log statements come first). Each log statement has three parts:

The tag (the blue label in the upper left corner)
The date of the log message (right to the tag)
The actual log message (the text in the box)

Tipps and Tricks

Access Logs via any PostgreSQL Client

Log statements are stored in a table called OCFLogStatement. You can use any PostgreSQL client to access the database of your cloud app and then query this table. You don't have to view your logs with Objective-Cloud Connect all the time.

Management of the Log Table

At the moment you are responsible to manage the contents of the log table. Every time you call OCFLog a row will be inserted in the log table. At some point you may want to clean up the log table or backup it to a safe place. There is no automatic mechanism that cleans up the table.

Use OCFLog(…) only for important Stuff

At some point OCFLog(…) has to write to your database. This can be a costly operation. Think carefully about what to log. You should not log every aspect of every incoming request. It is a good idea to log only the most critical things and go from there.

Objective-C in the Cloud