npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

telemetry-github

v0.1.1

Published

telemetry for GitHub client apps

Downloads

84

Readme

Build Status

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.

Getting started

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.

Counters vs. custom events

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" }

Timers

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);

Options

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.

Publishing a new release

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.

License

MIT

When using any GitHub logos, be sure to follow the GitHub logo guidelines.