npm.io
1.6.1 • Published 7h ago

@evo/gotcha-log

Licence
ISC
Version
1.6.1
Deps
0
Size
625 kB
Vulns
0
Weekly
0

gotcha-log

Logger for gotcha. Will use global gotcha config (if gotcha client is already present in page than window._GOTCHA_IS_HERE will be true ). Or if there is no gotcha on page, it will not work until you will set the config with initGotchaLogger function.

Installation

npm install --save -E @evo/gotcha-log

API

gotcha.log(msg, extra);
gotcha.error(msg, extra);

Usage with global gotcha client

import * as gotcha from '@evo/gotcha-log';
// or import { log } from '@evo/gotcha-log';

gotcha.log('test msg')
// or log('test msg')
gotcha.error('error msg')

Usage as a standalone logger

import * as gotcha from '@evo/gotcha-log';

gotcha.initGotchaLogger(<GOTCHA_SITE>, <GOTCHA_HOST>, <TXID>)

gotcha.log('test');
gotcha.error('test');

See details about GOTCHA_SITE, GOTCHA_HOST here

Example of the resulting message:

{
    "message":"test msg",
    "filename":"default",
    "screenWidth":1855,
    "screenHeight":1056,
    "userLanguage":"US",
    "currentUrl":"http://localhost:8000/",
    "site":"evodoc-dev",
    "type":"log"
}

logging extra

const extra = { user: { name: 'test', age: 1 } };
gotcha.log('test msg', extra);

Will log:

{
    message: "test msg",
    ctx: { user_name_str: "test", user_age_int: 1 },
    //...
}

extra will be flattened as described here

txid

By default gotcha log will apply txid from global gotcha configuration. But you can also specify txid per log in the extra argument:

gotcha.log('test msg', { txid: '<some id>' });

@evo/gotcha-log/dist/metrics

There was a need to transfer the numerical data of event metrics to the backend from the frontend to save them in the Prometheus. For this purpose a sub-module of metrics was created.

The design of the module has been inspired by the package prom-client

All metrics are uploaded to backend using window.sendBeacon(). If browser does not support this API, it will fallbacks to XMLHttpRequest()

NOTE:

Before add metrics to your project, you must add your project config to gotcha-server

Usage:

Common usage:

// at start of your application, initialize metrics module
import {initGotchaMetrics, metric} from '@evo/gotcha-log/dist/metrics';

initGotchaMetrics({
    project: <project-id>, // do not forget, to add your project to gotcha-server config
    host: <gotcha-backend-host>
});

// create metric: metric(<name>, [<value>], [<labels>])
metric(
    'pageview', // metric name
     1, // value
    {page:'koshyk'} // labels
)

Also you can create metric instance manually:

import { Counter } from '@evo/gotcha-log/dist/metrics';

const reduxActionsErrorsCounter=new Counter({
    name: 'redux-errors'
});
reduxActionsErrorsCounter.inc(123, {action: 'createOrder', version: '1.2.3'})

// or

const incCounter=reduxActionsErrorsCounter.getStandaloneInc( {action: 'createOrder', version: '1.2.3'})
incCounter(3) // which is equivalent to reduxActionsErrorsCounter.inc(3, {action: 'createOrder', version: '1.2.3'})

All metrics will upload to backend automatically each 5s. You can stop uploading by calling:

import { stopUploadByInterval } from '@evo/gotcha-log/dist/metrics';
stopUploadByInterval()

And resume it by calling:

import { startUploadByInterval } from '@evo/gotcha-log/dist/metrics';
startUploadByInterval()

NOTE:

startUploadByInterval and stopUploadByInterval also add / remove visibilitychange and pagehide listeners, which upload the last metrics to backend when the page is hidden or the user leaves it. beforeunload is not used: it fires unreliably on mobile and can make the page ineligible for bfcache. The visibilitychange listener is attached to window, so it runs after document listeners (e.g. web-vitals reporting final CLS/INP) and uploads their metrics too.

Send metrics to backend immediately:

import { immediatelyUploadMetrics } from '@evo/gotcha-log/dist/metrics';
immediatelyUploadMetrics()