# @evo/gotcha-log

> Logger for [gotcha](https://gitlab.uaprom/gotcha/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

Latest version **1.6.1** (published 2026-11-19) · ISC license · 0 weekly downloads

## Install

```sh
npm install @evo/gotcha-log
pnpm add @evo/gotcha-log
yarn add @evo/gotcha-log
bun add @evo/gotcha-log
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.6.1 |
| Published | 2026-11-19 |
| First published | 2017-01-25 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 625.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | lequan, zemlanin, alexander, seedofjoy, 041616, docccdev, orhideous, tailhook, hunson.abadeer, mark_tven, amostovenko, sadkovoy, himiranov, evo-kazymyrov, stoyanovk, m.kindritskiy.smartweb |

## Links

- npm: https://www.npmjs.com/package/@evo/gotcha-log
- Repository: git@gitlab.uaprom:gotcha/gotcha-log
- npm.io page: https://npm.io/package/@evo/gotcha-log

## Recent versions

- 1.6.1 (latest) — 2026-11-19
- 1.6.0 — 2026-05-27
- 1.5.1 — 2021-04-28
- 1.4.0 — 2019-04-25
- 1.3.1 — 2018-01-22
- 1.3.0 — 2017-11-08
- 1.2.0 — 2017-11-08
- 1.1.15 — 2017-09-13
- 1.1.14 — 2017-09-12
- 1.1.13 — 2017-09-11
- 1.1.12 — 2017-09-11
- 1.1.10 — 2017-09-11
- 1.1.7 — 2017-09-11
- 1.1.5 — 2017-09-11
- 1.1.4 — 2017-09-11
- … 5 more at https://npm.io/package/@evo/gotcha-log/versions

## README

## gotcha-log
Logger for [gotcha](https://gitlab.uaprom/gotcha/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
```sh
npm install --save -E @evo/gotcha-log
```
## API
#### gotcha.log(msg, extra);
#### gotcha.error(msg, extra);
## Usage with global gotcha client
```javascript
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
```javascript
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](https://gitlab.uaprom/gotcha/gotcha/blob/master/src/client/README.md)

Example of the resulting message:

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

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

Will log:
```js
{
    message: "test msg",
    ctx: { user_name_str: "test", user_age_int: 1 },
    //...
}
```
> extra will be flattened as described [here](http://doc.logevo.gitlab.uaprom/structured.html#rules-how-extra-data-is-handled)

## txid
By default gotcha log will apply txid from global gotcha configuration.
But you can also specify `txid` per log in the extra argument:
```js
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](https://github.com/siimon/prom-client)

All metrics are uploaded to backend using [window.sendBeacon()](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/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](https://gitlab.evo.dev/gotcha/gotcha-server#write-prometheus-metrics-from-frontend)
### Usage:

Common usage:
```js
// 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:
```js
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:

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

And resume it by calling:
```js
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:
```js
import { immediatelyUploadMetrics } from '@evo/gotcha-log/dist/metrics';
immediatelyUploadMetrics()
```

---
_Source: https://npm.io/package/@evo/gotcha-log · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
