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.
To create a trace manually, import
opentelemetry, which is a global
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
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.
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
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")
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.
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.