Documentation forSolarWinds Observability SaaS

Install the Python Library

The Python Library is a custom distro of OpenTelemetry Python, delivered as a package named solarwinds-apm. Install the library from the Python Package Index (PyPI) and use its command line interface (CLI) commands to bootstrap and instrument your Python application.

Before you start

Verify the following to ensure the library can collect and transmit data:

  • The platform where your APM library will be installed is supported.

  • Your application components are supported by the library.

  • Your firewall configuration permits TCP/HTTPS/TLS outbound connections to otel.collector.xx-yy.cloud.solarwinds.com (or apm.collector.xx-yy.cloud.solarwinds.com when using legacy mode) port 443, where xx-yy is determined by the URL you use to access SolarWinds Observability SaaS, described in Data centers and endpoint URIs. See Firewall or access control requirements.

    If your firewall or access control requirements do not allow such connections, configure the library to send data through a proxy.

Do not run other APM libraries alongside the SolarWinds Observability Python Library. Remove other APM libraries and agents from your Python application before using the SolarWinds Observability Python Library.

Python Library requirements

Version 4.0.0 and newer

The solarwinds-apm package is pure Python starting at version 4.0.0 and its binary distribution (Python wheel) or source distribution can be installed on most systems.

System requirements for installation from the Python wheel are:

  • Package installer for Python (pip) version 19.3 or greater

    If you are running an older version, upgrade pip with the command pip install --upgrade pip

Requirements to enable System Metrics

Starting at version 4.0.0, solarwinds-apm package supports system metrics instrumentation. To enable this feature, the service environment also needs psutil version 5.0 or greater installed. Then system metrics will generate automatically.

On Windows/macOS/Linux (except Alpine):

pip install "psutil>=5.0"

If your platform is not supported by the pre-built wheels provided by psutil (e.g. Alpine Linux), see this page for how to install.

Version 3.6.0 and older

Requirements for Python wheel

The solarwinds-apm package provides pre-built binary distributions (Python wheels) for most supported systems. Installing the package using the pip command automatically selects the Python wheel compatible with your system.

System requirements for installation from the Python wheels are:

  • Package installer for Python (pip) version 19.3 or greater

    If you are running an older version, upgrade pip with the command pip install --upgrade pip

  • An operating system that is compatible with the manylinux2014 Python wheel platform specification (see PEP599 from the Python Developer's Guide)

    Most modern Linux operating systems, except for Alpine Linux, are compatible with the manylinux2014 Python wheel platform specification.

If your system does not satisfy these requirements, you can install solarwinds-apm from the source. See Requirements for source distribution.

Requirements for source distribution

If your platform is not supported by the wheels provided with the package, use the pip command to install solarwinds-apm from the source distribution. When you install from the source distribution, the package compiles an extension during installation.

System requirements for installation from source distribution are:

  • Python header files
  • The gnu compiler
  • The make command

The command to install the above components is specific to the underlying operating system you are using.

On Debian/Ubuntu:

sudo apt-get install python3-dev g++ make

On RHEL/CentOS/Amazon Linux:

sudo yum install python3-devel gcc-c++ make

On Alpine Linux:

sudo apk add python3-dev g++ make

Some systems may provide multiple Python versions. If this is the case, specify the versioned header package, such as python3-dev, that matches the correct Python runtime.

See the Components supported by the Python Library to verify your system is supported.

The extension is compiled into a binary with both system and Python version dependencies. Do not copy the installed library package from one platform onto another platform. Instead, install the library on each individual platform.

Install the Python Library

Install the library and psutil from PyPI, then run the opentelemetry-bootstrap command. This command detects and installs the instrumentation packages applicable to your system:

pip install solarwinds-apm "psutil>=5.0"
opentelemetry-bootstrap --action=install

Make sure you install the Python Library after installing all other service dependencies. This order of installation allows opentelemetry-bootstrap to detect the packages and install the corresponding instrumentation libraries. For example:

pip install -r requirements.txt           # installs all other dependencies
pip install solarwinds-apm "psutil>=5.0"
opentelemetry-bootstrap --action=install

Enable the Python Library

The library requires a service key to connect to your account, and it must be loaded by running your application with the opentelemetry-instrument command.

Service key

The service key should be defined in the environment your application runs in (see Configure the Python Library):

export SW_APM_SERVICE_KEY="YourApiToken:YourServiceName"

The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

It is a required configuration and should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

Load the Python Library

Run your application with the prefix command opentelemetry-instrument to wrap all common Python frameworks and start exporting traces and metrics. For example:

opentelemetry-instrument command_to_run_your_service

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.