Implement a Call-Home Functionality or Telemetry in your Open Source Project

Overview

Implementing telemetry in your open source project helps you determine whether people are testing your software and continuing its use over time. Such insights not only confirm if the developed software meets users’ needs but also helps identify which versions are being adopted and which might be vulnerable to the latest bugs or other issues.

Scarf telemetry offers different implementation options. If you need a tailored solution for a particular use case, don’t hesitate to reach out—we’re here to assist.

What you’ll need: 

• Scarf (sign up for free). You can sign up with a valid email address or your GitHub account.

To implement a call-home or telemetry functionality, you need to decide what you will track and where to store it. You can, for example, create a JSON file on GitHub to store the latest version. You could host this file on your website, embed the response as part of a public API, or put it into your factor CDN. Where this is hosted is less important than having a URL to which we can redirect.

Step 0: Create a new File Package

Repeat the same first steps. Create a new File Package, select an owner, and give it a name.

Select Event Collection Only.

Choose the domain where your files should be available. You may choose to use your own domain to serve files. You may also choose to use <username>.gateway.scarf.sh, provided by default by Scarf.

The Desired Path Format is the URL that will be receiving information from your project’s files.

Pro tip: Telemetry events are often of high importance for organizations. Don’t forget to adjust the importance slider accordingly.

Step 1: Test your File Package

After creating this setup, confirm that the URL is operational by opening the new URL in a web browser. Verify the setup in the Scarf Dashboard and view the analytics.

Step 2: Include your new Scarf URL in your project

Next, use your new Scarf Package URL in your project. When someone executes the desired file, a new “download” will be listed from your project’s file.

Each time the script (or code snippet) runs, the event is logged. You can also gather information about the geographical origin of the call, basic company information, and more.

After testing the various methods for measuring downloads, views, and usage with Scarf, create a plan for what you want to track and the data you want to see.

Here is a real world example from Unstructured.io in Python:

# Copyright 2022 Unstructured Technologies, Inc# Licensed under the Apache License, Version 2.0def scarf_analytics():       try:     # If either environment variable is set, do not collect metrics and exit.        if os.getenv("SCARF_NO_ANALYTICS") != "true" and os.getenv("DO_NOT_TRACK") != "true":            requests.get(          # CUSTOMER_ENDPOINT is a DNS CNAME configured within your Scarf account          # FILE_PACKAGE_NAME is the Scarf collection under which these data points will be collected                "https://CUSOMER_ENDPOINT.scarf.sh/FILE_PACKAGE_NAME?version="                + __version__                + "&platform="                + platform.system()                + "&python"                + python_version                + "&arch="                + platform.machine(),            )    except Exception:        pass

Step 3: Update your marketing materials

Make sure to:

• Roll out tracking to all your projects/sites.
• Update all documentation and tutorials to use your custom URLs.

If you want to improve your lead flow, start by filling out the lead generation form once your data is flowing in. Reach out to your customer success manager or our sales team to inquire about a trial of Scarf’s lead generation service.