feat!: Improve logging and add logLevel (#427)

BREAKING CHANGE: The `logging` configuration option has now been replaced with `logLevel`. This allows for more fine-grain control over what should be logged as well as silencing logs altogether.

Author: offirgolan

docs/configuration.md

@@ -23,18 +23,18 @@ polly.configure({
 
 [config.js](https://raw.githubusercontent.com/Netflix/pollyjs/master/packages/@pollyjs/core/src/defaults/config.js ':include :type=code')
 
-## logging
+## logLevel
 
-_Type_: `Boolean`
-_Default_: `false`
+_Type_: `'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent'`
+_Default_: `'warn'`
 
-Logs requests and their responses to the console grouped by the recording name.
+Set the log level for the polly instance.
 
 **Example**
 
 ```js
 polly.configure({
-  logging: true
+  logLevel: 'info'
 });
 ```
 
@@ -110,8 +110,8 @@ polly.configure({
 
 ## expiryStrategy
 
-_Type_: `String`
-_Default_: `warn`
+_Type_: `'warn' | 'error' | 'record'`
+_Default_: `'warn'`
 
 The strategy for what should occur when Polly tries to use an expired recording in `replay` mode. Can be one of the following:
 
@@ -432,7 +432,7 @@ a GUID for the request.
 
   ```js
   // Retrieve our model
-  let model = await fetch('/models/1').then(res => res.json());
+  let model = await fetch('/models/1').then((res) => res.json());
 
   // Modify the model
   model.foo = 'bar';
@@ -441,7 +441,7 @@ a GUID for the request.
   await fetch('/models/1', { method: 'POST', body: JSON.stringify(model) });
 
   // Get our updated model
-  model = await fetch('/models/1').then(res => res.json());
+  model = await fetch('/models/1').then((res) => res.json());
 
   // Assert that our change persisted
   expect(model.foo).to.equal('bar');

docs/quick-start.md

@@ -108,8 +108,8 @@ import LocalStoragePersister from '@pollyjs/persister-local-storage';
 Polly.register(FetchAdapter);
 Polly.register(LocalStoragePersister);
 
-describe('Simple Example', function() {
-  it('fetches a post', async function() {
+describe('Simple Example', function () {
+  it('fetches a post', async function () {
     /*
       Create a new polly instance.
 
@@ -119,7 +119,7 @@ describe('Simple Example', function() {
     const polly = new Polly('Simple Example', {
       adapters: ['fetch'], // Hook into `fetch`
       persister: 'local-storage', // Read/write to/from local-storage
-      logging: true // Log requests to console
+      logLevel: 'info' // Log requests to console
     });
 
     const response = await fetch(
@@ -253,8 +253,8 @@ Lets take a look at how we can modify our previous test case to test against a
 post that does not exist.
 
 ```js
-describe('Simple Client-Side Server Example', function() {
-  it('fetches an unknown post', async function() {
+describe('Simple Client-Side Server Example', function () {
+  it('fetches an unknown post', async function () {
     /*
       Create a new polly instance.
 
@@ -264,7 +264,7 @@ describe('Simple Client-Side Server Example', function() {
     const polly = new Polly('Simple Client-Side Server Example', {
       adapters: ['fetch'], // Hook into `fetch`
       persister: 'local-storage', // Read/write to/from local-storage
-      logging: true // Log requests to console
+      logLevel: 'info' // Log requests to console
     });
     const { server } = polly;
 

docs/server/request.md

@@ -91,10 +91,10 @@ The recording the request should be recorded under.
 
 Get a header with a given name.
 
-| Param       | Type             | Description            |
-| ----------- | ---------------- | ---------------------- |
-| name        | `String`         | The name of the header |
-| **Returns** | `String | Array` | The header value       |
+| Param       | Type     | Description            |
+| ----------- | -------- | ---------------------- | ---------------- |
+| name        | `String` | The name of the header |
+| **Returns** | `String  | Array`                 | The header value |
 
 **Example**
 
@@ -107,11 +107,11 @@ req.getHeader('Content-Type'); // → application/json
 Set a header with a given name. If the value is `null` or `undefined`, the header will be
 removed.
 
-| Param       | Type                      | Description              |
-| ----------- | ------------------------- | ------------------------ |
-| name        | `String`                  | The name of the header   |
-| value       | `String | Array`          | The value for the header |
-| **Returns** | [Request](server/request) | The current request      |
+| Param       | Type                      | Description            |
+| ----------- | ------------------------- | ---------------------- | ------------------------ |
+| name        | `String`                  | The name of the header |
+| value       | `String                   | Array`                 | The value for the header |
+| **Returns** | [Request](server/request) | The current request    |
 
 **Example**
 
@@ -276,5 +276,5 @@ req.configure({ recordFailedRequests: true });
 
 req.configure({ timing: Timing.relative(3.0) });
 
-req.configure({ logging: true });
+req.configure({ logLevel: 'info' });
 ```

docs/server/route-handler.md

@@ -27,7 +27,7 @@ called in the order they were declared.
 ```js
 server
   .get('/session')
-  .on('request', req => {
+  .on('request', (req) => {
     req.headers['X-AUTH'] = '<ACCESS_TOKEN>';
     req.query.email = 'test@app.com';
   })
@@ -60,7 +60,7 @@ called in the order they were declared.
 ```js
 server
   .get('/session')
-  .once('request', req => {
+  .once('request', (req) => {
     req.headers['X-AUTH'] = '<ACCESS_TOKEN>';
     req.query.email = 'test@app.com';
   })
@@ -292,7 +292,7 @@ server.any('/session').configure({ recordFailedRequests: true });
 
 server.get('/users/:id').configure({ timing: Timing.relative(3.0) });
 
-server.get('/users/1').configure({ logging: true });
+server.get('/users/1').configure({ logLevel: 'info' });
 ```
 
 ### recordingName

packages/@pollyjs/adapter-fetch/src/index.js

@@ -32,7 +32,7 @@ export default class FetchAdapter extends Adapter {
     const { context } = this.options;
 
     if (isNode) {
-      console.warn(
+      this.polly.logger.log.warn(
         '[Polly] [adapter:fetch] Using the fetch adapter in Node has been deprecated. Please use the node-http adapter instead.'
       );
     }

packages/@pollyjs/adapter/src/index.js

@@ -47,13 +47,21 @@ export default class Adapter {
     if (!this.isConnected) {
       this.onConnect();
       this.isConnected = true;
+
+      this.polly.logger.log.debug(
+        `Connected to ${this.constructor.id} adapter.`
+      );
     }
   }
 
   disconnect() {
     if (this.isConnected) {
       this.onDisconnect();
       this.isConnected = false;
+
+      this.polly.logger.log.debug(
+        `Disconnected from ${this.constructor.id} adapter.`
+      );
     }
   }
 
@@ -149,7 +157,7 @@ export default class Adapter {
     pollyRequest.action = ACTIONS.RECORD;
 
     if ('navigator' in global && !navigator.onLine) {
-      console.warn(
+      pollyRequest.log.warn(
         '[Polly] Recording may fail because the browser is offline.\n' +
           `${stringifyRequest(pollyRequest)}`
       );
@@ -189,7 +197,7 @@ export default class Adapter {
             break;
           // log a warning and continue if expiryStrategy is "warn".
           case EXPIRY_STRATEGIES.WARN:
-            console.warn(`[Polly] ${message}`);
+            pollyRequest.log.warn(`[Polly] ${message}`);
             break;
           // throw an error if we encounter an unsupported expiryStrategy.
           default:

packages/@pollyjs/core/package.json

@@ -49,6 +49,7 @@
     "fast-json-stable-stringify": "^2.1.0",
     "is-absolute-url": "^3.0.3",
     "lodash-es": "^4.17.21",
+    "loglevel": "^1.8.0",
     "route-recognizer": "^0.3.4",
     "slugify": "^1.6.3"
   },

packages/@pollyjs/core/src/-private/logger.js

@@ -1,4 +1,5 @@
 import { ACTIONS } from '@pollyjs/utils';
+import logLevel from 'loglevel';
 
 const FORMATTED_ACTIONS = {
   [ACTIONS.RECORD]: 'Recorded',
@@ -10,72 +11,50 @@ const FORMATTED_ACTIONS = {
 export default class Logger {
   constructor(polly) {
     this.polly = polly;
-    this.groupName = null;
+    this.log = logLevel.getLogger(`@pollyjs/core:${this.polly.recordingName}`);
+
+    this.log.setLevel(polly.config.logLevel);
   }
 
   connect() {
     this._middleware = this.polly.server
       .any()
-      .on('error', (...args) => this.logError(...args))
-      .on('response', (...args) => this.logRequest(...args));
+      .on('error', (...args) => this.logRequestError(...args))
+      .on('request', (...args) => this.logRequest(...args))
+      .on('response', (...args) => this.logRequestResponse(...args));
   }
 
   disconnect() {
-    this.groupEnd();
     this._middleware.off('error');
     this._middleware.off('response');
   }
 
-  groupStart(groupName) {
-    // If the provided groupName is different, end the current group so a new one
-    // can be started.
-    if (this.groupName && this.groupName !== groupName) {
-      this.groupEnd();
-      this.groupName = null;
-    }
-
-    // Create a new console group for the provided groupName if one
-    // doesn't already exist.
-    if (!this.groupName) {
-      this.groupName = groupName;
-      console.group(this.groupName);
-    }
-  }
-
-  groupEnd() {
-    if (this.groupName) {
-      console.groupEnd();
-    }
-  }
-
   logRequest(request) {
-    if (request.config.logging) {
-      this.groupStart(request.recordingName);
+    const { log } = request;
 
-      console.groupCollapsed(
-        `${FORMATTED_ACTIONS[request.action]} ➞ ${request.method} ${
-          request.url
-        } ${request.response.statusCode} • ${request.responseTime}ms`
-      );
-      console.log('Request:', request);
-      console.log('Response:', request.response);
-      console.log('Identifiers:', request.identifiers);
-      console.groupEnd();
-    }
+    log.debug(`Request: ${request.method} ${request.url}`, { request });
   }
 
-  logError(request, error) {
-    this.groupStart(request.recordingName);
+  logRequestResponse(request) {
+    const { log } = request;
+    const debug = log.getLevel() <= log.levels.DEBUG;
 
-    console.group(`Errored ➞ ${request.method} ${request.url}`);
-    console.error(error);
-    console.log('Request:', request);
+    log.info(
+      `Response: ${FORMATTED_ACTIONS[request.action]} ➞ ${request.method} ${
+        request.url
+      } ${request.response.statusCode} • ${request.responseTime}ms`,
+      ...(debug ? [{ request, response: request.response }] : [])
+    );
+  }
 
-    if (request.didRespond) {
-      console.log('Response:', request.response);
-    }
+  logRequestError(request, error) {
+    const { log } = request;
+    const debug = log.getLevel() <= log.levels.DEBUG;
 
-    console.log('Identifiers:', request.identifiers);
-    console.groupEnd();
+    log.error(
+      `Errored ➞ ${request.method} ${request.url}`,
+      error,
+      ...(debug ? [{ request }] : [])
+    );
   }
 }

packages/@pollyjs/core/src/-private/request.js

@@ -2,6 +2,7 @@ import md5 from 'blueimp-md5';
 import stringify from 'fast-json-stable-stringify';
 import isAbsoluteUrl from 'is-absolute-url';
 import { URL, assert, timestamp } from '@pollyjs/utils';
+import logLevel from 'loglevel';
 
 import NormalizeRequest from '../utils/normalize-request';
 import parseUrl from '../utils/parse-url';
@@ -138,6 +139,20 @@ export default class PollyRequest extends HTTPBase {
     return this[ROUTE].shouldIntercept();
   }
 
+  get log() {
+    if (this.id) {
+      const log = logLevel.getLogger(
+        `@pollyjs/core:${this.recordingName}:${this.id}`
+      );
+
+      log.setLevel(this.config.logLevel);
+
+      return log;
+    } else {
+      return this[POLLY].logger.log;
+    }
+  }
+
   on(eventName, listener) {
     this[EVENT_EMITTER].on(eventName, listener);
 
@@ -275,5 +290,12 @@ export default class PollyRequest extends HTTPBase {
               (r) => r.id === this.id && r.recordingId === this.recordingId
             ).length
         : 0;
+
+    this.log.debug('Request Identified:', {
+      id: this.id,
+      order: this.order,
+      identifiers: this.identifiers,
+      request: this
+    });
   }
 }

packages/@pollyjs/core/src/defaults/config.js

@@ -1,4 +1,5 @@
 import { MODES, EXPIRY_STRATEGIES } from '@pollyjs/utils';
+import logLevel from 'loglevel';
 
 import Timing from '../utils/timing';
 
@@ -14,7 +15,7 @@ export default {
     disableSortingHarEntries: false
   },
 
-  logging: false,
+  logLevel: logLevel.levels.WARN,
   flushRequestsOnStop: false,
 
   recordIfMissing: true,