feat: Add a default, plugin-specific logger to advanced plugins (#6693)

docs/guides/plugins.md

@@ -244,6 +244,22 @@ console.log(version);  // 1.0.1
 
 Note that the [plugin generator](https://github.com/videojs/generator-videojs-plugin) already takes care of adding a version number for you.
 
+#### Logging
+
+By default, each advanced plugin instance has its own `log` property much like `videojs` and `Player` instances do. The log messages will be prefixed with the player's ID and the plugin's name:
+
+```js
+player.examplePlugin().log('hello world!');
+```
+
+The above will log the following:
+
+    VIDEOJS: $PLAYER_ID: examplePlugin: hello world!
+
+The `log` function will also have all the methods/properties of the default `videojs.log`; such as, `error()`, `warn()`, `level()`, etc.
+
+> **NOTE:** This method is added in the constructor and it _will not_ override any predefined `log` property of the plugin's prototype.
+
 ### Advanced Example Advanced Plugin
 
 What follows is a complete ES6 advanced plugin that logs a custom message when the player's state changes between playing and pause. It uses all the described advanced features:

src/js/plugin.js

@@ -203,6 +203,10 @@ class Plugin {
 
     this.player = player;
 
+    if (!this.log) {
+      this.log = this.player.log.createLogger(this.name);
+    }
+
     // Make this object evented, but remove the added `trigger` method so we
     // use the prototype version instead.
     evented(this);

test/unit/plugin-advanced.test.js

@@ -71,6 +71,31 @@ QUnit.test('setup', function(assert) {
   );
 });
 
+QUnit.test('log is added by default', function(assert) {
+  const instance = this.player.mock();
+
+  assert.strictEqual(typeof instance.log, 'function', 'log is a function');
+  assert.strictEqual(typeof instance.log.debug, 'function', 'log.debug is a function');
+  assert.strictEqual(typeof instance.log.error, 'function', 'log.error is a function');
+  assert.strictEqual(typeof instance.log.history, 'function', 'log.history is a function');
+  assert.strictEqual(typeof instance.log.levels, 'object', 'log.levels is a object');
+  assert.strictEqual(typeof instance.log.warn, 'function', 'log.warn is a function');
+});
+
+QUnit.test('log will not clobber pre-existing log property', function(assert) {
+  class MockLogPlugin extends Plugin {
+    log() {}
+  }
+
+  MockLogPlugin.VERSION = '1.0.0';
+  Plugin.registerPlugin('mockLog', MockLogPlugin);
+
+  const instance = this.player.mockLog();
+
+  assert.strictEqual(typeof instance.log, 'function', 'log is a function');
+  assert.strictEqual(instance.log, MockLogPlugin.prototype.log, 'log was not overridden');
+});
+
 QUnit.test('all "pluginsetup" events', function(assert) {
   const setupSpy = sinon.spy();
   const events = [