Package: telly
Tellysimple, privacy-friendly usage statistics for your open source softwareWhat is Telly?Tellymakes it easy to collect usage statistics and support telemetry for your open source software. For most
packages, you can start collecting daily active user counts and feature usage statistics with just one line of code.Critically, Telly can also help you respect the privacy of your users and comply with privacy regulations. Our data
collection infrastructure and reporting dashboard are built with Privacy by Design principles, including features like
end-to-end encryption and differential privacy. While only you can determine if rules like GDPR or CCPA apply to your
situation, Telly can help you collect useful data in a responsible way.Why is Telly useful?Building open source software is hard. Whether you're a commercial open source company or just sharing a hobby project,
it can be nearly impossible to answer questions like:How many people are actually using my software on a daily basis?Which features or use cases are most popular?Which versions of my software are still actively used?Is anyone using my package on Ubuntu 12.04, Windows 7, or a Raspberry Pi?Which versions or implementations of Python are my users using?Is my software being installed or used from a private repository outside of PyPI?Telly is designed to make answering these questions possible with minimal effort and without compromising user privacy.Why did we build Telly?We've been working on open source projects for more than two decades, including prior commercial open source businesses.
We're also active users of open source software.Telly is the tool we wish we'd had as software developers, built in a way that we'd actually accept as software users.How do I use Telly?Integrating Telly into your project is simple.Addtellyto yourrequirements.txt,setup.py, or viapoetry add telly.Configure your data collection account athttps://gotelly.io/start.Copy the line of code from the web app into your project.Add a notice to your project's README.md that explains how you're using Telly to improve your project.For most packages, the change is just one line of code at the bottom of your instrumented module:importsys;importtelly;telly.go(sys.modules[__name__],'my-project-uuid')That's it!  As long as your code executes in an environment where egress traffic tohttps://telly.shis allowed, data
will automatically be collected and visible in your dashboard based on your project's privacy settings.If you want to select specific methods or classes for instrumenting, you can also use the following methods:telly.decorate_all_classes(sys.modules[__name__])- decorate all classes in the moduletelly.decorate_all_methods(sys.modules[__name__])- decorate all methods in the moduletelly.decorate(sys.modules[__name__])- decorate all classes and methods in the module@count_decoratorwith each methodWhat data does Telly collect?Telly can be configured to collect more or less information. Currently, this information is separated into two groups:Level IPython Interpreter (implementation, version, environment)Execution Platform (CPU, RAM, OS)Python Package Environment (packages, versions)Aggregate counts of method calls or class invocations (no argument values ever)Level IIBy default, Level II information is always salted and hashed.  Values are never directly visible to any humans, and
Telly only stores values temporarily during each rolling analytics window. This approach, combined with differential
privacy techniques for statistics, allows us to estimate quantities the number of unique users and user behavior while
reducing the likelihood of disclosing personally identifiable information.Level II information currently includes:Salted SHA-256 of usernameSalted SHA-256 of user home pathSalted SHA-256 of machine IDSalted SHA-256 of machine hostnameTwo salting methods are currently available and can be set with theTELLY_SALT_TYPEenvironment variable:random_uuid4: RFC 4122 UUID4 (uuid.uuid4())defaultmachine_id: Machine ID (uuid.getnode())Therandom_uuid4salt is calculated once and stored in~/.telly_salt.  If that path is not writable, such as in
highly-restricted execution environments, Telly falls back on machine ID.  The quality ofuuid.uuid4()varies
across different implementations and versions of Python but is considered to be cryptographically secure
for salting purposes.Note: For internal corporate usage of Telly, Level II information can be logged and made visible in the dashboard
subject to contract terms.Supported languages and geographiesTelly doesn't just support Python libraries. It's also compatible with Node viaTelly.jsand support for other
languages is on the way.Telly lets you choose where data about your users is stored. We currently support fully-isolated environments in the
US and EU.Sample notice languageIn most circumstances, when you embed Telly in your project, you'll want to add a notice to your README.md that lets
your users
know what information Telly is collecting and how you're using it to manage your project.Here are a few examples of notices that you might start from:Example 1We want to make our software more useful and reliable.  In order to do that, we're using Telly, a privacy-friendly
usage statistics and support tool.  Telly may collect basic information about your Python and OS environment, allowing 
us to understand things like which operating systems and Python versions to support.   In some cases, Telly may also
collect SHA-256-hashed representations of information that allows us to estimate our unique number of users.  These 
hashes are only used temporarily to assign a temporary ID for aggregate reporting; no plaintext information is ever
transmitted or visible to humans and even hashes are only stored during a temporary, rolling analytics window.  

You can learn more about Telly's privacy functionality here: https://gotelly.io/.  

To disable Telly's data collection, you can either:
 * set the TELLY_DISABLE environment variable to a truthy value like Y or 1
 * create a file named .telly_disable in your home directoryExample 2This software may collect information about you and your use of the software, which is shared with our telemetry 
