This package provides tracing to Python applications for the collection of distributed tracing and performance metrics in Epsagon.
To install Epsagon, simply run:
pip install -U epsagonThe 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 EPSAGON_METADATA=FALSE
export AUTOWRAPT_BOOTSTRAP=epsagon
<python command>For example:
export EPSAGON_TOKEN=<your-token>
export EPSAGON_APP_NAME=django-prod
export EPSAGON_METADATA=FALSE
export AUTOWRAPT_BOOTSTRAP=epsagon
python app.pyWhen using inside a Dockerfile, you can use ENV instead of export.
You can see the list of auto-tracing supported frameworks
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
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.
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.
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.
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.
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'],
)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.
The following frameworks are supported by Epsagon:
| Framework | Supported Version | Auto-tracing Supported |
|---|---|---|
| AWS Lambda | All |
|
| Step Functions | All | |
| Generic | All | |
| Gunicorn | >=20.0.4 |
|
| Django | >=1.11 |
|
| Flask | >=0.5 |
|
| Tornado | >=4.0 |
|
| fastapi | >=0.62.0 |
|
| Celery | >=4.0.0 |
|
| Azure Functions | >=2.0.0 |
|
| Chalice | >=1.0.0 |
|
| Zappa | >=0.30.0 |
Tracing Lambda functions can be done in three methods:
- Auto-tracing through the Epsagon dashboard.
- Using the
serverless-plugin-epsagonif you're using The Serverless Framework. - Calling the SDK.
Make sure to choose just one of the methods
Calling the SDK is simple:
import epsagon
epsagon.init(
token='<epsagon-token>',
app_name='<app-name-stage>',
metadata_only=False,
)
# Wrap your entry point:
@epsagon.lambda_wrapper
def handle(event, context):
# Your code is hereTracing Step Functions is similar to regular Lambda functions, but the wrapper changes from lambda_wrapper to step_lambda_wrapper:
import epsagon
epsagon.init(
token='<epsagon-token>',
app_name='<app-name-stage>',
metadata_only=False,
)
# Wrap your entry point:
@epsagon.step_lambda_wrapper
def handle(event, context):
# Your code is hereTracing Django application can be done in two methods:
- Auto-tracing using the environment variable.
- Calling the SDK.
Calling the SDK is simple, and should be done in your main settings.py file where the application is being initialized:
import epsagon
epsagon.init(
token='<epsagon-token>',
app_name='<app-name-stage>',
metadata_only=False,
)Tracing Flask application can be done in two methods:
- Auto-tracing using the environment variable.
- Calling the SDK.
Calling the SDK is simple, and should be done in your main py file where the application is being initialized:
import epsagon
epsagon.init(
token='<epsagon-token>',
app_name='<app-name-stage>',
metadata_only=False,
)Tracing Tornado application can be done in two methods:
- Auto-tracing using the environment variable.
- Calling the SDK.
Calling the SDK is simple, and should be done in your main py file where the application is being initialized:
import epsagon
epsagon.init(
token='<epsagon-token>',
app_name='<app-name-stage>',
metadata_only=False,
)Tracing fastapi application can be done in two methods:
- Auto-tracing using the environment variable.
- Calling the SDK.
Calling the SDK is simple, and should be done in your main py file where the application is being initialized:
import epsagon
epsagon.init(
token='<epsagon-token>',
app_name='<app-name-stage>',
metadata_only=False,
)Tracing Celery consumer can be done in two methods:
- Auto-tracing using the environment variable.
- Calling the SDK.
Calling the SDK is simple, and should be done in your main py file where the consumer is being initialized:
import epsagon
epsagon.init(
token='epsagon-token',
app_name='app-name-stage',
metadata_only=False,
)Tracing Gunicorn application can be done in two methods:
- Auto-tracing using the environment variable.
- Calling the SDK.
Calling the SDK is simple, and should be done in your main py file where the application is being initialized:
import epsagon
epsagon.init(
token='<epsagon-token>',
app_name='<app-name-stage>',
metadata_only=False,
)Tracing Azure Functions can be done in the following method:
import azure.functions as func
import epsagon
epsagon.init(
token='epsagon-token',
app_name='app-name-stage',
metadata_only=False,
)
@epsagon.azure_wrapper
def main(req):
return func.HttpResponse('Success')Tracing Chalice applications running on Lambda functions can be done by:
from chalice import Chalice
import epsagon
epsagon.init(
token='epsagon-token',
app_name='app-name-stage',
metadata_only=False
)
app = Chalice(app_name='hello-world')
# Your code is here
app = epsagon.chalice_wrapper(app)Tracing web applications running on Lambda functions using Zappa can be done by:
from zappa.handler import lambda_handler
import epsagon
epsagon.init(
token='epsagon-token',
app_name='app-name-stage',
metadata_only=False
)
# Your code is here
epsagon_handler = epsagon.lambda_wrapper(lambda_handler)And in your zappa_settings.json file include the following:
{
"lambda_handler": "module.path_to.epsagon_handler"
}For any tracing, you can simply use the generic Epsagon wrapper using the following example:
import epsagon
epsagon.init(
token='epsagon-token',
app_name='app-name-stage',
metadata_only=False,
)
# Wrap your entry point:
@epsagon.python_wrapper(name='my-resource')
def main(params):
# Your code is hereEpsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.
| Library | Supported Version |
|---|---|
| logging | Fully supported |
| urllib | Fully supported |
| urllib3 | Fully 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 |
| greengrasssdk | >=1.4.0 |
| SQLAlchemy | >=1.2.0,<1.4.0 |
| kafka-python | >=1.4.0 |
Advanced options can be configured as a parameter to the init() method or as environment variables.
| Parameter | Environment Variable | Type | Default | Description |
|---|---|---|---|---|
| token | EPSAGON_TOKEN | String | - | Epsagon account token |
| app_name | EPSAGON_APP_NAME | String | Application |
Application name that will be set for traces |
| metadata_only | EPSAGON_METADATA | Boolean | True |
Whether to send only the metadata (True) or also the payloads (False) |
| use_ssl | EPSAGON_SSL | Boolean | True |
Whether to send the traces over HTTPS SSL or not |
| collector_url | EPSAGON_COLLECTOR_URL | String | - | The address of the trace collector to send trace to |
| keys_to_ignore | EPSAGON_IGNORED_KEYS | List | - | List of keys names to be removed from the trace |
| keys_to_allow | EPSAGON_ALLOWED_KEYS | List | - | List of keys names to be included from the trace |
| ignored_endpoints | EPSAGON_ENDPOINTS_TO_IGNORE | List | - | List of endpoints to ignore from tracing (for example /healthcheck |
| url_patterns_to_ignore | EPSAGON_URLS_TO_IGNORE | List | [] |
Array of URL patterns to ignore the calls |
| debug | EPSAGON_DEBUG | Boolean | False |
Enable debug prints for troubleshooting |
| disable_timeout_send | EPSAGON_DISABLE_ON_TIMEOUT | Boolean | False |
Disable timeout detection in Lambda functions |
| split_on_send | EPSAGON_SPLIT_ON_SEND | Boolean | False |
Split the trace into multiple chunks to support large traces |
| propagate_lambda_id | EPSAGON_PROPAGATE_LAMBDA_ID | Boolean | False |
Insert Lambda request ID into the response payload |
| logging_tracing_enabled | EPSAGON_LOGGING_TRACING_ENABLED | Boolean | True |
Add Epsagon Log Id to all logging messages |
| step_dict_output_path | EPSAGON_STEPS_OUTPUT_PATH | List | None |
Path in the result dict to append the Epsagon steps data |
| - | EPSAGON_HTTP_ERR_CODE | Integer | 500 |
The minimum number of an HTTP response status code to treat as an error |
| - | EPSAGON_SEND_TIMEOUT_SEC | Float | 1.0 |
The timeout duration in seconds to send the traces to the trace collector |
| - | EPSAGON_DISABLE_LOGGING_ERRORS | Boolean | False |
Disable the automatic capture of error messages into logging |
| - | EPSAGON_IGNORE_FLASK_RESPONSE | Boolean | False |
Disable the automatic capture of Flask response data |
| - | EPSAGON_SKIP_HTTP_RESPONSE | Boolean | False |
Disable the automatic capture of http client response data |
| - | DISABLE_EPSAGON | Boolean | False |
A flag to completely disable Epsagon (can be used for tests or locally) |
| - | DISABLE_EPSAGON_PATCH | Boolean | False |
Disable the library patching (instrumentation) |
| - | EPSAGON_LAMBDA_TIMEOUT_THRESHOLD_MS | Integer | 200 |
The threshold in millieseconds to send the trace before a Lambda timeout occurs |
| - | EPSAGON_PAYLOADS_TO_IGNORE | List | - | Array of dictionaries to not instrument. Example: '[{"source": "serverless-plugin-warmup"}]' |
| - | EPSAGON_REMOVE_EXCEPTION_FRAMES | Boolean | False |
Disable the automatic capture of exception frames data (Python 3) |
| - | EPSAGON_FASTAPI_ASYNC_MODE | Boolean | False |
Enable capturing of Fast API async endpoint handlers calls(Python 3) |
If you have any issue around using the library or the product, please don't hesitate to:
- Use the documentation.
- Use the help widget inside the product.
- Open an issue in GitHub.
If you encounter a bug with the Epsagon library for Python, we want to hear about it.
When opening a new issue, please provide as much information about the environment:
- Library version, Python runtime version, dependencies, etc.
- Snippet of the usage.
- A reproducible example can really help.
The GitHub issues are intended for bug reports and feature requests. For help and questions about Epsagon, use the help widget inside the product.
Provided under the MIT license. See LICENSE for details.
Copyright 2020, Epsagon