Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added npm and event collection #183

Merged
merged 4 commits into from
Dec 27, 2024
Merged

Added npm and event collection #183

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
663009a
Update packages.md
SaraDScarf Nov 26, 2024
dcef83c
Merge branch 'master' into patch-8
SaraDScarf Dec 11, 2024
c3144ac
Small tweaks
aviaviavi Dec 27, 2024
17c54d1
small tweaks
aviaviavi Dec 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 51 additions & 7 deletions docs/packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ It will usually take 30 minutes and up to 2-3 hours before you see data pulled i

## File Packages

File Packages on Scarf are a flexible and low-level package type that can track visits and downloads on arbitrary URLs. File packages were originally created to track published tar balls, but it has since expanded to many other use cases and will likely be renamed in future versions of Scarf. You can think of File Packages as a powerful and fully customizable link shortener. Common use cases include:
File Packages on Scarf are a flexible and low-level package type that can track visits and downloads on arbitrary URLs. File packages were originally created to track published tar balls, but it has since expanded to many other use cases. You can think of File Packages as a powerful and fully customizable link shortener. Common use cases include:

- Tracking downloads of GitHub release artifacts
- Tracking downloads of every artifact on your company/project "downloads" page
Expand All @@ -75,15 +75,15 @@ File Packages on Scarf are a flexible and low-level package type that can track
- Tracking and attributing visits to marketing and sales content on your site.

### Creating a File Package
1. Once signed in to Scarf, navigate to the home page.
1. Log in to your Scarf account.

2. Click plus icon in the navigation, then select New Package.
2. Click the plus icon in the top right navigation, then select New Package.
![Create a new package](assets/pics/qs-file-packages/create-new-package.png)

3. In the first drop-down click on the package type you would like to create. For this section you will click `File`.
3. In the first drop-down click on the package type you would like to create. For this section you will click `New File`.
![Create a package](assets/pics/qs-file-packages/create-file.png)

4. Select the package owner from the dropdown.
4. Select a package owner from the dropdown of Organizations you belong to.
![Select package owner](assets/pics/qs-file-packages/file-package-select-owner.png)

5. Give your package a name.
Expand All @@ -98,7 +98,7 @@ This example uses 2 variables `{version}` and `{platform}`.

![path where files are located](assets/pics/qs-file-packages/file-package-outgoing-url.png)

2.) Choose the domain where your files should be available from. You may choose to use your own domain for serving files. You may also choose to use `<username>.gateway.scarf.sh` provided by default by Scarf.
2.) Choose the domain where your files will be available from. You may choose to use your own domain for serving files. You may also choose to use `<username>.gateway.scarf.sh` provided by default by Scarf.

3.) Add the Incoming URL Path where Scarf will direct requests to fetch a file asset.

Expand Down Expand Up @@ -139,6 +139,47 @@ Example:

![New file package route](assets/pics/qs-file-packages/file-package-new-route.png)

## npm Packages

NPM Packages on Scarf are a convenient way to collect usage and event telemetry from your npm packages by adding a dependncy on `[scarf-js](https://www.npmjs.com/package/@scarf/scarf)`.

1. Log in to your Scarf account.

2. Click the plus icon in the navigation, then select New Package.
![Create a new package](assets/pics/qs-file-packages/create-new-package.png)

3. In the first drop-down, select `npm` as the package type.
![Create a package](assets/pics/qs-file-packages/create-file.png)

4. Select the package owner from the dropdown list of Organizations you belong to.
![Select package owner](assets/pics/qs-file-packages/file-package-select-owner.png)

5. Give your npm package a name.
This name should match the name of your package on npm, or the same as the `name` in your `package.json`.
![Name your package](assets/pics/qs-file-packages/file-package-name.png)

6. Click **Submit**.

### Configuring Telemetry for npm packages
Once an npm entry has been created, you are ready to configure your package by adding scarf as a dependency
```bash
npm i --save @scarf/scarf
```
Once your library is published to npm with this change, Scarf will automatically
receive stats on install, no additional code is required! For additional details on configuration of the scarf-js library please refer to the [scarf-js NPM entry](https://www.npmjs.com/package/@scarf/scarf).

## Event Collection

## Event Collection Packages

Event Collection Packages on Scarf are another flexible package type which can be used to collect event telemetry by fetching a URL or by importing event history. Event Collection Packages are an alias of File packages and share all the same traits. Common use cases include:

- Sending custom telemetry or other events from your application
- Importing log or event history from your hosted installations to Scarf

### Creating an Event Collection Package
1. Log in to your Scarf acccount.

## Event Collection Packages

Event Collection Packages on Scarf are another flexible package type purpose built for telemetry data in general. Event data can be sent to a public Scarf Gateway URL of your choice, or by bulk ingesting events through our authenticated API. Event Collection Packages are an alias of File packages and share all the same traits. Common use cases include:
Expand All @@ -162,6 +203,7 @@ Event Collection Packages on Scarf are another flexible package type purpose bui
![Name your package](assets/pics/qs-file-packages/file-package-name.png)

### Adding an Incoming URL

This section explains what the Incoming URLs are and how to use a URL template for Event Collection.

1.) Add the URL path where your events will be collected. This is the user visible endpoint your application will connect to for event submission. This setting while required is not relevant when submitting events via the [Event Import API](https://docs.scarf.sh/event-import/).
Expand All @@ -173,11 +215,13 @@ This section explains what the Incoming URLs are and how to use a URL template f

3.) Click **Submit**.

4.) Configuring Telemetry
Once an Event Collection package has been created, you are ready to collect [Custom telemetry](https://docs.scarf.sh/custom-telemetry/)

### Configuring Event Collection
Once an Event Collection package has been created, you are ready to collect [Custom telemetry](https://docs.scarf.sh/custom-telemetry/)

## Python Packages

Scarf Gateway configuration for a Python package entry has three main considerations:

- pip Command: This is the current pip command used to install your package. For packages on PyPI.org, this will be of the form pip install my-pkg and will include the `--extra-index-url https://my-python-project-domain.com` if your package is hosted elsewhere. This defines the location where the users will be redirected to when installing your package.
Expand Down