Integrating Scarf for collecting anonymous usage metrics for SDKs, container images, docs

[tiswanso]

The AGNTCY TSC is evaluating whether to use Scarf for package usage metrics collection.

Scarf is a LF backed project and fits with the LF telemetry data policy.

• it's also listed in CNCF's hosted tools
• AGNTCY would get licenses & credits since it's a part of LF: https://docs.scarf.sh/foundation-backed-projects/

  Unlimited seat licenses for all project maintainers.
  Unlimited data retention.
  100 Monthly Tracked Company (MTC) credits.
  Your foundation may also have access to additional benefits beyond what's listed here, just ask us, or talk to your foundation-side contact.

Use cases summary:

• Enriched IP data Metrics for
  • project artifact downloads: container images, pypi packages, npm packages, release binaries, …
    • Acts as URI router--usable in solutions with project DNS (registry provider agnostic): see https://docs.scarf.sh/gateway/#container-image-packages
  • Docs / READMEs via img pixel
• Custom metrics (call-home to scarf endpoint)--e.g. see project longhorn's usage

OSS Project Usage Examples

• Linkerd:
  • Custom domain that linkerd uses for container images (via scarf gateway): cr.l5d.io/linkerd
    • https://github.com/linkerd/linkerd2/blob/main/charts/linkerd2-cni/values.yaml#L70
    • https://github.com/linkerd/linkerd2/blob/main/charts/linkerd-control-plane/values.yaml#L147
    • Orig PR: docker: Access container images via cr.l5d.io linkerd/linkerd2#5756
• Project longhorn integration: [TASK] Add Scarf integration for adoption metrics collection longhorn/longhorn#11783
  • send events to Scarf during upgrades (version info metrics): Introduce optional ability to trigger Scarf.sh events longhorn/upgrade-responder#62

A2A project also has it under consideration: a2aproject/A2A#1379

• Feature tracker for anonymous A2A SDK usage telemetry

Effort:

• Container image downloads

  • Change helm charts defaults and docker-compose to refer to new scarf image registry URL
  • READMEs/docs updates to refer to image registry URLs
  • (optional) DNS: new domain name with CNAME & TXT to integrate with scarf -- eg. containers.agntcy.org

• SDK Packages

  • python -- SDK users change requirements.yaml to use '--extra-index-url' to point to scarf URL
    • or for uv settings like this in pyproject.toml:

       [tool.uv.pip]
       extra-index-url = ["https://download.pytorch.org/whl/cpu"]
      

  • .js (npm) -- SDK package add scarf as a dependency npm i --save @scarf/scarf
  • Rust -- ? SDK users importing SDK like this should work to use custom registry URL for scarf gateway: some-crate = { version = "1.0", registry = "my-private-registry" }

• Binary release artifacts

  • github releases: ??? I'm not sure if/how we can add custom download URLs in github releases pages within the normal actions/create-release -> actions/upload-release-asset workflow