mirror of https://github.com/videojs/video.js.git synced 2024-12-12 11:15:04 +02:00

feat: createLogger for easier logging in individual modules (#5418 )

Create a new createLogger module for better debugging. Each logger has its own log level and its own createLogger that will nest logs underneath them. `player.log` is also included, which logs the player id as part of the log statement. The history API also got a filter method.

For example:
```js
var log = videojs.log.createLogger('foo');
log('hello');
// > VIDEOJS: foo: hello
```

2018-09-28 16:52:58 -04:00

6.2 KiB

Raw Blame History

Debugging

Logging

Logging

Video.js includes videojs.log, a lightweight wrapper around a subset of the console API. The available methods are videojs.log, videojs.log.debug, videojs.log.warn, and videojs.log.error.

API Overview

Most of these methods should be fairly self-explanatory, but for complete details, see the API docs.

Method	Alias Of	Matching Level(s)
`videojs.log()`	`console.log`	all, debug, info
`videojs.log.debug()`	`console.debug`	all, debug
`videojs.log.warn()`	`console.warn`	all, debug, info, warn
`videojs.log.error()`	`console.error`	all, debug, info, warn, error
`videojs.log.createLogger()`	n/a	n/a
`videojs.log.level()`	n/a	n/a
`videojs.log.history()`	n/a	n/a
`videojs.log.history.clear()`	n/a	n/a
`videojs.log.history.disable()`	n/a	n/a
`videojs.log.history.enable()`	n/a	n/a
`videojs.log.history.filter()`	n/a	n/a

For descriptions of these features, please refer to the sections below.

Log Safely

Unlike the console, it's safe to leave videojs.log calls in your code. They won't throw errors when the console doesn't exist.

Log Objects Usefully

Similar to the console, any number of mixed-type values can be passed to videojs.log methods:

videojs.log('this is a string', {butThis: 'is an object'});

Creating new Loggers

Sometimes, you want to make a new module or plugin and log messages with a label. Kind of how all these logs are prepended with VIDEOJS:. You can do that via the createLogger method. It takes a name and gives you back a log object like videojs.log. Here's an example:

const mylogger = videojs.log.createLogger('mylogger');

mylogger('hello world!');
// > VIDEOJS: mylogger: hello world!

// We can even chain it further
const anotherlogger = mylogger.createLogger('anotherlogger');

anotherlogger('well, hello there');
// > VIDEOJS: mylogger: anotherlogger: well, hello there

Log Levels

Unlike the console, videojs.log includes the concept of logging levels. These levels toggle logging methods on or off.

Levels are exposed through the videojs.log.level method. This method acts as both a getter and setter for the current logging level. With no arguments, it returns the current logging level:

videojs.log.level(); // "info"

By passing a string, the logging level can be changed to one of the available logging levels:

videojs.log.level('error'); // show only error messages and suppress others
videojs.log('foo'); // does nothing
videojs.log.warn('foo'); // does nothing
videojs.log.error('foo'); // logs "foo" as an error

Available Log Levels

info (default): only show log, log.warn, and log.error messages
all: enables all logging methods
error: only show log.error messages
off: disable all logging methods
warn: only show log.warn and log.error messages
debug: show log, log.debug, log.warn, and log.error messages

Debug Logging

Although the log levels attempt to match their window.console counterparts, window.console.debug is not available on all platforms. As such, it will use the closest comparable method, falling back from window.console.debug to window.console.info to window.console.log, and ultimately to nothing if none of those methods are available.

History

Note: In Video.js 5, videojs.log.history was an array. As of Video.js 6, it is a function which returns an array. This change was made to provide a richer, safer logging history API. You can also filter the history based on the name of the logger.

By default, the videojs.log module tracks a history of everything passed to it regardless of logging level:

videojs.log.history(); // an array of everything that's been logged up to now

This will work even when logging is set to off.

This can be useful, but it can also be a source of memory leaks. For example, logged objects will be retained in history even if references are removed everywhere else!

To avoid this problem, history can be disabled or enabled via method calls (using the disable and enable methods respectively). Disabling history is as easy as:

videojs.log.history.disable();

Finally, the history (if enabled) can be cleared at any time via:

videojs.log.history.clear();

History filtering

If you want to find all the history that was created by a particular logger, you can do so via history.filter(). Given a specific logger with name foo, you can pass foo to history.filter() and get all items logger by foo. Let me show you an example:

const mylogger = videojs.log.createLogger('mylogger');
const anotherlogger = mylogger.createLogger('anotherlogger');

videojs.log('hello');
mylogger('how are you');
anotherlogger('today');

videojs.log.history.filter('VIDEOJS');
// > [['VIDEOJS:', 'hello'], ['VIDEOJS: mylogger:', 'how are you'], ['VIDEOJS: mylogger: anotherlogger:', 'today']]
videojs.log.history.filter('mylogger');
// > [['VIDEOJS:    mylogger:', 'how are you'], ['VIDEOJS: mylogger: anotherlogger:', 'today']]
videojs.log.history.filter('anotherlogger');
// > [['VIDEOJS: mylogger: anotherlogger:', 'today']]

6.2 KiB Raw Blame History