epsagon 1.37.0

Epsagon Instrumentation for Python

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
• 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
)

Add Epsagon middleware to the application's middleware list (located in settings.py)

MIDDLEWARE = [
    '....',
    'epsagon.wrappers.django.DjangoMiddleware',
]

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__)
epsagon.flask_wrapper(app)

@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()

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.