> For the complete documentation index, see [llms.txt](https://docs.reo.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reo.dev/integrations/input-sources/developer-insights/python.md).

# Python

When developers use your Python package, it signals **real product usage**. With Reo, you can identify and monitor usage of your PyPI packages.

{% hint style="info" %}
Python tracking is **not automatic on install**. You add a single function call to your package, and it fires whenever you choose: at import, at startup, or on a key product event.
{% endhint %}

***

### How it works

1. A developer installs and runs your package
2. Your code calls <mark style="color:red;">`log_event()`</mark> at the point you chose
3. The event is sent to **your telemetry endpoint**, a hostname on your own domain such as <mark style="color:red;">`packages.<your_domain>.com`</mark>
4. That hostname points to Reo's telemetry endpoint through a CNAME record, so the event arrives at Reo
5. Reo processes it and surfaces it as a **developer activity signal** in your dashboard

***

### Step 1: Send your PyPI package URL to Reo

Share your package link with the Reo team so we can configure tracking on our side:

```
https://pypi.org/project/your-package
```

{% hint style="warning" %}
Your events will not appear in the dashboard until this is done. Send the package details before you start implementing.
{% endhint %}

***

### Step 2: Create the product usage metric

* From the left navigation menu, click on **Settings** > select **Configurations**

<figure><img src="https://2705882080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx46P5sAHxDG7PqOdVLxI%2Fuploads%2FRF9OpZb7mVbM0dujLK3r%2FScreenshot%202026-10-06%20at%202.49.11%E2%80%AFPM.png?alt=media&amp;token=07aedfce-0201-4803-95f5-3e79d1b75fea" alt=""><figcaption></figcaption></figure>

* Spot the **Product usage metrics** card and click **Configure**

<figure><img src="https://2705882080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx46P5sAHxDG7PqOdVLxI%2Fuploads%2FqRuFuo0vdsZozY9jHeXE%2FScreenshot%202026-10-06%20at%202.50.13%E2%80%AFPM.png?alt=media&amp;token=60efc661-1276-4404-a653-a1334c80b864" alt=""><figcaption></figcaption></figure>

* Click **Create New**&#x20;

<figure><img src="https://2705882080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx46P5sAHxDG7PqOdVLxI%2Fuploads%2Fc3OojdViiQiq0bOHE2XS%2FScreenshot%202026-10-06%20at%202.51.39%E2%80%AFPM.png?alt=media&amp;token=80f405fd-c115-4ade-ae4f-d37b58d20c7a" alt=""><figcaption></figcaption></figure>

* **Name the metric** <mark style="color:red;">`pypi_download`</mark>&#x20;
* Choose the **Mode as Single**&#x20;

<figure><img src="https://2705882080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx46P5sAHxDG7PqOdVLxI%2Fuploads%2Frn4uCZCCEwunRkW625Ka%2FScreenshot%202026-10-07%20at%201.04.24%E2%80%AFPM.png?alt=media&amp;token=55569821-ffeb-4775-97a9-1286ce287b1d" alt=""><figcaption></figcaption></figure>

* Additionally, you can also add meta parameters

{% hint style="info" %}
Meta parameters help you capture additional data for the corresponding metric.
{% endhint %}

* Against the 'Meta parameters' for your metric click **Add new** > provide a name for the parameter and choose the Data type

<figure><img src="https://2705882080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx46P5sAHxDG7PqOdVLxI%2Fuploads%2FARZfRxPKN1bZClc3HBTs%2FScreenshot%202026-10-07%20at%201.06.33%E2%80%AFPM.png?alt=media&amp;token=67ee146b-e748-40f5-a7f3-d0f48a8be763" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2705882080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx46P5sAHxDG7PqOdVLxI%2Fuploads%2F8oLsYiOkLrdl1DYMC8Ei%2FScreenshot%202026-10-07%20at%201.00.56%E2%80%AFPM.png?alt=media&amp;token=28fb7f96-a84c-4425-abb3-23ee3e1d8b03" alt="" width="375"><figcaption></figcaption></figure>

* Once you've configured the meta parameters and metric, click **Save**

{% hint style="success" %}
**Reo records your events against this metric and surfaces them as signals.**
{% endhint %}

<figure><img src="https://2705882080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx46P5sAHxDG7PqOdVLxI%2Fuploads%2FHel472RXAyJJ518rjomX%2FScreenshot%202026-10-07%20at%201.08.50%E2%80%AFPM.png?alt=media&amp;token=1032322a-fce1-4efa-b153-c1fac0c72dfb" alt=""><figcaption></figcaption></figure>

***

### Step 3: Point your telemetry domain at Reo

Telemetry is sent to a hostname on your own domain. Add a CNAME record pointing it at Reo's telemetry endpoint:

| DNS record type | Host / Name                                                  | Value (points to)                                   |
| --------------- | ------------------------------------------------------------ | --------------------------------------------------- |
| CNAME           | <mark style="color:red;">`packages.<your_domain>.com`</mark> | <mark style="color:red;">`telemetry.reo.dev`</mark> |

{% hint style="info" %}
Wait for the record to propagate before moving on.
{% endhint %}

***

### Step 4: Install the SDK

```bash
pip install reo-census
```

***

### Step 5: Add it to your dependencies

Add <mark style="color:red;">`reo-census`</mark> to your package's dependency file (<mark style="color:red;">`requirements.txt`</mark>, <mark style="color:red;">`pyproject.toml`</mark>, or <mark style="color:red;">`Pipfile`</mark>) so it installs alongside your package.

***

### Step 6: Initialise the logger

Point <mark style="color:red;">`endpoint_url`</mark> at the hostname you set up in Step 3, including the <mark style="color:red;">`/data`</mark> path:

```python
from reo_census import ReoEventLogger

logger = ReoEventLogger(
    package_name="your-package",
    package_version="1.0.0",
    endpoint_url="https://packages.<your_domain>.com/data",
)
```

Alternatively, set it at runtime with no code change:

```bash
export PACKAGE_TRACKER_ENDPOINT="https://packages.<your_domain>.com/data"
```

### Step 7: Call <mark style="color:red;">`log_event()`</mark> where usage happens

```python
logger.log_event()
```

Put the call wherever it reflects real usage: application startup, CLI execution, package initialisation, or a meaningful product event.

{% hint style="warning" %}
**CLI tools and short-lived scripts:** <mark style="color:red;">`log_event()`</mark> is non-blocking by default and runs in a background thread. A short-lived process can exit before that thread finishes, and the event is lost. Use <mark style="color:red;">`logger.log_event(blocking=True)`</mark> in those cases.
{% endhint %}

***

### Step 8: Verify

Run your package, then open your Reo dashboard and check the <mark style="color:red;">`pypi_download`</mark> metric. You should see:

* The package name and version in use
* Event timestamp and caller IP, recorded by Reo on arrival
* Any custom properties you chose to send

***

## Optional configuration

### Sending directly to Reo instead of your own domain

If you skip Step 3, leave <mark style="color:red;">`endpoint_url`</mark> unset and the SDK falls back to Reo's endpoint:

```
https://telemetry.reo.dev/data
```

Events are recorded the same way. You lose only the benefit of telemetry travelling under your own brand and domain.

### Adjusting the timeout

<mark style="color:red;">`timeout`</mark> controls the per-request socket timeout in seconds, and defaults to <mark style="color:red;">`3.0`</mark>. Keep it low so telemetry never holds up your users.

```python
logger = ReoEventLogger(
    package_name="your-package",
    package_version="1.0.0",
    endpoint_url="https://packages.<your_domain>.com/data",
    timeout=3.0,
)
```

### Defaults

| Option                                         | Default                                                          |
| ---------------------------------------------- | ---------------------------------------------------------------- |
| <mark style="color:red;">`endpoint_url`</mark> | <mark style="color:red;">`https://telemetry.reo.dev/data`</mark> |
| <mark style="color:red;">`timeout`</mark>      | <mark style="color:red;">`3.0`</mark> seconds                    |
| Blocking mode                                  | Non-blocking (the request runs in a background thread)           |

***

## How your users opt out

Once you add <mark style="color:red;">`log_event()`</mark>, tracking is on by default. Your users can disable it by setting a single environment variable:

| Variable                                       | Values                                                                                                                                   | Effect                     |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| <mark style="color:red;">`DO_NOT_TRACK`</mark> | <mark style="color:red;">`1`</mark>, <mark style="color:red;">`true`</mark>, or <mark style="color:red;">`yes`</mark> (case-insensitive) | Disables all event sending |

{% hint style="info" %}
Document this variable in your project README so your users know how to opt out.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.reo.dev/integrations/input-sources/developer-insights/python.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
