Atom and all repositories under Atom will be archived on December 15, 2022. Learn more in our official announcement
telemetry-github is an open source module written in TypeScript. It sends usage metrics to GitHub's internal analytics pipeline.
This app can be used from any GitHub client application that speaks JavaScript and has access to localStorage.
We've open-sourced this library because we care about privacy and want to be transparent about how we collect metrics.
to install package and dependencies:
npm install telemetry-github
to run tests:
npm test
to run lint:
npm run-script lint
to compile typescript:
tsc
The client api is experimental and subject to change. but for right now it looks something like this:
import StatsStore from "telemetry-github";
// make a store
const store = new StatsStore("atom", "1.24.1", false, getAccessToken, options);
// record a usage event
store.incrementCounter("commit");
// record a change in user consent to record metrics
store.setOptOut(true);
Please note that there are several methods of the StatsStore class that are public for unit testing purposes only. The methods describe below are the ones that clients should care about.
There are some event types that are common across all client apps: usage events, ping events, and opt in / out events. telemetry encapsulates as much complexity around these as possible so clients don't have to deal with it.
Counters are a great fit for understanding the number of times a certain action happened. For example, how many times per day do users click a particular button?
However, apps might want to collect more complex metrics with arbitrary metadata. For example, Atom currently collects "file open" events, which preserve the grammar (aka language) of the opened file. For those use cases, the addCustomEvent function is your friend. addCustomEvent takes any object and stuffs it in the database, giving clients the flexibility to define their own data destiny. The events are sent to the metrics back end along with the daily payload.
Events must include a type, which is the first argument to addCustomEvent. A timestamp is added for you in ISO-8601 format.
const event = { grammar: "javascript" };
await store.addCustomEvent("open", event);
// { "date": "2018-06-14T21:01:33.602Z", "eventType": "open", "grammar": "javascript" }
You can use the addTimer API to send latency metrics. While of course you could use addCustomEvent to record latency metrics, using this endpoint allows us to have a consistent event format across apps.
const eventType = "appStartup";
const loadTimeInMilliseconds = 42;
const metadata = {spam: "ham"};
// metadata is optional
store.addTiming(eventType, loadTimeInMilliseconds, metadata);
You can pass additional options to telemetry via its constructor:
// The following are the default values
const options = {
reportingFrequency: 86400, // How often do we want to send metrics.
logInDevMode: false, // Whether it should send metrics when isDevMode is true.
verboseMode: false, // Whether it should log the requests in the console.
};
const store = new StatsStore("atom", "1.24.1", false, getAccessToken, options);All the option parameters are optional.
Follow these instructions for releasing a new version with npm. In order for client apps to use a new version, bump the version of telemetry-github in the package.json file, and then run npm install again.
When using any GitHub logos, be sure to follow the GitHub logo guidelines.