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:
Framework | Supported Version | Auto-tracing Supported |
---|---|---|
AWS Lambda | All | Yes, through the dashboard |
Step Functions | All | No |
Generic | All | No |
Gunicorn | >=2.0 | Yes |
Django | >=1.11 | Yes |
Flask | >=0.5 | Yes |
Tornado | >=4.0 | Yes |
Celery | >=4.0.0 | Yes |
Azure Functions | >=2.0.0 | No |
Chalice | >=1.0.0 | No |
Zappa | >=0.30.0 | No |
Integrations
Epsagon 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 |
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.
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 |
- | 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 | 0.2 | 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 |
- | 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) |
Updated 3 months ago