left-hook-analytics-client

Client package for programmatically leveraging the left-hook-analytics api

Usage

To use this package, you must first obtain an Application API Key from the Left Hook Analytics administrator.

Create an instance of the left hook analytics client using your Application Api Key

const AnalyticsClient = require("left-hook-analytics-client")

let analytics = new AnalyticsClient({
   applicationApiKey : "my-application-api-key"
})

Assuming you have provided a valid Application API Key, the client will now fetch your service-level keys. This should occur rather quickly after instantiation, so you are unlikely to leverage client methods before this information has been retrieved. However, service-level api calls will await service-level key retrieval before making any requests. If you have provided an invalid Application API Key, attempting to leverage service methods will throw an error.

Once application details have been fetched, log service methods will be exposed.

Error Logging

To report an error to the Left Hook Analytics API, use the logError method available on the AnalyticsClient instance. Every log method expects a manifest object. The shape of a manifest varies for each log type. An error manifest must have the string properties attempt and origin, and may optionally include a stack and meta property, either of which may be a string, number, object, or array.

async function mightFail ( myParam ){
   let someParam = myParam
   try {
      // ...
      let result = await someAsyncOperation(someParam)
      // ...
      return result
   } catch(err){
      console.error(err)
      analytics.logError({
         origin : "myFile.js",
         attempt: "someAsyncOperation",
         stack : err,
         meta : {
            someParam : myParam
         }
      })
   }
}

The logError method has no return value, and is treated in code as a synchronous function. Assuming the Application API Key you have provided is valid and the origin and attempt properties have been given literal values, it is guaranteed that your log has been recorded. When an error log is recorded, the application name and the application id are associated with that log, so that you may retrieve aggregate statistics and application-related details at a later time.