Options
All
  • Public
  • Public/Protected
  • All
Menu

Namespace utils

Provides utility methods for working with Tracker instances or collectors.

// esm
import { trackers } from '@paychex/core';

// cjs
const { trackers } = require('@paychex/core');

// iife
const { trackers } = window['@paychex/core'];

// amd
require(['@paychex/core'], function({ trackers }) { ... });
define(['@paychex/core'], function({ trackers }) { ... });

Index

Functions

Functions

withNesting

  • Enables nested timings for the given Tracker instance.

    IMPORTANT: Enabling nested timings introduces edge cases and best practices you should understand before using. See the NestedTimingTracker documentation for more information.

    example
    import { tracker } from '~/tracking';

    const child = tracker.child();
    const logger = trackers.utils.withNesting(child);

    async function loadSecurity(start, clientId) {
        const [stop] = start('load user roles');
        await fakeDataCall(clientId); // pretend data call
        stop({ role: 'admin' });
    }

    async function loadFeatures(start, product) {
        const [stop] = start(`load ${product} features`);
        await fakeDataCall(product); // pretend data call
        stop({ features: [
            `${product}-feat-a`,
            `${product}-feat-b`
        ]});
    }

    async function loadProducts(start, clientId) {
        const [stop, nest] = start('load products');
        await fakeDataCall(clientId); // pretend data call
        await Promise.all([
            loadFeatures(nest, 'prod-a'),
            loadFeatures(nest, 'prod-b')
        ]);
        stop({ products: ['prod-a', 'prod-b'] });
    }

    async function loadClientData(clientId) {
        const [stop, nest] = logger.start('load client data');
        await loadProducts(nest, clientId);
        await loadSecurity(nest, clientId);
        stop({ clientId });
    }

    await loadClientData('client-123');

    timing tree:

     
    {
      "id": "dfc21f25-42da-439f-8fd4-23ab02b70668",
      "label": "load client data",
      "start": 1562872496161,
      "stop": 1562872496208,
      "duration": 47,
      "type": "timer",
      "count": 1,
      "data": {
        "children": [
          {
            "label": "load products",
            "count": 1,
            "start": 1562872496161,
            "stop": 1562872496192,
            "duration": 31,
            "data": {
              "children": [
                {
                  "label": "load prod-a features",
                  "count": 1,
                  "start": 1562872496176,
                  "stop": 1562872496191,
                  "duration": 15,
                  "data": {
                    "children": [],
                    "features": [
                      "prod-a-feat-a",
                      "prod-a-feat-b"
                    ]
                  }
                },
                {
                  "label": "load prod-b features",
                  "count": 1,
                  "start": 1562872496176,
                  "stop": 1562872496192,
                  "duration": 16,
                  "data": {
                    "children": [],
                    "features": [
                      "prod-b-feat-a",
                      "prod-b-feat-b"
                    ]
                  }
                }
              ],
              "products": [
                "prod-a",
                "prod-b"
              ]
            }
          },
          {
            "label": "load user roles",
            "count": 1,
            "start": 1562872496192,
            "stop": 1562872496208,
            "duration": 16,
            "data": {
              "children": [],
              "role": "admin"
            }
          }
        ],
        "clientId": "client-123"
      }
    }

    Parameters

    • tracker: Tracker

      The Tracker to wrap to enable nested timings.

    Returns NestedTimingTracker

    A Tracker instance that can create nested timings.

withReplacement

  • Wraps a collector so the TrackingInfo instance's key and value strings will be replaced according to the specified map. Used primarily to convert system codes into human-readable values before passing to a collector.

    example
    const map = new Map([
      [/^lang$/, 'language'],
      [/\ben\b/i, 'English'],
      [/\bes\b/i, 'Spanish'],
    ]);

    const collector = trackers.utils.withReplacement(console.log, map);
    export const tracker = trackers.create(collector);

    tracker.event('lang', { avail: ['es', 'en'], selected: 'en' });

    {
      "id": "09850c98-8d0e-4520-a61c-9401c750dec6",
      "type": "event",
      "label": "language",
      "start": 1611671260770,
      "stop": 1611671260770,
      "duration": 0,
      "count": 1,
      "data": {
        "avail": [ "Spanish", "English" ],
        "selected": "English"
      }
    }

    Parameters

    • collector: TrackingSubscriber

      The collector function to wrap. Will be invoked with a new TrackingInfo instance whose keys and values will be replaced according to the given map.

    • map: Map<RegExp, string>

      The mapping of values to replace. For example, /\ben\b/gi -> 'English' would change all instances of 'en' to 'English'. NOTE: Be sure to use \b to indicate word boundaries, ^ and $ to indicate the start and end of a string, /g to enable multiple replacements within a string, and /i to ignore case.

    • keysOnly: boolean = false

      Whether to replace only object keys; if not specified, object keys and values will be replaced.

    Returns TrackingSubscriber