Epsagon Instrumentation for Python

This package provides an instrumentation to Python code running on functions for collection of distributed tracing and performance monitoring.

• Installation
• Usage
  • AWS Lambda
  • Django Application
  • Flask Application
  • Tornado Application
  • Generic Python
  • Auto-tracing
• Custom Data
  • Custom Labels
  • Custom Errors
  • Ignore Keys
• Frameworks Integration
  • Serverless
  • Chalice
  • Zappa
• Copyright

Installation

From your project directory:

$ pip install epsagon

More details about lambda deployments are available in the AWS documentation.

Usage

Make sure to add epsagon under your requirements.txt file.

AWS Lambda

Simply use our decorator to report metrics:

import epsagon
epsagon.init(
    token='my-secret-token',
    app_name='my-app-name',
    metadata_only=False,  # Optional, send more trace data
)

@epsagon.lambda_wrapper
def handler(event, context):
  pass

Django Application

Add the following code to the settings.py file:

import epsagon
epsagon.init(
    token='my-secret-token',
    app_name='my-app-name',
    metadata_only=False,  # Optional, send more trace data
)

For web frameworks: Use ignored_endpoints to blacklist specific paths and prevent Epsagon from sending a trace.

import epsagon
epsagon.init(
    ...
    ignored_endpoints=['/path', '/path/to/ignore']
)

Flask Application

Use the example snippet:

from flask import Flask
import epsagon

epsagon.init(
    token='my-secret-token',
    app_name='my-app-name',
    metadata_only=False
)

app = Flask(__name__)

@app.route('/')
def hello():
    return "Hello World!"

app.run()

Tornado Application

Use the example snippet:

import tornado.ioloop
import tornado.web
import epsagon

epsagon.init(
    token='my-secret-token',
    app_name='my-app-name',
    metadata_only=False
)


class MainHandler(tornado.web.RequestHandler):
    def get(self):
        self.write('Hello, world')


def make_app():
    return tornado.web.Application([
        (r'/', MainHandler),
    ])


if __name__ == '__main__':
    app = make_app()
    app.listen(8888)
    tornado.ioloop.IOLoop.current().start()

Generic Python

Use the example snippet:

import epsagon
epsagon.init(
    token='my-secret-token',
    app_name='my-app-name',
    metadata_only=False
)


@epsagon.python_wrapper
def main():
    return 'It worked!'
  
main()

Auto-tracing

You can apply Epsagon tracing without any code changes using:

AUTOWRAPT_BOOTSTRAP=epsagon <command>

For example:

AUTOWRAPT_BOOTSTRAP=epsagon python app.py

Configuration

You can customize your library usage using flags. The flags should be set as enviroment variables in your code runtime enviroment.

EPSAGON_SEND_TIMEOUT_SEC - Set a custom trace send timeout. EPSAGON_HTTP_ERR_CODE - Minimum HTTP status to be treated as an error. EPSAGON_SSL - TRUE / FALSE. Disable SSL for trace send. Default is TRUE. EPSAGON_ENDPOINTS_TO_IGNORE - Endpoints to ignore, comma seperated. aka: "endpoint1, endpoint2" EPSAGON_TOKEN - Account Epsagon token. EPSAGON_APP_NAME - Application name that will be set for traces. EPSAGON_METADATA - TRUE / FALSE. Whether to send all collected data, or just metadata. Default is FALSE. EPSAGON_SPLIT_ON_SEND - TRUE / FALSE. Split big traces into multiple parts. Default is FALSE.

Lambda specific flags

EPSAGON_DISABLE_ON_TIMEOUT - TRUE / FALSE. Don't send trace on timeout. Default is FALSE.

Custom Data

Custom Labels

You can add custom labels to your traces. Filters can later be used for filtering traces that contains specific labels:

def handler(event, context):
    epsagon.label('key', 'value')
    epsagon.label('user_id', event['headers']['auth'])
    epsagon.label('number_of_records_parsed_successfully', 42)

Custom Errors

You can manually set a trace as an error, even if handled correctly. Please refer to the full documentation, about handling of this errors in the issues management.

def handler(event, context):
    try:
        fail = 1 / 0
    except Exception as ex:
        epsagon.error(ex)
        
    # or

    if 'my_param' not in event:
        epsagon.error(ValueError('event missing my_param'))
        # or
        epsagon.error('event missing my_param')

Ignore keys

You can prevent data from being sent to epsagon by filtering specific keys in initialization.

import epsagon
epsagon.init(
    token='my-secret-token',
    app_name='my-app-name',
    metadata_only=False,
    keys_to_ignore=['Request Data', 'Status_Code']
)

Frameworks Integration

When using any of the following integrations, make sure to add epsagon under your requirements.txt file.

Serverless

Using Epsagon with Serverless is simple, by using the serverless-plugin-epsagon.

Chalice

Using Epsagon with Chalice is simple, follow this example:

from chalice import Chalice
import epsagon
epsagon.init(
    token='my-secret-token',
    app_name='my-app-name',
    metadata_only=False
)
app = Chalice(app_name="hello-world")


@app.route("/")
def index():
    return {"hello": "world"}

app = epsagon.chalice_wrapper(app)

or In S3 trigger example:

from chalice import Chalice

app = Chalice(app_name="helloworld")

import epsagon
epsagon.init(
    token='my-secret-token',
    app_name='my-app-name',
    metadata_only=False
)
# Whenever an object is uploaded to 'mybucket'
# this lambda function will be invoked.

@epsagon.lambda_wrapper
@app.on_s3_event(bucket='mybucket')
def handler(event):
    print("Object uploaded for bucket: %s, key: %s"
          % (event.bucket, event.key))

Zappa

Using Epsagon with Zappa is simple, follow this example:

from flask import Flask
from zappa.handler import lambda_handler
import epsagon

epsagon.init(
    token='my-secret-token',
    app_name='my-app-name',
    metadata_only=False
)
app = Flask(__name__)


@app.route('/')
def hello_world():
    return 'Hello, World!'


epsagon_handler = epsagon.lambda_wrapper(lambda_handler)

And in your zappa_settings.json file include the following:

{
  "lambda_handler": "module.path_to.epsagon_handler"
}

Copyright

Provided under the MIT license. See LICENSE for details.

Copyright 2019, Epsagon.