Installation - Python

2 min read Updated: 11.09.2026

Before you start, create a project in the DockRay panel. Its settings hold the project token - the public identifier that goes into the ingest URL - and the API keys tab is where you generate a private key. The key is shown once, when it is generated: DockRay stores only its hash. If you do not have a project yet, start with Getting Started.

Requirements

Python 3.9 or newer,
an environment with an asyncio event loop - an ASGI application, a script run through asyncio.run(), or a worker with async support,
outbound HTTPS connections allowed.

The package is an asynchronous client: every reporting method is a coroutine, so calling it is always preceded by await. Its only dependency is httpx, installed together with the package.

Installation

bash

pip install dock-ray

Constructing the client

Unlike the PHP integrations, there is no global init() function here - you construct a DockRayClient instance and pass it wherever it is needed:

python

from dock_ray import DockRayClient

client = DockRayClient(
    token="PROJECT_TOKEN",
    private_key="PROJECT_PRIVATE_KEY",
    environment="production",
)

Without a token and a key the constructor does not raise - client.enabled returns False, and every reporting call returns immediately without attempting a network connection. That lets you construct the client unconditionally and leave the credentials out of your local environment. The package itself never reads any server variable - your own code decides where the token and key come from.

Reporting

python

try:
    settle(order)
except Exception as error:
    await client.capture_exception(error)

Every reporting method - capture_exception(), capture_message(), capture_transaction() - returns a bool: True when the panel accepted the event, False for anything else, including an account that has used up its error quota.

Closing the client

Call await client.close() when the application shuts down - it drains pending background tasks and closes the httpx connection pool. Skipping this in a short-lived script can cut a send off midway, before the event has left the process.

The first test

python

import asyncio
from dock_ray import DockRayClient

async def main():
    client = DockRayClient(token="PROJECT_TOKEN", private_key="PROJECT_PRIVATE_KEY")
    await client.capture_message("DockRay control message")
    await client.close()

asyncio.run(main())

The message should appear in the panel under Errors for the project the token points at.