Thundra Agent Python For Tracing

Trace your marvelous python projects with async monitoring by Thundra!

Async Monitoring with Zero Overhead

By default, Thundra agent reports by making an HTTPS request. This adds an overhead to your lambda function.

Instead, you can setup async monitoring in 2 minutes and monitor your lambda functions with zero overhead!

Contents

• Installation
• Configuration
• Usage
  • No-Code Change Tracing
  • In-Code Configuration Tracing
  • Decorator
  • Request Body
• Frameworks
• Integrations
• Log Plugin
• Thundra Foresight
  • Activating Thundra Foresight
• Getting Help
• Opening Issues
• All Environment Variables

Installation

Run this command from your project directory:

pip install thundra -t .

Configuration

You can configure Thundra using environment variables or module initialization parameters.

Environment variables have higher precedence over initialization parameters.

Check out the configuration part of our docs for more detailed information.

1. Most Useful Environment variables

2. Object initialization parameters

Usage

No-Code Change Tracing

The simplest way to auto trace configuration of all your endpoints into project by setting following environment variables:

export THUNDRA_APIKEY=<your_thundra_api_key>
export THUNDRA_AGENT_APPLICATION_NAME=<your_application_name>
<python command>

For illustration of Fastapi:

export THUNDRA_APIKEY=<your_thundra_api_key>
export THUNDRA_AGENT_APPLICATION_NAME=fastapi-prod
uvicorn main:app --reload

For Dockerfile, you just replace export with ENV.

You can see the list of no-code change supported frameworks

In-Code Configuration Tracing

Another simple alternative is to copy the snippet into your code before your app created:

import thundra

thundra.configure(
     options={
         "config": {
             "thundra.apikey": <your_thundra_api_key>,
             "thundra.agent.application.name": <your_application_name>
         }
     }
)

To run on your framework please refer to supported frameworks

Decorator

Just import this module, pass your api key to it and use our decorator to wrap your handler:

import thundra

thundra.configure(
     options={
         "config": {
             "thundra.apikey": <your_thundra_api_key>,
             "thundra.agent.application.name": <your_application_name>
         }
     }
)

@thundra.<framework_wrapper>
def handler(event, context):
    print("Hello Thundra!")

OR

export THUNDRA_APIKEY=<your_thundra_api_key>
export THUNDRA_AGENT_APPLICATION_NAME=<your_application_name>

import thundra

@thundra.<framework_wrapper>
def handler(event, context):
    print("Hello Thundra!")

NOTES

• To run on your framework please refer to supported frameworks
• You should disable framework that you use by using environment variable or in-code configuration. Explanations can be found in corresponding framework section.

Request Body

Normally thundra does not get your project's requests' body. In order to see request body on tracing data, following environment variable shall be set besides api key and application name:

export THUNDRA_AGENT_TRACE_REQUEST_SKIP=True

OR

import thundra

thundra.configure(
     options={
         "config": {
             "thundra.apikey": <your_thundra_api_key>,
             "thundra.agent.application.name": <your_application_name>,
			 "thundra.agent.trace.request.skip": True
         }
     }
)

Frameworks

The following frameworks are supported by Thundra:

AWS Lambda

Tracing Lambda functions:

1. Check our integration document on web site

NOTES

• Make sure to choose just one of the methods from integration document above.
• For decorator tracing method:
  1. Set THUNDRA_APIKEY and other configurations if needed as no-code change or in-code change sytle.
  2. Change @thundra.<framework_wrapper> by @thundra.lambda_wrapper.
• In order to activate AWS Step Functions trace, THUNDRA_AGENT_LAMBDA_AWS_STEPFUNCTIONS environment variable should be set true.
• In order to activate AWS AppSync trace, THUNDRA_AGENT_LAMBDA_AWS_APPSYNC environment variable should be set true.
• For other integrations' configuration, please take a look environment variables table at the end.

Django

Tracing Django application:

1. Auto trace by using one of the following methods:
   • No-Code Change Tracing.
   • In-Code Configuration Tracing
2. Trace specific endpoints by Decorator

Code snippet in In-Code Configuration Tracing should be added into settings.py file. To trace django database processes, following environment variables shall be set to false:

• No-Code Change Tracing:

  export THUNDRA_AGENT_TRACE_INTEGRATIONS_DJANGO_ORM_DISABLE=false
  export THUNDRA_AGENT_TRACE_INTEGRATIONS_RDB_DISABLE=false

• In-Code Configuration Tracing:

  import thundra
  
  thundra.configure(
      options={
          "config": {
              "thundra.apikey": <your_thundra_api_key>,
              "thundra.agent.application.name": <your_application_name>,
              "thundra.agent.trace.integrations.django.orm.disable": False,
              "thundra.agent.trace.integrations.rdb.disable": False
          }
      }
  )

NOTES

• Make sure to choose just one of the methods.
• For decorator tracing method:
  1. Disable thundra django instrumentation by using THUNDRA_AGENT_TRACE_INTEGRATIONS_DJANGO_DISABLE or its corresponding in-code configuration.
  2. Change @thundra.<framework_wrapper> by @thundra.django_wrapper.

Flask

Tracing Flask application:

1. Auto trace by using one of the following methods:
   • No-Code Change Tracing.
   • In-Code Configuration Tracing
2. Trace specific endpoints by Decorator

Code snippet in In-Code Configuration Tracing should be added into app.py file before application is initialized.

NOTES

• Make sure to choose just one of the methods.
• For decorator tracing method:
  1. Disable thundra flask instrumentation by using THUNDRA_AGENT_TRACE_INTEGRATIONS_FLASK_DISABLE or its corresponding in-code configuration.
  2. Change @thundra.<framework_wrapper> by @thundra.flask_wrapper.

