Scarf SDK

0.2.1 · active · verified Thu Apr 16

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.

Common errors

```
NameError: name 'ScarfEventLogger' is not defined
```
cause 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.
```
cause 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.
```
cause 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)`.

Warnings

gotcha Telemetry 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.
gotcha Users 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.
gotcha The 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.

Install

pip install scarf-sdk Install stable version

Imports

ScarfEventLogger
```
from scarf import ScarfEventLogger
```

Quickstart

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

view raw JSON →