@kano/telemetry

    1.0.3 • Public • Published

    Telemetry

    Provides a unified telemetry API reporting API usages, user actions and custom events.

    Installation

    yarn add @kano/telemetry

    Usage

    Simple

    import { TelemetryClient } from '@kano/telemetry/index.js';
    
    const client = new TelemetryClient();
    
    const subscription = client.onDidTrackEvent((event) => {
        // Add to a message queue or send to server
        const message = [
            event.timestamp,
            event.scope,
            event.name,
            event.properties,
        ];
    });
    
    // You can track different type of telemetry events
    client.trackEvent({ name: 'MyEvent', properties: {} });
    client.trackException({ exception: new Error('Something went wrong') });
    client.trackMetric({ name: 'my metric', value: 3 });
    client.trackTrace({ message: 'Tracing...' });
    client.trackPageView({ page: '/login' });
    
    // When done
    subscription.dispose();

    Mounting Clients

    You can mount clients to reconciliate events accross multiple telemetry clients. A usual pattern would be to create a master client in your app and mount the clients provided by your dependencies.

    import { TelemetryClient } from '@kano/telemetry/index.js';
    
    const client = new TelemetryClient({ scope: 'my-app' });
    const otherClient = new TelemetryClient({ scope: 'auth' });
    
    client.mount(otherClient);
    
    // From now on all events from the otheClient will be available under the client. Scopes will be nested
    
    client.onDidTrackEvent((event) => {
        console.log(event.scope);
        //> ['my-app', 'auth']
    });
    
    otherClient.trackEvent({ name: 'MyEvent', properties: {} });

    Default collections

    import { TelemetryClient } from '@kano/telemetry/index.js';
    
    const client = new TelemetryClient();
    
    // Automatically collects all unhandled exceptions and page views
    client.collectExceptions();

    Reporting

    You can either subscribe to a client and manage the events yourself or use a readymade reporter to store all your events

    Queue

    The queue will stack events until a configurable timeout is reached or a max number of events is reached.

    import { QueueReporter, TelemetryClient } from '@kano/telemetry/index.js';
    
    const client = new TelemetryClient();
    
    const reporter = new QueueReporter({
        maxBatchSize: 20,
        fireInterval: 3000,
    });
    
    reporter.onDidBatchEvents((batch) => {
        // batch has an events property containing the last batch of events
        // More events can be created while the batch is being saved. Call flush when you successfully
        // reported the events, no more events will be fired until flush or failed is called
        fetch('api.host.me/telemetry', {
            method: 'POST',
            body: JSON.stringify(bash.events),
        }).then((r) => {
            if (r.status !== 200) {
                bash.fail();
            } else {
                bash.flush();
            }
        });
    });
    
    reporter.start(client);

    Alternatively, you can extend a reporter and override the fire method.

    import { QueueReporter } from '@kano/telemetry/index.js';
    
    class MyReporter extends QueueReporter {
        fire(batch) {
            // save, then flush or fail
        }
    }
    
    const reporter = new MyReporter({
        maxBatchSize: 20,
        fireInterval: 3000,
    });
    
    reporter.start(client);

    Development

    Tests

    Using polymer cli, serve the contents of the directory

    polymer serve
    

    Then browse to the promted url at /test

    Keywords

    none

    Install

    npm i @kano/telemetry

    DownloadsWeekly Downloads

    17

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    11.5 kB

    Total Files

    8

    Last publish

    Collaborators

    • alexdamis
    • drew-h
    • andrejordan
    • snpranav
    • hediho
    • ianjc
    • ellenw3lsh
    • melissakano
    • camuskano
    • jacobmorgan99
    • alexfiennes
    • kanocomputing
    • rpazdera
    • hicksatkano
    • holographicleah
    • tomkano
    • alexb-kano
    • jamie_old_plantain