partner, Telly. You can learn more about how we use this information at our website here: [your privacy notice]Verifying telly distributions with sigstoreWe use sigstore to sign telly distributions.  You can use sigstore to verify the module as follows:$pip3installsigstore
$python-msigstoreverifytelly.pyHow does telly work (and when doesn't it)?For Python, Telly works by introspecting your module, decorating classes and methods, incrementing a global counter,
and then spawning an async process to send the data to Telly when configured.  Telly works in almost all situations
where Python executes, including in a Jupyter notebook, web app, REPL, script, or a module imported from another
module.  For some patterns where atexit methods are not registered, like multiprocessing, manual decoration may be
required to ensure that data is collected.Telly can also be configured to report data on a periodic basis for long-running jobs or "permanently-running" services
like those that frequently occur in data science, machine learning, and web application environments.  These settings
can be configured by libraries or through theTELLY_TIMERandTELLY_TIMER_INTERVAL_SECenvironment variables.Telly also generally works in situations where signal stuff happens, like when processes are killed or inside an
IDE or debugger like pdb, VS Code, or PyCharm.  By default, Telly will attempt to log the exit signal sent and return
signal handling to any previous handlers.  If you want Telly to only report on normal atexit, you can set theTELLY_EXIT_SIGNAL_ONLYenvironment variable to a truthy value..I'm a user.  Can I see what Telly is logging?Absolutely! Just setTELLY_SHOW_MEto a truthy value liketrueor1and Telly will print what it transmits like this:$ TELLY_SHOW_ME=1 python3 foo.pyHow can I opt in or out of a single project's telemetry?You can opt in or out of a single project's telemetry using the telly CLI methods:Opt in:python3 -m telly optin [project-uuid]Opt out:python3 -m telly optout [project-uuid]These commands edit the.telly_optinfile in your home directory.  You can always edit it manually or
list its contents like this:$ cat ~/.telly_optinHow can I enable or disable Telly completely?If you want to disable or enable Telly for all projects, you can use the commands below:Enable:python3 -m telly enableDisable:python3 -m telly disableThese commands create or removes the.telly_disablefile in your home directory.  You can always
create or delete it manually.Want to learn more?Want to learn more about using Telly? Do you have an idea for new features? Just want to hear our voice?Email us:contact@gotelly.ioJoin ourSlackFollow us onTwitterPlatform CompatibilityWe purposefully designed Telly to be compatible across a very broad range of environments.  Telly uses only standard
Python system libraries that are available in almost all Python implementations.We have tested Telly on the following Python implementations:CPython2.62.73.43.53.63.73.83.93.103.11.0rc2+PyPy3.63.9We have also tested Telly on the following operating systems:UbuntuUbuntu 16.04 x86: No issues in execution on default python3 and python2.Ubuntu 18.04 x86: No issues in execution on default python3 and python2.Ubuntu 20.04 x86: No issues in execution on default python3.Ubuntu 22.04 x86: No issues in execution on default python3.WindowsWindows 10: No issues executing on python 3.10 or anaconda 3.9.MacOSMacOS Catalina (10.15): No issues executing on system python.Alpine3.4:  No issues in execution with python3 or python2.3.16: No issues in execution with python3.AWS LinuxAWS Linux 5 x86: No issues executing on default python2 or python3.AWS Linux 4 x86: No issues executing on default python2 or python3.Red Hat LinuxRed Hat Linux 8 x86: No issues executing on default python2 or python3.Red Hat Linux 6 x86: No issues executing on default python2.SUSE LinuxSUSE Linux 12 x86: No issues executing on default python2 or python3.History0.3.0 (2022-08-19)Initial beta release0.4.0 (2022-08-20)Allow configuration of output level, including complete silenceAllow configuration of zlib compressionAdd reduced timeout and allow configurationInclude API version configuration for future-proofingAllow configuration of default collector region for compliance jurisdiction0.5.0 (2022-08-28)Added async http method for sending data in backgroundEnabled minified and compressedAdded default endpoint for new telly.sh collection infrastructure0.6.0 (2022-08-30)Better signal handlingAdditional configurabilityAbility to track multiple projects simultaneouslyInitial PyPI release0.7.0 (2022-09-01)Fixing Python 2.6 support0.8.0 (2022-09-02)Simplifying module setupAdded UUID4 (default) and machine ID salt optionsAdded TELLY_SHOW_ME0.9.0 (2022-09-18)Fixed issues with signal handling (e.g., inside Pycharm or Flask apps)Fixed signal handling registration bug on Windows (or other non-POSIX)Fixed bug with os.fsync on Python <2.7Improved signal handling setupImproved error handling for libraries that don't like inspect.getmembers()Implemented periodic reporting via TELLY_TIMER/TELLY_TIMER_INTERVAL_SEC for long-running jobs or servicesFixed duplicate reporting where multiple calls could trigger reporting same statsAdded .telly_disable to disable behavior0.9.1 (2022-09-21)Change _INTERVAL to _INTERVAL_SEC for clarity and consistency with JS0.9.2 (2022-10-02)Initial "real" pypi release0.9.3 (2022-11-10)Addingpython3 -m telly optin|optout|enable|disablecommands and updating readmeSwitchinggo()to decorating methods only for type-handling safetyUpdating docs for opt in/out and enable/disable