scarf-sdk

library0.2.1pypypi✓ verified 85d ago

Scarf's Python SDK is a client library for sending telemetry events to Scarf, typically using JSON payloads. It provides open-source software maintainers with deep insights into how their projects are being used, by which companies, and more, aiding in understanding reach and identifying growth opportunities. The library is actively maintained with consistent minor updates.

observability http-networking

pip install scarf-sdk

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SCARF-SDK

scarf-sdk

observabilitypythonv0.2.1

Install

2.1s avg

Import

621ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.652s · 21.2MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.1s · import 0.590s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ScarfEventLogger

✓ from scarf import ScarfEventLogger

This quickstart demonstrates how to initialize the `ScarfEventLogger` with a Scarf endpoint URL and send a custom telemetry event with a JSON payload. It also highlights how users can opt-out using environment variables.

import os from scarf import ScarfEventLogger # Initialize with your Scarf endpoint URL. This is typically found in your Scarf dashboard. # For a runnable example, we use an environment variable or a placeholder. endpoint_url = os.environ.get('SCARF_ENDPOINT_URL', 'https://your-scarf-endpoint.com') logger = ScarfEventLogger( endpoint_url=endpoint_url, timeout=5.0 # Optional: Set a default timeout in seconds (default is 3.0) ) # Send an event with properties (JSON payload) success = logger.log_event({ "event": "package_function_call", "package": "my_python_library", "details": { "version": "1.2.3", "feature": "data_processing", "user_id": "anon_user_123" } }) if success: print("Telemetry event sent successfully.") else: print("Failed to send telemetry event.") # Telemetry can be disabled by users via environment variables: # DO_NOT_TRACK=1 or SCARF_NO_ANALYTICS=1

Debug

Known issues

gotchaTelemetry events are sent to a specific `endpoint_url`. Failing to provide a valid and accessible URL during `ScarfEventLogger` initialization will result in events not being received by Scarf.

fix

Always ensure the `endpoint_url` passed to `ScarfEventLogger` is correct and resolves to your Scarf Gateway or event collection endpoint.

affects: All versions

gotchaUsers can disable telemetry collection by setting the `DO_NOT_TRACK` or `SCARF_NO_ANALYTICS` environment variables to `1`. This means your application might not report data if a user has opted out.

fix

Inform your users about the `DO_NOT_TRACK` and `SCARF_NO_ANALYTICS` environment variables for privacy control. Handle scenarios where telemetry might be disabled gracefully in your application logic.

affects: All versions

gotchaThe default timeout for sending telemetry events is 3 seconds. On unstable networks or with large payloads, this might be too short, leading to `requests.exceptions.Timeout` errors and dropped events.

fix

Consider increasing the `timeout` parameter during `ScarfEventLogger` initialization (e.g., `timeout=10.0`) or when calling `logger.log_event` for specific events.

affects: All versions

Errors

Common errors & fixes

NameError: name 'ScarfEventLogger' is not defined

The `scarf-sdk` library is not installed or the `ScarfEventLogger` class was not imported correctly.

fix

Ensure the library is installed with `pip install scarf-sdk` and import it using `from scarf import ScarfEventLogger`.

Telemetry events are not appearing in my Scarf dashboard.

This often occurs if the provided `endpoint_url` is incorrect or inaccessible, or if the user has opted out of analytics via environment variables (`DO_NOT_TRACK` or `SCARF_NO_ANALYTICS`).

fix

Double-check that the `endpoint_url` is correct and reachable. Verify that `DO_NOT_TRACK` or `SCARF_NO_ANALYTICS` environment variables are not set to `1` in the execution environment. Also ensure an Event Collection Package is configured in your Scarf account.

requests.exceptions.Timeout: HTTPSConnectionPool(...) Read timed out.

The network request to send the telemetry event took longer than the configured timeout period.

fix

Increase the `timeout` parameter when initializing `ScarfEventLogger` or when calling `log_event`. For example: `logger = ScarfEventLogger(endpoint_url="...", timeout=10.0)`.

Upgrade

Version history

0.2.1latest on PyPI · released Dec 31, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/scarf-sh/scarf-py ↗

packagehttps://pypi.org/project/scarf-sdk/ ↗

homepagehttps://scarf.sh ↗