This package provides tracing to Python applications for the collection of distributed tracing and performance metrics in Epsagon.

📘

Open source repository

This is an open-source project which can be found at our GitHub repository.

Installation

To install Epsagon, simply run:

pip install -U epsagon

Usage

Auto-tracing

The simplest way to get started is to run your python command with the following environment variable:

export EPSAGON_TOKEN=epsagon-token
export EPSAGON_APP_NAME=app-name-stage
export AUTOWRAPT_BOOTSTRAP=epsagon
python command

For example:

export EPSAGON_TOKEN=your-token
export EPSAGON_APP_NAME=django-prod
export AUTOWRAPT_BOOTSTRAP=epsagon
python app.py

When using inside a Dockerfile, you can use ENV instead of export.

You can see the list of auto-tracing supported frameworks

Calling the SDK

Another simple alternative is to copy the snippet into your code:

import epsagon
epsagon.init(
    token='epsagon-token',
    app_name='app-name-stage',
    metadata_only=False,
)

To run on your framework please refer to supported frameworks

Tagging Traces

You can add custom tags to your traces, for easier filtering and aggregations.

Add the following call inside your code:

epsagon.label('key', 'value')
epsagon.label('user_id', user_id)

You can also use it to ship custom metrics:

epsagon.label('key', 'metric')
epsagon.label('items_in_cart', items_in_cart)

Valid types are string, bool, int and float.

In some frameworks tagging can be done in different ways.

Custom Errors

You can set a trace as an error (although handled correctly) to get an alert or just follow it on the dashboard.

Add the following call inside your code:

try:
    fail = 1 / 0
except Exception as ex:
    epsagon.error(ex)

# Or manually specify Exception object
epsagon.error(Exception('My custom error'))

In some frameworks custom errors can be declared in different ways.

Filter Sensitive Data

You can pass a list of sensitive properties and hostnames and they will be filtered out from the traces:

epsagon.init(
    token='epsagon-token',
    app_name='app-name-stage',
    metadata_only=False,
    keys_to_ignore=['password', 'user_name'],
    url_patterns_to_ignore=['example.com', 'auth.com']
)

Or specify keys that are allowed:

epsagon.init(
    token='epsagon-token',
    app_name='app-name-stage',
    metadata_only=False,
    keys_to_allow=['Request Data', 'Status_Code'],
)

The keys_to_ignore and keys_to_allow properties can contain strings (will perform a loose match, so that First Name also matches first_name).
Also, you can set url_patterns_to_ignore to ignore HTTP calls to specific domains.

Ignore Endpoints

You can ignore certain incoming requests by specifying endpoints:

epsagon.init(
    token='epsagon-token',
    app_name='app-name-stage',
    metadata_only=False,
    ignored_endpoints=['/healthcheck'],
)

Frameworks

The following frameworks are supported by Epsagon:

Integrations

Epsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.

Configuration

Advanced options can be configured as a parameter to the init() method or as environment variables.