Log

Publishing

Ensure you've properly updated the version number in ./overlay/balloon/package.json according to Semantic Versioning standards!

Take note of the new version number and run this command:

git tag vXXXXXX where "XXXXXX" is the version number.

Then run git push origin --tags.

Original Documentation

APPLOG and ERRORLOG
6/7/2019
===================

-- Problem --

The Log.ts methods that write to the console are only useful for development work.  The logRemote() method only sends a message to the backend and does not write anything to the console (which might be helpful).  The logError() method calls logRemote() but it doesn't add anything to assist in identifying or resolving the problem.


-- Remote Logging Strategy --

There are 2 distinct reasons for writing application messages to the backend:

• Usage Tracking - Startup, log-in and various other events are valuable indicators of application use.  This helps inform system admin decisions, provides reporting capabilities and may be a contractual obligation.

• Error Logging - Application errors can be caused by faulty logic, corrupt data, unusual client environments or unanticipated user actions.  Capturing and recording as much information as possible about them is the best way to proactively troubleshoot and resolve issues.


-- Client-Side --

The Log object should be a generic utility that can be used with any application.  It should provide a method for writing DEVELOPMENT messages to the console, a method for sending TRACKING messages to the backend and a method for sending ERROR reports to the backend.

Tags are sort, all-cap identifiers used to categorize all 3 types of messaging.  These should be implemented as a separate enumeration class to ensure consistency and to support autocompiling.  Since projects will have different messaging needs, the LogEnum object will need to be application-specific.

DEVELOPMENT - The use of "DEBUG", "INFO" and "WARN" as tags would enable a single method to support all console variants.  These messages are not written to the console in production code unless App.debug = true.

TRACKING - These messages are posted to the backend and written to the stats.applog table.  Their tags relate to the specific kind of event and new ones need to be added to the enumeration as needed.  (The only tag currently used in the WMI is "LOC-SEARCH" -- but there will be more.)  The tracking method should also call console.info() with a standard prefix like " ||| TRACK ||| " + message.

ERROR - These messages are posted to the backend and written to the stats.errorlog table.  Their tags relate to the general category of error which can also be extended as needed.  Generally, tags like "APP", "HTTP", "LINK", "OL" (OpenLayers), "GS" (GeoServer) and "PHP" (backend call) might be appropriate.  Most importantly, the detail parameter should include enough information to identify the context in which the error occurred.  Essentially, if there is a potential problem warranting a try-catch block, what would someone need to know to fix it?

The error method need not always be called from inside a try-catch block.  It can and should be used whenever an else clause is needed to intercept some inexplicable and unforgivable condition.  The error method should also call console.error() with a standard prefix like " ||| ERROR ||| " + err-desc + detail.


-- Server-Side --

There are 2 separate endpoints for posting messages to the backend.  POST is used rather than GET because errors have a lot of parameters and either message type may include lengthy, sensitive or binary values.  By convention, these endpoints will be always be named stats-applog.php (TRACKING) and stats-errorlog.php (ERRORS).

The parameters for stats-applog.php are:

       pk = project key (or any other unique application, project or instance identifier) REQUIRED
     user = current user token (if logged in)
      tag = the application-defined identifier for sorting, analysis and reports (all caps)
      msg = additional information as needed

The parameters for calling stats-errlog.php are:

       pk = project key (or any other unique application, project or instance identifier) REQUIRED
     user = current user token (if logged in)
      tag = the application-defined identifier for sorting, analysis and reports (all caps)
   detail = the applicate state, variable values and any other relevant contextual information
   source = code location that threw or caught the error (as file:line or class:method)
  err-num = standard error number
 err-desc = standard error description
    stack = the stack trace (if available)


-- Testing --

These 2 test versions of the endpoints are now working:
  https://www.no-harm.us/test/stats-applog.php
  https://www.no-harm.us/test/stats-errorlog.php

A notifiation email is sent to [email protected] whenever stats-errorlog.php is called.  This is for testing purposes and the "to" addess can be changed.  Normally, notifications will only be enabled in the production system.

Both endpoints have been successfully tested from:
  https://www.no-harm.us/sandbox/log-test.html

Since the projKey parameter is required and it must be a valid WMI key, it should be one of these strings:

  XqfU5yJnE8n5bHM4
  Bkjj3SyQ4i8dN99g
  cYb45s6e2n41c51w
  fTk92yg3wA47eGjK


-- Reference --

https://www.sohamkamani.com/blog/2017/08/21/enums-in-javascript/
https://stackoverflow.com/questions/21876461/difference-between-console-log-and-console-debug
https://code.tutsplus.com/tutorials/working-with-date-and-time-in-php--cms-31768