# [idb-logger](https://github.com/theajack/logger)
π A high-performance, high-capacity, and highly scalable web-side logging system based on WebWorker and indexedDB
**[Online use](https://shiyix.cn/jsbox?github=theajack.logger) | [δΈζ](https://github.com/theajack/logger/blob/master/README.cn.md) | [Changelog](https://github.com/theajack/logger/blob/master/scripts/version.md) | [issue feedback](https://github.com/theajack/logger/issues/new) | [Gitee](https://gitee.com/theajack/logger)**
## 0. Introduction
idb-logger is committed to helping web developers access a high-performance logging system conveniently and efficiently. Relying on webworker and indexedDB technologies, web applications can store large-capacity logs in the browser in a way that hardly affects the user experience, and Report it to the server at the right time, or download it by the user.
### 0.1 Features
1. Support WebWorker + indexedDB to store logs
2. Three log storage modes can be selected, and when not supported, the supported mode will be automatically selected down
3. Support no storage mode, only use idb-logger as a log generation tool
4. Support to define the maximum number of storage logs, the oldest records will be automatically deleted
5. Support download log
6. Support query log, support multiple query modes
7. Support custom basic data
8. Support custom reporting based on onReport callback
## 1. Quick use
### 1.0 install
#### 1.0.1 npm install
```
npm i idb-logger
```
```js
import Logger from 'idb-logger';
```
#### 1.0.2 cdn
```html
```
### 1.1 Quick use
```js
const logger = new Logger();
logger.log('an ordinary log');
logger.error('an error log', 'additional information', {type: 'additional information'});
logger.log('start').then(({discard, add})=>{
// add is log detail
// If maxRecords is reached, discard is a discarded log, otherwise null
})
logger.download(); // download log
```
### 1.2. API introduction
ts declaration:
```ts
declare class Logger {
static version: string;
private_store;
id: string;
storeType: TLogStoreType;
constructor({ id, useConsole, storeType, maxRecords, baseInfo, onReport, onDiscard, }?: ILoggerOption);
injectBaseInfo(baseInfo?: IBaseInfoOption & IJson): Promise;
log(...args: any[]): Promise;
error(...args: any[]): Promise;
warn(...args: any[]): Promise;
info(...args: any[]): Promise;
private _logCommon;
close(): Promise;
destory(): Promise;
clear(): Promise;
count(): Promise;
delete(logid: string): Promise;
refreshTraceId(): Promise;
refreshDurationStart(): Promise;
download({ name, filter }?: {
name?: string;
filter?: TFilterOption;
keys?: string[];
}): Promise;
get(logid: string): Promise;
getAll(): Promise;
filter(filter?: TFilterOption): Promise;
}
```
complete logdata
```ts
interface ILogDBData {
uid: string; // user id will be stored in storage
clientid: string; // client id will be stored in storage
traceid: string; // This access id can be refreshed by refreshTraceId
network: string; // network status
url: string; // current url
ua: string; // browser ua
msg: string; // message type, if the first parameter of log is a string, take this value
payload?: any; // other parameters of log
type: TLogType; // log info warn error
duration: number; // The time when the page enters the current log, you can refresh the timing at seven o'clock through refreshDurationStart
time: string; // time string
timestamp: number; // timestamp
logid: string; // log unique id
}
```
#### 1.2.1 Constructor
```ts
new Logger({
id, // Specify the database name Default value: default
useConsole, // whether to print to the console default true
storeType, // storage mode, default idb, support idb storage temp none
maxRecords, // maximum number of stored records default 10000
baseInfo, // inject custom base information
onReport, // Triggered when the log is generated, can be used to customize the report data
onDiscard, // Triggered when maxRecords is reached, discarded data
onError, // error listener
});
```
declaration
```ts
interface ILoggerOption extends Partial {
id?: string;
useConsole?: boolean;
storeType?: TLogStoreType;
maxRecords?: number;
baseInfo?: IBaseInfo;
onReport?: (data: ILogDBData) => void;
onDiscard?: (data: ILogDBData) => void;
onError?: (err: ILogError) => void;
}
```
1. storeType
idb means using indexedDB to store logs, storage means using localStorage to store logs, temp means using js variables to store data (non-persistent), none means not storing data (only using idb-logger as a log generation tool)
The default value is idb. When a certain storage type is not supported by the browser, the next mode will be automatically selected backward.
2. maxRecords
In order to reduce client performance consumption, you can specify a maximum storage amount. When this amount is exceeded, the logger will automatically delete the oldest record and trigger the onDiscard callback
3. baseInfo
Accepts a json, which is used to inject the basic information of the log. When the name is consistent with the default baseInfo, the default baseInfo will be overwritten
Default baseInfo `clientid, uid, traceid, network, url, ua`
#### 1.2.2 Logging
There are four methods on the logger object: log, error, warn, info
The usage method is similar to support the incoming of any amount and any type of data
parameter rules
1. When the first parameter is a string or a number, the parameter is used as the msg field of the log, and all the following parameters are combined into an array as the payload attribute
2. When the first parameter is json and there is only one parameter, all the properties in the json will be overwritten to the properties of the log
3. When the first parameter is not a number or a string, the default value __def__ will be used as msg, and all parameters will be combined into an array as the payload attribute
```ts
await logger.log('start'); // Return Promise<{discard, add}> add is the added log data. The call method conforms to rule 1
await logger.info({
msg: 'start', // write message
time: 'xxxx', // Override log properties
your_custom: 'xxxx', // custom properties
}); // This call method conforms to rule 2
await logger.warn({}, [], '', 1); // This call method conforms to rule 3
await logger.error('error', {}, [], '', 1); // This call method conforms to rule 1
```
#### 1.2.3 Query
```ts
await logger.filter(filter); // return Promise
```
filter supports three modes
1. Filter
Support to pass in a function `(data: ILogDBData) => boolean`, the callback function is the log data, return true or false to indicate whether the data hits
Note: In indexedDB mode, since the function will be passed to the worker for execution, it is required that other methods or features not supported in the worker cannot be called in the function.
```ts
await logger.filter(item=>{
return item.msg.includes('xxx') && item.type === 'log';
})
```
2. AND (incoming json)
Pass in a json, each attribute will be used and String together, supports regular expressions
```ts
await logger.filter({
msg: /xxx/i,
type: 'log',
})
```
3. OR (pass in json array)
Pass in a json array, each element in the array is connected with or logic, and the and logic is used between the attributes within the element, which is consistent with 2
```ts
await logger.filter([{
msg: /xxx/i,
}, {
type: 'log',
}])
```
The above statement means that msg in the log contains xxx or type is equal to log
#### 1.2.4 Download
Download logs stored in indexedDB
```ts
await logger.download({
name, // optional name of the downloaded file defaults to timestamp
filter, // optional same as filter in 1.2.3
keys, // optional specifies additional properties to download
});
```
#### 1.2.5 Other APIs
##### 1.2.5.1 getAll
get all logs
```ts
await logger.getAll();
```
##### 1.2.5.1 get
Get a log based on the log id
```ts
await logger.getAll(logid);
```
##### 1.2.5.1 count
Get the number of logs
```ts
await logger.count();
```
##### 1.2.5.1 delete
Delete a log by log id
```ts
await logger.delete(logid);
```
##### 1.2.5.1 injectBaseInfo
Inject log basic information
```ts
await logger.injectBaseInfo({
network: 'wifi',
phone: 'xxxx',
});
```
##### 1.2.5.1 refreshTraceId
Refresh the traceid, generally used for reconnection, etc., considered to be the second visit scenario
Also refreshDurationStart
```ts
await logger.refreshTraceId();
```
##### 1.2.5.1 refreshDurationStart
Refresh the timing starting point, generally used in scenarios that need to re-count the time
```ts
await logger.refreshTraceId();
```
##### 1.2.5.1 close
close the database
```ts
await logger.close();
```
##### 1.2.5.1 clear
close and clear the database
```ts
await logger.clear();
```
##### 1.2.5.1 destory
Close, empty and delete the database
```ts
await logger.destory();
```