@lalamove/web-logger

A logger Javascript SDK to send client side errors or logs to custom logging services, based on Lalamove's log format.

Install

yarn add @lalamove/web-logger

Usage

Modules

Create a file to init the logger:

import Logger from '@lalamove/web-logger';

// Init config
// Will auto catch window.onerror to logging services after init, in `fatal` level
const log = new Logger({
    url: 'https://log.dev.lalamove.com', // Logging services URL, required
    key: 'API_KEY', // Credential key, required
    release: '2.0.0', // Product version, required
    locale: 'zh_HK', // required
    location: 'HK_HKG', // required
    environment: 'test', // Environment, required
    platform: 'webapp', // required
    appType: 'user' // required
});

export default log;

Then you can use it with import:

import log from './log';

// Custom log message
log.info('testing message');

React Error Boundaries

Read here for more details of Error Boundaries in React.

Create a component called ErrorBoundary:

import { Component } from 'react';
import log from './log';

export default class ErrorBoundary extends Component {
  static componentDidCatch(error, info) {
    const errorMessage = error.toString();
    log.error(errorMessage, null, info.componentStack);
  }

  render() {
    return this.props.children;
  }
}

Then you can use it as a regular component:

<ErrorBoundary>
  <BlahBlahBlah />
</ErrorBoundary>

Old-school way

Your application should get the build from node_modules/@lalamove/web-logger/index.iife.js (after yarn), and add it in the <head>.

<script src="node_modules/@lalamove/web-logger/index.iife.js"></script>
<script>
// Init config
// Will auto catch window.onerror to logging services after init
var log = new Logger({
    url: 'https://log.dev.lalamove.com', // Logging services URL, required
    key: 'API_KEY', // Credential key, required
    release: '2.0.0', // Product version, required
    locale: 'zh_HK', // required
    location: 'HK_HKG', // required
    environment: 'test', // Environment, required
    platform: 'webapp', // required
    appType: 'user' // required
});

// Custom log message
log.info('testing message');
</script>

API

changeLogLevels()

Updates the log levels to call or suppress. Accepts an array of strings. Levels that are not included will be suppressed and not logged. During initialization, all five levels are included (debug, info, warning, error, fatal).

const defaultLevels = ['debug', 'info', 'warning', 'error', 'fatal'];
log.changeLogLevels(['info', 'warning', 'error', 'fatal']); // will suppress log.debug()

changeUrl()

Change URL in config.

log.changeUrl('https://log.test.lalamove.com');

changeLocation()

Change location in config.

log.changeLocation('TW_TPE');

changeLocale()

Change locale in config.

log.changeLocale('zh_TW');

changeClientId()

Change client id in config.

log.changeClientId('20');

info()

Custom info log.

log.info('blahblahblah');

// Destructuring the object in second argument to context when sending data to logging services
log.info('blahblahblah', { customKey: 'message' });

debug()

Custom debug log.

log.debug('blahblahblah');

// Destructuring the object in second argument to context when sending data to logging services
log.debug('blahblahblah', { customKey: 'message' });

warning()

Custom warning log.

log.warning('blahblahblah');

// Destructuring the object in second argument to context when sending data to logging services
log.warning('blahblahblah', { customKey: 'message' });

error()

Custom error log.

log.error('blahblahblah');

// Destructuring the object in second argument to context when sending data to logging services
log.error('blahblahblah', { customKey: 'message' });

// Custom error stack trace string
log.error('blahblahblah', { customKey: 'message' }, 'Error: error message↵ at Home._this.render(https://blah.com/index.js:1:1)');

fatal()

Custom fatal log.

log.fatal('blahblahblah');

// Destructuring the object in second argument to context when sending data to logging services
log.fatal('blahblahblah', { customKey: 'message' });

// Custom error stack trace string
log.fatal('blahblahblah', { customKey: 'message' }, 'Error: error message↵ at Home._this.render(https://blah.com/index.js:1:1)');

Features

Log format

The output of the log will be posted to the logging services in the JSON format below:

{
    "message": "", // Describing what happened
    "src_file": "", // File path
    "src_line": "", // Line number
    "context": {
        "agent": "", // navigator.userAgent
        "environment": "",
        "locale": "",
        "location": "",
        "platform": "",
        "app_type": "",
        "release": "",
        "client_id": "",
        "url": "", // window.location.href
        // Destructuring custom context here
    },
    "level": "", // Log level: debug/info/warning/error/fatal
    "time": "", // ISO8601.nanoseconds+TZ
    "backtrace": "" // Error stack
}

Run Tests

yarn test

Browsers Support

We use window.fetch to send out network request to custom logging services. If you would like to support older browsers, you need to import github/fetch and taylorhakes/promise-polyfill.

Chrome
Firefox
Safari
Edge

License

MIT License

lalamove / web-logger Goto Github PK

web-logger's Introduction