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

export EPSAGON_TOKEN=<EPSAGON-TOKEN>
export EPSAGON_APP_NAME=<APP-NAME-STAGE>
export AUTOWRAPT_BOOTSTRAPS=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:

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:

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.0No
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
SQLAlchemy>=1.2.0

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 2 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.