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 define environment variables:

• EPSAGON_TOKEN
• EPSAGON_APP_NAME
• AUTOWRAPT_BOOTSTRAP

For example:

export EPSAGON_TOKEN=<EPSAGON-TOKEN>
export EPSAGON_APP_NAME=<APP-NAME-STAGE>
export AUTOWRAPT_BOOTSTRAP=epsagon

python <APP-NAME>

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

ENV EPSAGON_TOKEN=<EPSAGON-TOKEN>
ENV EPSAGON_APP_NAME=<APP-NAME-STAGE>
ENV AUTOWRAPT_BOOTSTRAP=epsagon

CMD python <APP-NAME>

You can see the list of auto-tracing supported frameworks

Calling the SDK

Another alternative is to initialize the module with epsagon.init().
epsagon.init() takes parameters:

• token: str
• app_name: str
• [optional] metadata_only: bool (Default to True)
• [optional] keys_to_allow: [str]
• [optional] keys_to_ignore: [str]
• [optional] ignored_endpoints: [str]
• [optional] url_patterns_to_ignore: [str]

For example:

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. These tags follow specific metrics in the form of key-value pairs.

Tags must be labeled in order to be followed. Simply label a key-value pair.

epsagon.label(<KEY>, <VALUE>)
epsagon.label('user_id', user_id)

Valid types are string, bool, int and float.

In some frameworks tagging can be done in different ways.

Measuring Function Duration

You can measure internal functions duration by using the @epsagon.measure decorator. For example:

@epsagon.measure
def heavy_calculation():
    # code ...

This will ship another metric label to epsagon where the key=heavy_calculation_duration and the value will be the actual duration, in seconds.
You'll be able to see this label in the trace search, visualize it over time, and generate alerts based on this metric.

Custom Errors

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

try:
    # error raised
    1 / 0
except Exception as ex:
    epsagon.error(ex)
   
# or manually
epsagon.error(Exception('Custom Error Raised'))

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

Filter Sensitive Data

keys_to_allow parameter allows specific keys to appear in trace.
keys_to_ignore parameter contains keys wished to be ignored.
url_patterns_to_ignore paramater is used to ignore outgoing HTTP/S requests made to specific domains.

Both keys_to_ignore and keys_to_allow can contain strings, regular expressions, and predicate functions. Loose matches are performed on strings, so that First Name matches first_name.

epsagon.init(
    # ...
    keys_to_allow=['Request Data', 'Status_Code'],
    keys_to_ignore=['password', 'user_name'],
    url_patterns_to_ignore=['example.com', 'stackoverflow.com'],
)

Ignore Endpoints

Conversely, you can ignore incoming requests from specific endpoints.

epsagon.init(
    # ...
    ignored_endpoints=['/healthcheck'] 
)

Trace URL

You can get the Epsagon dashboard URL for the current trace, using the following:

import epsagon

# Inside some endpoint or function
print('Epsagon trace URL:', epsagon.get_trace_url())

This can be useful to have an easy access the trace from different platforms.

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.