Documentation forSolarWinds Observability SaaS

Python Library instrumentation SDK

The SolarWinds Observability Python Library is a custom distro based on the OpenTelemetry Python agent, and therefore supports the standard OpenTelemetry API. You can use the standard API to manually instrument your applications.

Create a trace manually

To create a trace manually, import trace from opentelemetry, which is a global TracerProvider. Use trace to get_tracer, then start a new span that will be set as the current span in the Tracer‘s context at execution.

Here is a simple example:

from opentelemetry import trace
# get Tracer from OpenTelemetry TracerProvider
tracer = trace.get_tracer(__name__)
# create a span using Tracer
with tracer.start_as_current_span("my_custom_span"):
    # do things
    my_cool_thing.do_stuff();
# span ends with the with-statement

The SolarWinds Observability APM OpenTelemetry extensions automatically hook into the auto-configured global trace object when the application starts. You do not need to create your own trace object.

If you create and use a different trace object, the manual instrumentation spans will not be recognized by the SolarWinds Observability APM extensions or received by the SolarWinds APM collector.

Determine if the library is ready

The Python Library initializes and maintains a connection to a SolarWinds Observability collector, and receives settings used for making tracing decisions. This process can take up to a few seconds depending on the connection. If the application receives requests before initialization is complete, these requests are not traced. While this is not critical for long-running server processes, it might be a problem for short-running apps such as cron jobs or CLI apps.

A call to this method allows the application to block requests until initialization is complete and the library is ready for tracing. The method accepts an optional timeout parameter in milliseconds. This parameter tells the library how long to wait for initialization. The default timeout value is 3000. Setting the timeout value to 0 results in no blocking.


from solarwinds_apm.api import solarwinds_ready
solarwinds_ready(wait_milliseconds=3000, integer_response=False)

By default, it returns a Boolean value of True (ready) or False (not ready). To get detailed information instead of a simple Boolean return value, set integer_response=True. This changes the return value to an integer status code as listed below:

  • 0: Unknown error
  • 1: Is ready
  • 2: Not ready yet, try later
  • 3: Limit exceeded
  • 4: Invalid API key
  • 5: Connection error

Set custom transaction name

The default instrumentation provided by the Python Library assigns a transaction name based on the URL values detected. If this transaction name is not descriptive enough for your instrumented operation, you can override the transaction name with a custom one. There are two ways to customize transaction name, with order of precedence described in Service transactions.

The SDK can assign transaction name in service code. If multiple transaction names are set on the same trace, the last transaction name is used.

from solarwinds_apm.api import set_transaction_name
result = set_transaction_name("my-cool-request")

The set_transaction_name function accepts a string transaction name to assign to the current request. Empty string and null are considered invalid transaction name values and are ignored. The function returns a Boolean value of True (successful naming) or False (not successful).

When viewed in the Traces Explorer, transaction names are converted to lowercase, invalid characters in transaction names are replaced, and transaction names may be truncated.

If an asynchronous execution unit call to set_transaction_name happens after the service entry span has been processed and exported, the call has no effect.

Alternatively, a custom transaction name can be configured for all traces. This can be used to target specific instrumented lambda functions. See Python SW_APM_TRANSACTION_NAME system environment variable.

More details

See Tracing in the OpenTelemetry Python Manual Instrumentation docs site and opentelemetry.trace package in the OpenTelemetry Python API documentation for more ways to use the API.

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.