epsagon 1.20.1

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

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',
]

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:

@epsagon.lambda_wrapper
def handler(event, context):
  epsagon.label('label', 'something_to_filter_afterwards')
  epsagon.label('number_of_records_parsed_successfully', 42)
  pass

Custom Errors

Set a custom error, maybe without even failing the function:

@epsagon.lambda_wrapper
def handler(event, context):
  if 'my_param' not in event:
      epsagon.error(ValueError('event missing my_param'))
  pass

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

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.