humbug 0.1.8

Humbug: Do you build developer tools? Humbug helps you know your users.

Humbug Python

The Humbug Python library.

Installation

Using pip

pip install humbug

From source

Clone this repository and enter this directory. Make sure you are in your desired Python environment and then run:

python setup.py install

Integration

To add Humbug to your project, first create a Bugout access token and journal following these instructions.

All reports are generated (and published) by a Humbug reporter. Create a file called report.py somewhere in your project and paste the following code in there:

from humbug.consent import HumbugConsent
from humbug.report import Reporter

consent = HumbugConsent(True)
reporter = Reporter(
    "<name of your project>",
    consent,
    bugout_token="<your Bugout access token>",
    bugout_journal_id="<your Bugout journal ID>",
)

Now, anywhere in your code, import this report object and use it to publish reports to your Bugout journal.

For example, to report an error:

def do_something(*args):
    try:
        something(*args)
    except Exception as e:
        reporter.error_report(e)

If you want to report system information when a user imports your package, put the following code in your __init__.py:

from .report import reporter

reporter.system_report()

All reports have three parameters: title, tags, content. You can create a custom report using the humbug.report.Report class, and you can publish it to your knowledge base using the humbug.report.Reporter.publish method:

from humbug.report import Report

report = Report(
    title="<title of report>",
    tags=["report:custom", "test"],
    content="# Custom report\nThis is an example of a custom report, with markdown content.\n",
)
reporter.publish(report)

By default, Humbug publishes all reports asynchronously and in the background. If you would like to publish reports synchronously, set wait=True on error_report, system_report, or publish.

For example, to publish the error report from above synchronously:

def do_something(*args):
    try:
        something(*args)
    except Exception as e:
        reporter.error_report(e, wait=True)

Consent

Humbug cares deeply about consent. The innocuous HumbugConsent from the snippet above supports a wide range of consent flows.

Opting in with environment variables

For example, if you would like your users to be able to opt in by setting an environment variable MY_APP_CONSENT=true:

from humbug.consent import environment_variable_opt_in, HumbugConsent
from humbug.report import Reporter

consent = HumbugConsent(environment_variable_opt_in("MY_APP_CONSENT", ["true"]))
reporter = Reporter(
    "<name of your project>",
    consent,
    bugout_token="<your Bugout access token>",
    bugout_journal_id="<your Bugout journal ID>",
)

If you use this configuration, unless your user uses your tool with MY_APP_CONSENT=true, no reports will ever get sent to your knowledge base.

Opting out with environment variables

If, like homebrew, you would like users to be able to opt out by setting an environment variable MY_APP_NO_CONSENT=1:

from humbug.consent import environment_variable_opt_out, HumbugConsent
from humbug.report import Reporter

consent = HumbugConsent(environment_variable_opt_out("MY_APP_NO_CONSENT", ["1"]))
reporter = Reporter(
    "<name of your project>",
    consent,
    bugout_token="<your Bugout access token>",
    bugout_journal_id="<your Bugout journal ID>",
)

In this case, reports are sent by default unless the user sets MY_APP_NO_CONSENT=1 in which case reports will never be sent.

Composing consent mechanisms

Humbug allows you to combine multiple consent mechanisms. For example:

from humbug.consent import environment_variable_opt_in, environment_variable_opt_out, HumbugConsent
from humbug.report import Reporter

consent = HumbugConsent(
    environment_variable_opt_in("MY_APP_CONSENT", ["true"]),
    environment_variable_opt_out("MY_APP_NO_CONSENT", ["1"]),
)
reporter = Reporter(
    "<name of your project>",
    consent,
    bugout_token="<your Bugout access token>",
    bugout_journal_id="<your Bugout journal ID>",
)

If your users do not set MY_APP_CONSENT or give it a value other than true, Humbug won't even bother to send you any reports. If MY_APP_CONSENT is indeed set to true, but the user has set MY_APP_NO_CONSENT=1, then again no reports will get sent back.

On the other hand, if the user has set MY_APP_CONSENT=true and left MY_APP_NO_CONSENT unset or set to a value other than 1, Humbug will send you any reports you have configured.

Example: activeloopai/Hub

This pull request shows how Activeloop integrated Humbug into their popular Hub tool.

This example shows how to use Humbug to record consent in a configuration file that the user can modify at will. It also shows how to add custom tags to your Humbug reports.