Iterative Telemetry

0.0.10 · active · verified Fri Apr 10

Iterative Telemetry is a common Python library used for sending anonymized usage telemetry. It can be disabled via an environment variable and collects a minimal amount of anonymized data to understand tool usage. The current version is 0.0.10, with patch-level releases occurring periodically.

Warnings

gotcha Telemetry can be entirely disabled by setting the environment variable `ITERATIVE_DO_NOT_TRACK=1`. This is a crucial user control for privacy.
Fix: Ensure users are aware of the `ITERATIVE_DO_NOT_TRACK` environment variable to opt-out of telemetry collection.
gotcha Prior to version 0.0.10, telemetry exception handling in daemon mode was fixed. Older versions may have experienced silent failures or unhandled exceptions in long-running background processes.
Fix: Upgrade to version 0.0.10 or newer to ensure robust exception handling in daemonized applications.
gotcha Before version 0.0.8, the library might have failed if the GitHub CLI was expected (e.g., for user ID inference) but not present on the system, leading to unexpected errors.
Fix: Upgrade to version 0.0.8 or newer to include exception handling for missing GitHub CLI.
gotcha The library is currently in 'Beta' development status (4 - Beta). While stable for its current use cases, the API or internal mechanisms might still undergo changes in future minor or major releases.
Fix: Be aware that as a beta project, API surface or behavior may change in future versions. Review changelogs carefully when upgrading.

Install

pip install iterative-telemetry Install latest version

Imports

IterativeTelemetryLogger

from iterative_telemetry.logger import IterativeTelemetryLogger

Quickstart

Initialize the IterativeTelemetryLogger with your tool's name and send custom events. Telemetry can be globally disabled by setting the `ITERATIVE_DO_NOT_TRACK=1` environment variable.

import os
from iterative_telemetry.logger import IterativeTelemetryLogger

# Instantiate the logger with your tool's name
# Telemetry can be disabled by setting ITERATIVE_DO_NOT_TRACK=1 in environment variables
logger = IterativeTelemetryLogger(tool_name="my_awesome_tool")

# Send a simple event
logger.send_event("tool_started", {"version": "1.0.0", "mode": "cli"})

# Send an event only once per user/tool instance (e.g., for first-time setup)
logger.send_event_once("first_run_event")

print("Telemetry events sent (or skipped if ITERATIVE_DO_NOT_TRACK is set).")

view raw JSON →