Narcoleptic's Patch Mangler
Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

piral-tracking

0.12.1 • Public • Published

Piral Logo

Piral Tracking · GitHub License npm version tested with jest Gitter Chat

This is a plugin that only has a peer dependency to piral-core. What piral-tracking brings to the table is a set of Pilet API extensions that can be used with piral or piral-core.

The set includes the track... APIs to be used in pilets for using a set of analytics, telemetry, and tracking tools from your Piral instance.

By default, these API extensions are not integrated in piral, so you'd need to add them to your Piral instance.

Documentation

The following functions are brought to the Pilet API.

trackEvent()

Tracks a custom event incl. properties and other standard metrics.

trackError()

Tracks an error or exceptional behavior incl. properties.

trackFrame()

Starts a tracking frame. The frame can be ended via the returned callback.

Usage

::: summary: For pilet authors

You can use the trackEvent function from the Pilet API to track a custom event with an arbitrary definition.

Example use:

import { PiletApi } from '<name-of-piral-instance>';
 
export function setup(piral: PiletApi) {
  piral.trackEvent('sample-pilet-ready');
}

You can use the trackError function from the Pilet API to track an error from the pilet.

Example use:

import { PiletApi } from '<name-of-piral-instance>';
 
export function setup(piral: PiletApi) {
  try {
    throw new Error('Ouch!');
  } catch (e) {
    piral.trackError(e);
  }
}

You can use the trackFrame function from the Pilet API to track a custom event with integrated running time measurement.

Example use:

import { PiletApi } from '<name-of-piral-instance>';
 
export function setup(piral: PiletApi) {
  const frame = piral.trackFrame('sample-pilet-computation');
 
  setTimeout(() => {
    frame();
  }, 4000);
}

:::

::: summary: For Piral instance developers

The provided library only brings API extensions for pilets to a Piral instance.

For the setup of the library itself you'll need to import createTrackingApi from the piral-tracking package.

import { createTrackingApi } from 'piral-tracking';

The integration looks like:

const instance = createInstance({
  // important part
  plugins: [createTrackingApi()],
  // ...
});

There are no options available.

The integration of other trackers is done by listening to the events. Example for Application Insights:

import { createInstance } from 'piral';
import { createTrackingApi } from 'piral-tracking';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
 
const appInsights = new ApplicationInsights({
  // ...
});
 
appInsights.loadAppInsights();
 
const instance = createInstance({
  plugins: [createTrackingApi()]
});
 
instance.on('track-event', evt => {
  const name = evt.name;
  const properties = {
    ...evt.properties,
    piletName: evt.pilet,
  };
  appInsights.trackEvent({ name, properties });
});

:::

Events

The extension gives the core a set of new events to be listened to:

  • track-event
  • track-error
  • track-frame-start and track-frame-end

The events are fully typed.

License

Piral is released using the MIT license. For more information see the license file.

Install

npm i piral-tracking

DownloadsWeekly Downloads

778

Version

0.12.1

License

MIT

Unpacked Size

21.1 kB

Total Files

16

Homepage

piral.io

Last publish

Collaborators

  • avatar