Monitoring Python - The Instana Python Package

Stan Loves Python

The Instana Python package: Python Distributed Tracing & Metrics Sensor.

Usage

The Instana Python package is a zero-configuration tool that automatically collects key metrics and distributed traces from your Python processes.

Installing

Automatic installation

Instana remotely instruments your Python applications automatically by Instana AutoTrace™. However, if you prefer to install the package manually, see Manual Installation as follows.

Kubernetes

The Instana AutoTrace WebHook is an implementation of a Kubernetes Mutating WebHook Admission Controller that automatically sets up everything that is required to monitor Python applications with Instana, across an entire Kubernetes cluster.

If you install the Instana AutoTrace WebHook on your Kubernetes clusters, you don't need to perform any manual steps to trace your Python applications that run in those clusters.

If your Python application and the Instana agent are managed by Kubernetes, check the documentation on Kubernetes network access for information about the required configuration in this setup.

The Instana AutoTrace WebHook installs only Python sensor 2.0.0 and newer, and doesn't deliver support for legacy runtimes like Python 2.7.{: note} To check which versions of related components are supported, see Supported Components & Versions. If you need to work with legacy runtimes, see the following Manual Installation section.

Deprecated: Legacy Python AutoTrace

The automatic installation of the Python AutoTracing feature through the host agent mechanism is deprecated and scheduled for complete removal in April 2024. Do not enable this feature.

The preferred approach to monitor Python applications is the AutoTrace WebHook which provides increased stability and a future-proof solution. However, this approach only works on Kubernetes/OpenShift. If your applications are not on Kubernetes, you can do the following steps:

  1. Instrument the Python application manually.
  2. Temporarily enable the deprecated Legacy Auto Installation via Host Agent mechanism (Linux x86 only), until the manual instrumentation takes place. This requires that the instrumenting machine is able to reach pip.{: note} The steps don't work in the air-gapped environments or similar environments that restrict egress.

Manual Installation

For runtimes with Python 3.7 and later versions

You can manually install the Instana Python package into the virtualenv, pipenv, or container by running this command:

pip install git+https://github.com/instana/python-sensor@v2.3.0

For runtimes with Python 3.6 and earlier versions

The Instana Python package (hosted on PyPI), with version 2.0.0 and earlier, is intended for legacy Python runtime versions (less than or equal to 3.6). To install the PyPI-hosted Instana Python package, run the following command:

pip install instana

To update an existing installation, run this command:

pip install -U instana

Then, continue to complete the actions in either of the following two sections based on your organization's needs.

Activating Without Code Changes

Instana offers a way of activating the Instana Python package without modifying a single line of code in your application. This allows you to avoid many of the processes involved with application code changes such as pull-requests, quality assurance, staging and deployment to production.

To activate the Instana package without any code changes, simply set the following environment variable for your Python application:

export AUTOWRAPT_BOOTSTRAP=instana

The Instana Python package will automatically load on application boot and instrument your Python application.

  • Note: This method of activation will not work with applications based on gevent. This is because gevent must be activated and monkey.patch_all() called first.

Activating With Code Changes

Alternatively, to manually import the instana package to inside your Python application code, add the following to your application code:

import instana

For additional information about Django, Flask, End-user Monitoring (EUM), and more, see the Frameworks section.

Configuration

For out of the box metrics and distributed tracing, no configuration is required. However, individual components are configurable. For more information, see the Python configuration.

Cloud Foundry

This section assumes that the Instana agent is running on the Diego cells of the Cloud Foundry foundation. Without an agent running on the underpinning Diego cell, monitoring Cloud Foundry applications is not supported.{: note} Additionally, since the Tile version 1.177.0, the instana_buildpack automates the setup of Python applications on Cloud Foundry. For more information, refer to the Instana Buildpack documentation.

For information on how to setup Instana agents and the related Cloud Foundry or Pivotal Platform functionality, see our Cloud Foundry and Pivotal Platform documentation.

Monitoring Python Cloud Foundry applications requires the following steps:

  • Add the instana Python package to the requirements.txt file
  • Add an AUTOWRAPT_BOOTSTRAP environment variable with the value instana to the application manifest as shown as follows
  • cf push the Cloud Foundry application
---
applications:
- name: test-python-flask
  buildpacks:
    - python_buildpack
  env:
    AUTOWRAPT_BOOTSTRAP: instana

Software Development Kits

Instana native SDK

The Python tracer package of Instana includes a tracing SDK for Python. The SDK takes the form of a public open source API. For more information about the full source code and code forge, see the Python tracer package of Instana. For more information about installing the Python Tracing SDK, see the Installing section. For examples on how to instrument your Python application, see Python Tracing SDK.

OpenTracing

The Instana Python package supports custom tracing through the legacy OpenTracing APIs. For more information, see Python OpenTracing.

Troubleshooting

Please see our dedicated Troubleshooting documentation.

Releases

For the Instana Python package release history, including changes made to the package, see the Github Releases page.

See Also