UNPKG

7.58 kBMarkdownView Raw
1# advanced-logger
2
3[![Feature branch build](https://github.com/AlexeyPopovUA/advanced-logger/actions/workflows/feature-branch-build.yml/badge.svg)](https://github.com/AlexeyPopovUA/advanced-logger/actions/workflows/feature-branch-build.yml)
4[![npm version](https://badge.fury.io/js/advanced-logger.svg)](https://badge.fury.io/js/advanced-logger)
5[![install size](https://packagephobia.now.sh/badge?p=advanced-logger)](https://packagephobia.now.sh/result?p=advanced-logger)
6[![](https://data.jsdelivr.com/v1/package/npm/advanced-logger/badge)](https://www.jsdelivr.com/package/npm/advanced-logger)
7
8
9[![Quality checks](https://github.com/AlexeyPopovUA/advanced-logger/actions/workflows/quality-checks.yml/badge.svg)](https://github.com/AlexeyPopovUA/advanced-logger/actions/workflows/quality-checks.yml)
10[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
11[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=bugs)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
12[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
13[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=coverage)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
14[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
15[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
16[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
17[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
18[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
19[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
20[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=AlexeyPopovUA_advanced-logger&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=AlexeyPopovUA_advanced-logger)
21
22
23[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
24
25
26[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FAlexeyPopovUA%2Fadvanced-logger.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2FAlexeyPopovUA%2Fadvanced-logger?ref=badge_shield)
27
28## What is it?
29
30It is an extendable isomorphic log sending library written in TypeScript for javascript application in nodejs and browsers.
31
32It can be extended with custom strategy ("when to send logs") and service ("where to send logs").
33
34It does not restrict you with conventions, for example, existence of "logSeverity", "ErrorId" or "message" fields in log.
35
36It supports any format of logs via custom serializer.
37
38## Features
39
40* :scream_cat: It works in browsers and nodejs
41* :articulated_lorry: It is able to send single logs and bundles of them to an external logger
42* It supports different log sending strategies:
43 1. :alarm_clock: interval (for example, every 10 seconds)
44 2. :loudspeaker: on request (only when you ask)
45 3. :alarm_clock: :heavy_plus_sign: :loudspeaker: mixed ("interval" + "on request") (will be done soon)
46 4. :steam_locomotive: :railway_car: :railway_car: :railway_car: on bundle size (for example, sends bundles of 100 logs)
47 5. :toilet: instant (received 1 log -> sent 1 log)
48* :busts_in_silhouette: It is able to group duplicated logs in certain time interval (for rapid fire of the same logs)
49* :octopus: It is not afraid of circular links in log objects
50* :building_construction: It supports custom format for logs (custom serializer)
51* :dart: It supports different remote logger endpoints (SumoLogic, Loggly and Elasticsearch). Who is the next? ᕙ(ಠ.ಠ)ᕗ
52
53## Runtime environment support :running_woman:
54
55Builds are generated as ES2015 bundles for nodejs and browser environments.
56
57:robot: NodeJS - tested on latest lts
58
59:globe_with_meridians: Browser - all latest browsers, that support ES2015 JS.
60
61## [Documentation](https://advancedlogger.com "Advanced Logger's Homepage")
62
63Complete documentation and examples can be found here:
64
65**[Advanced Logger's Homepage](https://advancedlogger.com "Advanced Logger's Homepage")**
66
67**[NPM package link](https://www.npmjs.com/package/advanced-logger "NPM package link")**
68
69### Simplest usage
70
71Now, the boring part :nerd_face:
72
73#### Installation
74
75Axios is a required peer dependency. It means that axios is not bundled into logger package, but required to be installed.
76
77As a dependency in a npm project:
78
79```shell
80npm i --save advanced-logger axios
81```
82
83```javascript
84import {AdvancedLogger, service, strategy} from 'advanced-logger';
85// or
86const {AdvancedLogger, service, strategy} = require('advanced-logger');
87```
88
89As script tags with CDN:
90
91```html
92<!--minified-->
93<script src="https://cdn.jsdelivr.net/npm/axios@latest/dist/axios.min.js"></script>
94<script src="https://cdn.jsdelivr.net/npm/advanced-logger@latest/dist/browser/advanced-logger.browser.min.js"></script>
95<!--dev version-->
96<script src="https://cdn.jsdelivr.net/npm/axios@latest/dist/axios.js"></script>
97<script src="https://cdn.jsdelivr.net/npm/advanced-logger@latest/dist/browser-debug/advanced-logger.browser.js"></script>
98```
99
100#### Configuration
101
102Lets initiate a logger that sends all logs instantly to Sumologic service.
103
104```javascript
105import {AdvancedLogger, service, strategy} from 'advanced-logger';
106
107const defaultLogConfig = {
108 UserAgent: window.userAgent,
109 Channel: "my-company",
110 BuildVersion: 123,
111 Platform: "browser",
112 Severity: "DEBUG",
113 Data: "",
114 Timestamp: "",
115 Message: "",
116 Category: ""
117};
118
119const serviceConfig = {
120 url: "https://www.google.nl",
121 sourceName: "advancedLoggerTest",
122 host: "advanced-logger",
123 sourceCategory: "MY/SUMO/namespace",
124 method: "POST"
125};
126
127const config = {serviceConfig, defaultLogConfig};
128
129const logger = new AdvancedLogger({
130 service: new service.SumologicService(config),
131 strategy: new strategy.InstantStrategy()
132});
133
134logger.log({test: "instant log u1"}); // sends log message :rocket:
135logger.log({test: "instant log u2"}); // sends log message :rocket:
136logger.log({test: "instant log u3"}); // sends log message :rocket:
137```
138
139### Upgrading between breaking changes
140
141#### 2.x to 3.x
142
143* Install axios to your project or just keep using it if it is already installed
144* Logger is compiled to ES2015 JS target. If your project requires support of old browsers and nodejs, please,
145make sure that you transpile and add necessary pollyfills to the build