Fastapi

Tracing Fastapi application:

1. Auto trace by using one of the following methods:
   • No-Code Change Tracing.
   • In-Code Configuration Tracing
2. Trace specific endpoints by Decorator by adding fastapi.Request as an parameter to your function if not exists.

NOTES

• Make sure to choose just one of the methods.
• For decorator tracing method:
  1. Disable thundra fastapi instrumentation by using THUNDRA_AGENT_TRACE_INTEGRATIONS_FASTAPI_DISABLE or its corresponding in-code configuration.
  2. Change @thundra.<framework_wrapper> by @thundra.fastapi_wrapper.
• Fastapi has been supported for python 3.7 and above.

Chalice

Tracing Chalice application:

1. Auto trace by using one of the following methods:
   • No-Code Change Tracing.
   • In-Code Configuration Tracing
2. Trace specific endpoints by Decorator

NOTES

• Make sure to choose just one of the methods.
• For decorator tracing method:
  1. Disable thundra chalice instrumentation by using THUNDRA_AGENT_TRACE_INTEGRATIONS_CHALICE_DISABLE or its corresponding in-code configuration.
  2. Change @thundra.<framework_wrapper> by @thundra.chalice_wrapper.

Tornado

Tracing Tornado application:

1. Auto trace by using one of the following methods:
   • No-Code Change Tracing.
   • In-Code Configuration Tracing
2. Trace specific endpoints by Decorator

NOTES

• Make sure to choose just one of the methods.
• Tornado has been supported for python 3.7 and above.
• For decorator tracing method:
  1. Disable thundra tornado instrumentation by using THUNDRA_AGENT_TRACE_INTEGRATIONS_TORNADO_DISABLE or its corresponding in-code configuration.
  2. Change @thundra.<framework_wrapper> by @thundra.tornado_wrapper.

Integrations

Thundra provides out-of-the-box instrumentation (tracing) for following libraries.

Log Plugin

Log plugin is added by default, but in order to enable it, you should add ThundraLogHandler to your logger.

You can either add it via logging.conf or add during getting logger object.

Configure via logging.conf

An example of configuration file is as follows:

[loggers]
keys=root

[handlers]
keys=thundraHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=NOTSET
handlers=thundraHandler

[handler_thundraHandler]
class=ThundraLogHandler
level=NOTSET
formatter=simpleFormatter
args=()

[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
datefmt=

Configure during getting logger object

You should add the followings after getting the logger object:

handler = ThundraLogHandler()
logger.addHandler(handler)
...
logger.removeHandler(handler)

Thundra Foresight

Foresight is a project powered by Thundra agent to show every detail for test runs. For know, it only supports pytest. Although Its automatically enabled after installing Thundra as 'pip install thundra', you need to set THUNDRA_APIKEY and THUNDRA_AGENT_TEST_PROJECT_ID as described below.

Activating Thundra Foresight

• Firstly, setting up environment for Thundra. There are three ways to do it.

  1. Setting THUNDRA_APIKEY and THUNDRA_AGENT_TEST_PROJECT_ID as environment variable.

  export THUNDRA_APIKEY=<your_apikey>
  export THUNDRA_AGENT_TEST_PROJECT_ID=<your_test_project_id>

  2. "thundra_apikey " and "thundra_agent_test_project_id" in you .env file. Then, loaded them in conftest.py file like:

      thundra_apikey =<your_apikey>
      thundra_agent_test_project_id = <your_test_project_id>

      # This method requires python >= 3.5
      from pathlib import Path
  
      from dotenv import load_dotenv
  
      env_path = Path(<your_env_file_name>)
      load_dotenv(dotenv_path=env_path)

  3. Importing Thundra in conftest file and configure it.

      import thundra
  
      thundra.configure(
          options={
              "config": {
                  "thundra.apikey": <your_apikey>,
                  "thundra.agent.test.project.id": <your_test_project_id>
              }
          }
      )

Deactivating Thundra Foresight

• There are three ways to deactivate Thundra Foresight for pytest:

  1. Run pytest with --thundra_disable command on terminal for specific pytest run.

      pytest --thundra_disable <your_tests_path>

  2. Modifying any configuration file read by pytest(pytest.ini, setup.cfg, pyproject.toml etc.) Please read carefully pytest official documentation for configuration files.

      [pytest]
      thundra_disable = 1

  or

      [tool.pytest.ini_options]
      thundra_disable = 1

  3. Setting THUNDRA_AGENT_TEST_DISABLE=True as environment variable.

NOTES

• All Thundra agent features are valid in Foresight. It's default enabled. If you see more information about your test cases, you can visit Thundra APM. If you want to disable thundra agent for tracing, you can set "THUNDRA_AGENT_DISABLE" as environment variable, "thundra_agent_disable" in .env file or "thundra.agent.disable" into thundra.configure() to True as describing above.

Getting Help

If you have any issue around using the library or the product, please don't hesitate to:

• Use the documentation.
• Open an issue in GitHub.
• Join our python slack channel.

Opening Issues

For any problem you encounter while using thundra, Please feel free to contact us via github issue or our python slack channel.

When opening a new issue, please provide as much information about the environment:

• Library version, Python runtime version, dependencies, operation system with version etc.
• Snippet of the usage.
• A reproducible example can really help.

The GitHub issues are intended for bug reports and feature requests.

All Environment Variables

Following table shows all environment variables of No-Code Change Tracing and their In-Code Configuration Tracing equivalent.