{"id":8621,"library":"scarf-sdk","title":"Scarf SDK","description":"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.","status":"active","version":"0.2.1","language":"en","source_language":"en","source_url":"https://github.com/scarf-sh/scarf-py","tags":["telemetry","analytics","usage tracking","sdk","open-source"],"install":[{"cmd":"pip install scarf-sdk","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"ScarfEventLogger","correct":"from scarf import ScarfEventLogger"}],"quickstart":{"code":"import os\nfrom scarf import ScarfEventLogger\n\n# Initialize with your Scarf endpoint URL. This is typically found in your Scarf dashboard.\n# For a runnable example, we use an environment variable or a placeholder.\nendpoint_url = os.environ.get('SCARF_ENDPOINT_URL', 'https://your-scarf-endpoint.com')\n\nlogger = ScarfEventLogger(\n    endpoint_url=endpoint_url,\n    timeout=5.0 # Optional: Set a default timeout in seconds (default is 3.0)\n)\n\n# Send an event with properties (JSON payload)\nsuccess = logger.log_event({\n    \"event\": \"package_function_call\",\n    \"package\": \"my_python_library\",\n    \"details\": {\n        \"version\": \"1.2.3\",\n        \"feature\": \"data_processing\",\n        \"user_id\": \"anon_user_123\"\n    }\n})\n\nif success:\n    print(\"Telemetry event sent successfully.\")\nelse:\n    print(\"Failed to send telemetry event.\")\n\n# Telemetry can be disabled by users via environment variables:\n# DO_NOT_TRACK=1 or SCARF_NO_ANALYTICS=1","lang":"python","description":"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."},"warnings":[{"fix":"Always ensure the `endpoint_url` passed to `ScarfEventLogger` is correct and resolves to your Scarf Gateway or event collection endpoint.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consider increasing the `timeout` parameter during `ScarfEventLogger` initialization (e.g., `timeout=10.0`) or when calling `logger.log_event` for specific events.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the library is installed with `pip install scarf-sdk` and import it using `from scarf import ScarfEventLogger`.","cause":"The `scarf-sdk` library is not installed or the `ScarfEventLogger` class was not imported correctly.","error":"NameError: name 'ScarfEventLogger' is not defined"},{"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.","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`).","error":"Telemetry events are not appearing in my Scarf dashboard."},{"fix":"Increase the `timeout` parameter when initializing `ScarfEventLogger` or when calling `log_event`. For example: `logger = ScarfEventLogger(endpoint_url=\"...\", timeout=10.0)`.","cause":"The network request to send the telemetry event took longer than the configured timeout period.","error":"requests.exceptions.Timeout: HTTPSConnectionPool(...) Read timed out."}]}