Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface Tracker

Provides methods for logging events, errors, and performance.

Best Practices

  • Combine tracker.child() with tracker.context() to set cross-cutting information specific to your application and to each high-level business process or transaction you have to track. You can create any number of child trackers that inherit settings from their ancestors.
example
// app/index.js

export const tracker = trackers.create();

tracker.context({
  app: 'my-app'
});
example
// app/components/search.js

// import the root tracker with 'app' defined
import { tracker } from '../index';
import { fetch, createRequest } from '../data';

// create a child tracker for use
// only within this file
const fileTracker = tracker.child();

// all calls to child tracker methods
// will include this 'component', along
// with 'app' set by the root tracker
fileTracker.context({
  component: 'my-app-search'
});

const operation = {
  base: 'my-app',
  path: '/search'
};

export async function getSearchResults(query) {

  // create a child tracker for use only within
  // the lifetime of this function (ensures each
  // call to this function gets its own context)
  const methodTracker = fileTracker.child();

  // set data specific to this invocation
  methodTracker.context({ query });

  // the following event will include 'query'
  // and 'component' from ancestor trackers
  // as well as 'app' from the root tracker
  methodTracker.event('search');

  const params = { query };
  const stop = methodTracker.start('perform search');
  const request = createRequest(operation, params);
  const response = await fetch(request).catch(errors.rethrow(params));
  const results = response.data;

  // the following timer will include 'query',
  // 'component', 'app', and -- only on this
  // timer -- a 'status' value
  stop({ status: results.length ? 'Found' : 'Not Found' });

  return models.utils.withOrdering(models.collection(...results), ['priority'], ['desc']);
}

Hierarchy

  • BaseTracker
    • Tracker

Index

Methods

Methods

child

  • Creates a child Tracker instance.

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

    // this tracker will inherit any context data
    // set in landing's tracker while also mixing
    // in any contextual data of its own
    export const myAppTracker = tracker.child();

    myAppTracker.context({ app: 'my-app' });
    myAppTracker.event('app tracker created');

    Returns Tracker

    A new Tracker instance that will notify the same root subscriber of TrackingInfo entries, mixing in ancestor contextual data as needed.

context

  • context(data: Record<string, any>): void

  • Sets contextual data to be mixed into each TrackingInfo created by this Tracker or any child Trackers.

    example
    import { get } from 'lodash';
    import { store, tracker } from '~/tracking';

    store.subscribe(() => {
      const state = store.getState();
      const app = get(state, 'routes.stage');
      const drawer = get(state, 'routes.drawer');
      tracker.context({ app, drawer });
    });

    Parameters

    • data: Record<string, any>

      The data to merge into any TrackingInfo instances created by this (or child) Tracker methods.

    Returns void

error

  • error(err: Error): void

  • Logs an Error.

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

    export function doSomething(param) {
      somePromiseMethod()
        .catch(errors.rethrow({ param }))
        .catch(tracker.error);
    }

    Parameters

    • err: Error

      The Error instance to log.

    Returns void

event

  • event(label: string, data?: Record<string, any>): void

  • Logs an event. Events usually represent important points in an application's lifecycle or user-initiated actions such as button clicks.

    NOTE: This method also creates a browser performance mark with the given message name.

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

    window.addEventListener('click', (e) => {
      if (e.target.matches('button, a')) {
        // could grab additional contextual data
        // by looking at ancestor elements' attributes
        const type = e.target.tagName.toLowerCase();
        tracker.event('click', {
          tags: ['ui', type],
          label: e.target.innerText
        });
      }
    });

    Parameters

    • label: string

      The name of the event to log.

    • Optional data: Record<string, any>

      Optional information to associate with this TrackingInfo.

    Returns void

start

  • start(label: string): TimerStopFunction

  • Starts a timer to measure performance.

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

    export async function doSomething(param) {
      const stop = tracker.start('doSomething');
      const results = await somePromiseMethod();
      stop({ count: results.length, param });
      return results;
    }

    Parameters

    • label: string

    Returns TimerStopFunction

    Method to invoke to stop and log the timer.

uuid

  • uuid(): string

  • Generates a random RFC 4122 UUID guaranteed to be unique.

    example
    import { tracker } from '~/tracking';
    import { proxy } from '~/path/to/data';

    proxy.use({
      headers: {
        'x-session-id': tracker.uuid()
      },
      match: {
        base: '^my\-app' // can use regular expression syntax
      }
    });

    Returns string