Package: epsagon
Epsagon Tracing for PythonThis package provides tracing to Python applications for the collection of distributed tracing and performance metrics inEpsagon.ContentsInstallationUsageAuto-tracingCalling the SDKTagging TracesMeasuring Function DurationCustom ErrorsFilter Sensitive DataIgnore EndpointsTrace URLFrameworksIntegrationsConfigurationGetting HelpOpening IssuesLicenseInstallationTo install Epsagon, simply run:pipinstall-UepsagonUsageAuto-tracingThe simplest way to get started is to run your python command with the following environment variable:exportEPSAGON_TOKEN=<epsagon-token>exportEPSAGON_APP_NAME=<app-name-stage>exportEPSAGON_METADATA=FALSEexportAUTOWRAPT_BOOTSTRAP=epsagon
<pythoncommand>For example:exportEPSAGON_TOKEN=<your-token>exportEPSAGON_APP_NAME=django-prodexportEPSAGON_METADATA=FALSEexportAUTOWRAPT_BOOTSTRAP=epsagon
pythonapp.pyWhen using inside aDockerfile, you can useENVinstead ofexport.You can see the list of auto-tracingsupported frameworksCalling the SDKAnother simple alternative is to copy the snippet into your code:importepsagonepsagon.init(token='epsagon-token',app_name='app-name-stage',metadata_only=False,)To run on your framework please refer tosupported frameworksTagging TracesYou 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 arestring,bool,intandfloat.
In someframeworkstagging can be done in different ways.Measuring Function DurationYou can measure internal functions duration by using the@epsagon.measuredecorator. For example:@epsagon.measuredefheavy_calculation():# Code...This will ship another metric label to epsagon where thekey=heavy_calculation_durationand 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 ErrorsYou 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/0exceptExceptionasex:epsagon.error(ex)# Or manually specify Exception objectepsagon.error(Exception('My custom error'))In someframeworkscustom errors can be declared in different ways.Filter Sensitive DataYou 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'],)Thekeys_to_ignoreandkeys_to_allowproperties can contain strings (will perform a loose match, so thatFirst Namealso matchesfirst_name).
Also, you can seturl_patterns_to_ignoreto ignore HTTP calls to specific domains.Ignore EndpointsYou can ignore certain incoming requests by specifying endpoints:epsagon.init(token='epsagon-token',app_name='app-name-stage',metadata_only=False,ignored_endpoints=['/healthcheck'],)Trace URLYou can get the Epsagon dashboard URL for the current trace, using the following:importepsagon# Inside some endpoint or functionprint('Epsagon trace URL:',epsagon.get_trace_url())This can be useful to have an easy access the trace from different platforms.FrameworksThe following frameworks are supported by Epsagon:FrameworkSupported VersionAuto-tracing SupportedAWS LambdaAll- [x] (Through the dashboard only)Step FunctionsAll- [ ]GenericAll- [ ]Gunicorn>=20.0.4- [x]Django>=1.11- [x]Flask>=0.5- [x]Tornado>=4.0- [x]fastapi>=0.62.0- [x]Celery>=4.0.0- [x]Azure Functions>=2.0.0- [ ]Chalice>=1.0.0- [ ]Zappa>=0.30.0- [ ]AWS LambdaTracing Lambda functions can be done in three methods:Auto-tracing through the Epsagon dashboard.Using theserverless-plugin-epsagonif you're using The Serverless Framework.Calling the SDK.Make sure to choose just one of the methodsCalling the SDK is simple:importepsagonepsagon.init(token='<epsagon-token>',app_name='<app-name-stage>',metadata_only=False,)# Wrap your entry point:@epsagon.lambda_wrapperdefhandle(event,context):# Your code is hereStep FunctionsTracing Step Functions is similar to regular Lambda functions, but the wrapper changes fromlambda_wrappertostep_lambda_wrapper:importepsagonepsagon.init(token='<epsagon-token>',app_name='<app-name-stage>',metadata_only=False,)# Wrap your entry point:@epsagon.step_lambda_wrapperdefhandle(event,context):# Your code is hereDjangoTracing Django application can be done in two methods:Auto-tracingusing the environment variable.Calling the SDK.Calling the SDK is simple, and should be done in your mainsettings.pyfile where the application is being initialized:importepsagonepsagon.init(token='<epsagon-token>',app_name='<app-name-stage>',metadata_only=False,)FlaskTracing Flask application can be done in two methods:Auto-tracingusing the environment variable.Calling the SDK.Calling the SDK is simple, and should be done in your mainpyfile where the application is being initialized:importepsagonepsagon.init(token='<epsagon-token>',app_name='<app-name-stage>',metadata_only=False,)TornadoTracing Tornado application can be done in two methods:Auto-tracingusing the environment variable.Calling the SDK.Calling the SDK is simple, and should be done in your mainpyfile where the application is being initialized:importepsagonepsagon.init(token='<epsagon-token>',app_name='<app-name-stage>',metadata_only=False,)fastapiTracing fastapi application can be done in two methods:Auto-tracingusing the environment variable.Calling the SDK.Calling the SDK is simple, and should be done in your mainpyfile where the application is being initialized:importepsagonepsagon.init(token='<epsagon-token>',app_name='<app-name-stage>',metadata_only=False,)CeleryTracing Celery consumer can be done in two methods:Auto-tracingusing the environment variable.Calling the SDK.Calling the SDK is simple, and should be done in your mainpyfile where the consumer is being initialized:importepsagonepsagon.init(token='epsagon-token',app_name='app-name-stage',metadata_only=False,)GunicornTracing Gunicorn application can be done in two methods:Auto-tracingusing the environment variable.Calling the SDK.Calling the SDK is simple, and should be done in your mainpyfile where the application is being initialized:importepsagonepsagon.init(token='<epsagon-token>',app_name='<app-name-stage>',metadata_only=False,)Azure FunctionsTracing Azure Functions can be done in the following method:importazure.functionsasfuncimportepsagonepsagon.init(token='epsagon-token',app_name='app-name-stage',metadata_only=False,)@epsagon.azure_wrapperdefmain(req):returnfunc.HttpResponse('Success')ChaliceTracing Chalice applications running on Lambda functions can be done by:fromchaliceimportChaliceimportepsagonepsagon.init(token='epsagon-token',app_name='app-name-stage',metadata_only=False)app=Chalice(app_name='hello-world')# Your code is hereapp=epsagon.chalice_wrapper(app)ZappaTracing web applications running on Lambda functions using Zappa can be done by:fromzappa.handlerimportlambda_handlerimportepsagonepsagon.init(token='epsagon-token',app_name='app-name-stage',metadata_only=False)# Your code is hereepsagon_handler=epsagon.lambda_wrapper(lambda_handler)And in yourzappa_settings.jsonfile include the following:{"lambda_handler":"module.path_to.epsagon_handler"}GenericFor any tracing, you can simply use the generic Epsagon wrapper using the following example:importepsagonepsagon.init(token='epsagon-token',app_name='app-name-stage',metadata_only=False,)# Wrap your entry point:@epsagon.python_wrapper(name='my-resource')defmain(params):# Your code is hereIntegrationsEpsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.LibrarySupported VersionloggingFully supportedurllibFully supportedurllib3Fully supportedrequests>=2.0.0httplib2>=0.9.2redis>=2.10.0pymongo>=3.0.0pynamodb>=2.0.0PyMySQL>=0.7.0MySQLdb>=1.0.0psycopg2>=2.2.0pg8000>=1.9.0botocore (boto3)>=1.4.0azure.cosmos>=4.0.0celery>=4.0.0greengrasssdk>=1.4.0SQLAlchemy>=1.2.0,<1.4.0kafka-python>=1.4.0ConfigurationAdvanced options can be configured as a parameter to the init() method or as environment variables.ParameterEnvironment VariableTypeDefaultDescriptiontokenEPSAGON_TOKENString-Epsagon account tokenapp_nameEPSAGON_APP_NAMEStringApplicationApplication name that will be set for tracesmetadata_onlyEPSAGON_METADATABooleanTrueWhether to send only the metadata (True) or also the payloads (False)use_sslEPSAGON_SSLBooleanTrueWhether to send the traces over HTTPS SSL or notcollector_urlEPSAGON_COLLECTOR_URLString-The address of the trace collector to send trace tokeys_to_ignoreEPSAGON_IGNORED_KEYSList-List of keys names to be removed from the tracekeys_to_allowEPSAGON_ALLOWED_KEYSList-List of keys names to be included from the traceignored_endpointsEPSAGON_ENDPOINTS_TO_IGNOREList-List of endpoints to ignore from tracing (for example/healthcheckurl_patterns_to_ignoreEPSAGON_URLS_TO_IGNOREList[]Array of URL patterns to ignore the callsdebugEPSAGON_DEBUGBooleanFalseEnable debug prints for troubleshootingdisable_timeout_sendEPSAGON_DISABLE_ON_TIMEOUTBooleanFalseDisable timeout detection in Lambda functionssplit_on_sendEPSAGON_SPLIT_ON_SENDBooleanFalseSplit the trace into multiple chunks to support large tracespropagate_lambda_idEPSAGON_PROPAGATE_LAMBDA_IDBooleanFalseInsert Lambda request ID into the response payloadlogging_tracing_enabledEPSAGON_LOGGING_TRACING_ENABLEDBooleanTrueAdd Epsagon Log Id to allloggingmessagesstep_dict_output_pathEPSAGON_STEPS_OUTPUT_PATHListNonePath in the result dict to append the Epsagon steps data-EPSAGON_HTTP_ERR_CODEInteger500The minimum number of an HTTP response status code to treat as an error-EPSAGON_SEND_TIMEOUT_SECFloat1.0The timeout duration in seconds to send the traces to the trace collector-EPSAGON_DISABLE_LOGGING_ERRORSBooleanFalseDisable the automatic capture of error messages intologging-EPSAGON_IGNORE_FLASK_RESPONSEBooleanFalseDisable the automatic capture of Flask response data-EPSAGON_SKIP_HTTP_RESPONSEBooleanFalseDisable the automatic capture of http client response data-DISABLE_EPSAGONBooleanFalseA flag to completely disable Epsagon (can be used for tests or locally)-DISABLE_EPSAGON_PATCHBooleanFalseDisable the library patching (instrumentation)-EPSAGON_LAMBDA_TIMEOUT_THRESHOLD_MSInteger200The threshold in millieseconds to send the trace before a Lambda timeout occurs-EPSAGON_PAYLOADS_TO_IGNOREList-Array of dictionaries to not instrument. Example:'[{"source": "serverless-plugin-warmup"}]'-EPSAGON_REMOVE_EXCEPTION_FRAMESBooleanFalseDisable the automatic capture of exception frames data (Python 3)-EPSAGON_FASTAPI_ASYNC_MODEBooleanFalseEnable capturing of Fast API async endpoint handlers calls(Python 3)Getting HelpIf you have any issue around using the library or the product, please don't hesitate to:Use thedocumentation.Use the help widget inside the product.Open an issue in GitHub.Opening IssuesIf 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.LicenseProvided under the MIT license. See LICENSE for details.Copyright 2020, Epsagon