Chronicler: API-based Logging

Chronicler: API-based Logging

If there is any programming topic near and dear to my heart, I would have to say logging would probably be one of the first. It is easy to over look when you are working on UI, but if you want to monitor your application near real-time to quickly react when problems arise it can be your best friend. Those hard to diagnose user errors are a lot easier to track down when you can see it happening.

You can use writeLog to handle logging on all the major engines. The main problem I have with this is, depending on my environment it can be a real pain to find the log files. Are your instances clustered for high availability? Good luck unless you have a way to access the log files. Using Chronicler to handle logging gives me one place to check for log files. I can event see events happening almost real-time at https://chronicler.kisdigital.com.

Viewing the Datas

Below is a simple function that uses cfhttp to make a call out to the API.

component{
  function log (required struct criteria) {
   cfhttp(url = "https://api.kisdigital.com/chron/log", method = "POST", charset = "utf-8"){
    cfhttpparam(type = "header", name = "Content-Type", value = "application/json");
    cfhttpparam(type = "body", value = serializeJSON({
     "appid": "0450c7d0-cba8-4a6a-9fe3bad81410ffc1",
     "type": criteria.keyExists("type") ? criteria.type : "information",
     "log": criteria.keyExists("log") ? criteria.log : "default",
     "message": criteria.keyExists("message") ? criteria.message : "No message."
    }));
  }
}

The only requirement to create a log item is a valid appid, a message, and an log name.  Applications may be created using the API once you have created your user account.

Creating an Account

The first step to get started is creating a user account. This is accomplished by using the createAccount Postman endpoint and filling out your email address and a password.

If you are successful your new user id will be in the response. This id is used for filtering logs and is required for each request. Do not lose it as there is not an easy way to retrieve it at the moment. These credentials can also be used at https://chronicler.kisdigital.com to load the viewer.

Your default application will also be created with your account.

Listing your Applications

Applications are logical ways to group your logs. The appid in the log request determines which app is being logged to, each app can have many log names. The log attribute is synonymous with the file attribute in writeLog.

You can get a listing of your currently defined applications by calling the application info endpoint.

https://api.kisdigital.com/chron/info/o/bfcb8aa1-ef9a-4070-b9a4e6068afb4e05/apps

Listing my applications

Your first application was created for you when your account was created.

If you would like to create a new application you just have to POST to the apps endpoint and pass a name. If the call is successful the new id will be returned in the response.

Creating an App

Creating an Entry

Now we know our appid lets log an item using the log request in the Postman collection.

Logging something

Filtering the Data

Filtering data

Logging the message is only the first part, next comes filtering the data which can be done by calling the filter endpoint with the owner with your userid which will return all of your log entries.

It is possible to filter for a specific day by passing the dt parameter with the date.

It is possible to filter for a specific app by passing the a parameter with the appid.
https://api.kisdigital.com/chron/filter/o/bfcb8aa1-ef9a-4070-b9a4e6068afb4e05/a/0450c7d0-cba8-4a6a-9fe3bad81410ffc1

You can also filter for a specific log with the l parameter.
https://api.kisdigital.com/chron/filter/o/bfcb8aa1-ef9a-4070-b9a4e6068afb4e05/l/other

All options may be combined.

Any filter called with a DELETE verb will purge the records.

Here is a Postman collection as well: https://www.getpostman.com/collections/48373a0b0ab69732a87c

Things are a little rough all the way around. I plan on cleaning up the viewer as soon as I can.