Epsagon Documentation

Welcome to the Epsagon Documentation. You'll find comprehensive guides and documentation to help you start working with our product as quickly as possible. Let's jump right in!

Get Started

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:

FrameworkSupported VersionAuto-tracing Supported
AWS LambdaAllYes, through the dashboard
Step FunctionsAllNo
GenericAllNo
Gunicorn>=2.0Yes
Django>=1.11Yes
Flask>=0.5Yes
Tornado>=4.0Yes
Celery>=4.0.0Yes
Azure Functions>=2.0.0
  • - [ ]
Chalice>=1.0.0No
Zappa>=0.30.0No

Integrations

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

LibrarySupported Version
loggingFully supported
urllibFully supported
urllib3Fully supported
requests>=2.0.0
httplib2>=0.9.2
redis>=2.10.0
pymongo>=3.0.0
pynamodb>=2.0.0
PyMySQL>=0.7.0
MySQLdb>=1.0.0
psycopg2>=2.2.0
pg8000>=1.9.0
botocore (boto3)>=1.4.0
azure.cosmos>=4.0.0
celery>=4.0.0
grpc>=0.3-10

Configuration

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

ParameterEnvironment VariableTypeDefaultDescription
tokenEPSAGON_TOKENString-Epsagon account token
app_nameEPSAGON_APP_NAMEStringApplicationApplication name that will be set for traces
metadata_onlyEPSAGON_METADATABooleanTrueWhether to send only the metadata (True) or also the payloads (False)
use_sslEPSAGON_SSLBooleanTrueWhether to send the traces over HTTPS SSL or not
collector_urlEPSAGON_COLLECTOR_URLString-The address of the trace collector to send trace to
keys_to_ignoreEPSAGON_IGNORED_KEYSList-List of keys names to be removed from the trace
keys_to_allowEPSAGON_ALLOWED_KEYSList-List of keys names to be included from the trace
ignored_endpointsEPSAGON_ENDPOINTS_TO_IGNOREList-List of endpoints to ignore from tracing (for example /healthcheck
url_patterns_to_ignoreEPSAGON_URLS_TO_IGNOREList[]Array of URL patterns to ignore the calls
debugEPSAGON_DEBUGBooleanFalseEnable debug prints for troubleshooting
disable_timeout_sendEPSAGON_DISABLE_ON_TIMEOUTBooleanFalseDisable timeout detection in Lambda functions
split_on_sendEPSAGON_SPLIT_ON_SENDBooleanFalseSplit the trace into multiple chunks to support large traces
propagate_lambda_idEPSAGON_PROPAGATE_LAMBDA_IDBooleanFalseInsert Lambda request ID into the response payload
-EPSAGON_HTTP_ERR_CODEInteger500The minimum number of an HTTP response status code to treat as an error
-EPSAGON_SEND_TIMEOUT_SECFloat0.2The timeout duration in seconds to send the traces to the trace collector
-EPSAGON_DISABLE_LOGGING_ERRORSBooleanfalseDisable the automatic capture of error messages into logging
-DISABLE_EPSAGONBooleanFalseA flag to completely disable Epsagon (can be used for tests or locally)
-DISABLE_EPSAGON_PATCHBooleanfalseDisable the library patching (instrumentation)

Updated 17 days ago


Python


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.