diff --git a/docs/gcp.md b/docs/gcp.md new file mode 100644 index 0000000..d3a8ef6 --- /dev/null +++ b/docs/gcp.md @@ -0,0 +1,42 @@ +# Working with Scarf on Google Cloud + +Scarf offers a variety of ways to integrate into your workflows on Google Cloud, from monitoring your artifacts that are GCP-hosted, eg [Google Artifact Registry](https://cloud.google.com/artifact-registry/docs), to getting data and insights into your GCP-hosted storage systems. + +## Enhanced download tracking from Google Artifact Registry + +### Configure your collection + +Scarf offers a way to track container downloads across your entire project and repository by configuring a *Collection* + +To acces Collections, in the top menu click `Tools` > `Collections`. + +![Collections menu](assets/pics/auto-creation/collections-menu.png) + +You will now be presented with the `Collections` page that give you the options to edit, delete, and create new collections. + +![Collections page](assets/pics/auto-creation/collections-page.png) + +To create a new collection: + +1. Insert the `Path` that will be matched against on your domain. Artifact Registry images take the form `{project_id}/{repository}/{image}`; well-formed Scarf path patterns will take the form of `your-project-id/*/*` to match against any repository and image in your project_id. +2. Next, insert a fully concrete `Backend Domain` of the form: `{your-location}-docker.pkg.dev`, eg `us-west1-docker.pkg.dev`. This is where Scarf will redirect your traffic that match the `Public Domain` and `Path` template you set. +3. Finally, enter the `Public Domain` you'd like to use. This can be `your-organization.docker.scarf.sh` or a custom domain of your choice. + +As soon as your images are pulled, Scarf will create your package entries automatically. No additional configuration is needed as you push new containers to Artifact Registry. + +[Learn more about collections here.](../gateway/#creating-collections) + +## Enhanced download tracking from Google Cloud Storage + +Create a File Package [as described](../packages/#file-packages) with a few GCP specific attributes. + +For your `File location` template, enter `https://storage.googleapis.com/{bucket_name}/{object_name}`. + +In your `Desired path format`, you can specify arbitrary formats, as long as any variables in your `File location` are also specified. For instance something as simple as: + +``` +/{bucket_name}/{object} +``` + +This can be customized further as needed, or made more concrete for specific buckets or objects. Read more about [File Packages](../gateway/#file-packages) for more information. + diff --git a/docs/organizations.md b/docs/organizations.md index 3220e9d..dd029cd 100644 --- a/docs/organizations.md +++ b/docs/organizations.md @@ -2,7 +2,9 @@ ## Creating an organization -To create an organization, in the header menu click on the `Organization` button +If you’re part of a company, open-source team, or have multiple stakeholders managing packages, converting to a Scarf Organization simplifies management and scales better than an individual account. + +To create an organization, in the header menu click on the `Organization` button, ![Organization button](assets/pics/orgs/organization-button.png) @@ -66,7 +68,11 @@ Et voilà! You now have new organization ![Organization page](assets/pics/orgs/organization-edit-page.png) -## Managing your organization +## Managing your Organization + +### Filter Settings + +You can manage Filter settings for your Organization by clicking into Filter Settings on your organization overview. ### Data providers @@ -82,7 +88,6 @@ To enable this Clearbit for your organization, navigate to your organization ove | Scarf Tier | Included Clearbit calls per month | |------------|----------------------------------------------------------| -| Free | 10,000 calls/month included (for a limited time) | | Basic | 10,000 calls/month included | | Premium | 25,000 calls/month included, with pay-per-usage upgrades | diff --git a/docs/packages.md b/docs/packages.md index d516114..8e2b2d7 100644 --- a/docs/packages.md +++ b/docs/packages.md @@ -1,14 +1,16 @@ -# Packages +# Setting up Scarf Packages ## Prerequisites - You will need to sign up for a [Scarf account](https://app.scarf.sh/register). - > _**Note:** You can sign up with a valid email address or your GitHub account._ -- The container to be tracked must be published to a public registry; eg Docker Hub, GitHub Container Registry. -> **Note:** This guide will use the `hello-world` [docker image](https://hub.docker.com/_/hello-world). + > **Note:** You can sign up with a valid email address or your GitHub account. + +- To track a container, it must be published to a public registry; eg Docker Hub, GitHub Container Registry. -## Docker + > **Note:** This guide will use the `hello-world` [docker image](https://hub.docker.com/_/hello-world). + +## Docker Packages ### Creating a Docker Package @@ -32,6 +34,7 @@ Using Scarf, users can pull your Docker container images via Scarf Gateway using 5. Optional: You can add a custom domain or use the domain provided by Scarf Gateway. 6. Click the `Submit` button to be redirected to a success screen with some additional information as to what you can do next. 7. Click on on `Go to your package` to view your package details view. + ![Enter the docker pull command](assets/pics/quick-start/docker-packages-succces-screen.png) Now you’re all set to start tracking your Docker images with Scarf. @@ -48,16 +51,20 @@ In the next section, you will create a tracking pixel that can be added to your In this section you will download your package with the pull command found in your package dashboard to start fetching data. 1. Navigate to your package details view. + ![Package dashboard](assets/pics/quick-start/docker-copy-pull-command.png) -2. Copy the Pull command. -3. Navigate to a terminal on your computer and run the Pull command. + +3. Copy the Pull command. +4. Navigate to a terminal on your computer and run the Pull command. + ![Run Scarf pull command](assets/pics/quick-start/terminal_pull.png) + _**Note:** Make sure the docker daemon is running on your computer._ -4. Back to the package details view and click on `View Analytics`. You should now see the Package Insights starting to populate with data. +6. Back to the package details view and click on `View Analytics`. You should now see the Package Insights starting to populate with data. It will usually take 30 minutes and up to 2-3 hours before you see data pulled in. Every time a user pulls your Docker container images from Scarf Gateway the data in your Package Insights will be updated. ![Data from packages](assets/pics/quick-start/package-analytics.png) -## Files +## 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: @@ -132,9 +139,61 @@ Example: ![New file package route](assets/pics/qs-file-packages/file-package-new-route.png) -## What’s Next? +## 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: + +- Sending custom telemetry or other events from your application +- Importing historical event data from an external application into to Scarf + +### Creating an Event Collection Package +1. Once signed in to Scarf, navigate to the home page. + +2. Click 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 click on the package type you would like to create. For this section you will click `Event Collection`. +![Create a package](assets/pics/qs-file-packages/create-file.png) + +4. Select the package owner from the dropdown. +![Select package owner](assets/pics/qs-file-packages/file-package-select-owner.png) + +5. Give your package a name. +![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/). + > Note: You can use a URL template, but if you use variables in your URL they need to also be used in your Incoming Path that is defined in the next step. + +![path where files are located](assets/pics/qs-file-packages/file-package-incoming.png) + +2.) Choose the domain where your events will be submitted. You may choose to use your own domain or you may choose to use `.gateway.scarf.sh` provided by default by Scarf. + +3.) Click **Submit**. + +### 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. +- Domain: This can be your own domain, or a Scarf-supplied domain, of the form `.gateway.scarf.sh`. By default, your Scarf domain will be used if this field is left empty. +- Telemetry: This allows you to gather insights into how your package is used without collecting any personally identifiable information. + +Installing Python packages via requirements.txt +Add the `--extra-index-url` option at the top of your requirements.txt: + +``` +--extra-index-url https://my-python-project-domain.com/simple/ +my-pkg==0.0.1 +``` + +NOTE: We have noticed indeterminate behavior in some versions of Pip that have resulted in the public registry being used for download regardless of the `--extra-index-url` addition. -- [Create a Pixel](/web-traffic) -- [Learn more about the Scarf Gateway](/gateway) +If you elect to use your own domain, you'll need to add a CNAME for that domain to `gateway.scarf.sh`. Additionally we require you to verify your ownership of the domain by setting a TXT with a value that Scarf provides upon package creation. See your DNS provider's instructions for how to add CNAME and TXT records. If you have questions or need help, join our [Slack community](https://tinyurl.com/scarf-community-slack). diff --git a/docs/quick-start.md b/docs/quick-start.md index a3cc355..e8ed8b7 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -59,7 +59,9 @@ In the next section, you will create a tracking pixel that can be added to your ### Creating a Tracking Pixel for Your Package -Tracking pixels are used to leverage the web traffic from your project’s documentation to learn which companies are using your software. +How the Package-Pixel Pair Works: +- Package Distribution: When users install your package, metadata like download source, volume, and timing can be routed through Scarf's infrastructure (e.g., via Scarf Gateway). +- Pixel Integration: The pixel is included in the package or its associated documentation. When the pixel is triggered, it records usage events, similar to a web analytics tracker. 1. Navigate to the [Scarf homepage](https://app.scarf.sh/home/). diff --git a/docs/sales-prospecting.md b/docs/sales-prospecting.md index 2cc614c..4b0d051 100644 --- a/docs/sales-prospecting.md +++ b/docs/sales-prospecting.md @@ -6,7 +6,7 @@ Companies familiar with your OSS are more likely to respond to sales outreach; t By identifying contacts at these companies, you can better prospect for upgrades to a paid version or a commercial support plan. -## This is where Scarf’s (Lead Generation) Sales Prospecting Service comes in. +*This is where Scarf’s (Lead Generation) Sales Prospecting Service comes in.* ### What is it? - In addition to the company names provided by Scarf, users also get a custom report of contacts at those companies who meet your ideal customer profile (ICP) and key buyer personas.