Skip to main content

Dynatrace OneAgent SDK for Python

Project description

Disclaimer: This SDK is currently still work in progress. Using the OneAgent SDK for Python is COMPLETELY UNSUPPORTED at this stage!

Read the latest version of this README, with working internal links, at GitHub.

Dynatrace OneAgent SDK for Python

This SDK enables Dynatrace customers to extend request level visibility into Python applications. It provides the Python implementation of the Dynatrace OneAgent SDK.

Requirements

The SDK supports Python 2 ≥ 2.7 and Python 3 ≥ 3.4. Only the official CPython (that is, the "normal" Python, i.e. the Python implementation from https://python.org) is supported.

The Dynatrace OneAgent SDK for Python includes the Dynatrace OneAgent SDK for C/C++. See here for its requirements, which also apply to the SDK for Python.

The version of the SDK for C/C++ that is included in each version of the SDK for Python is shown in the following table. The SDK for C/C++'s requirement for the Dynatrace OneAgent is also shown here, for your convenience (it is the same that is listed in the OneAgent SDK for C/C++'s documentation).

OneAgent SDK for Python OneAgent SDK for C/C++ Dynatrace OneAgent
1.0 1.1.0 ≥1.141

Using the OneAgent SDK for Python in your application

To install the latest version of the OneAgent SDK for Python, use the PyPI package oneagent-sdk:

python -m pip install --upgrade oneagent-sdk

To verify your installation, execute

python -c "import oneagent; print(oneagent.try_init())"

If everything worked, you should get some output ending with InitResult(status=0, error=None). Otherwise, see Troubleshooting.

You then need to load the SDK into the application and add code that traces your application using the SDK. For a quick “Hello World” that should give you a Path in the Dynatrace UI, try this:

import oneagent
from oneagent.sdk import SDK

if not oneagent.try_init():
    print('Error initializing OneAgent SDK.')

with SDK.get().trace_incoming_remote_call('method', 'service', 'endpoint'):
    pass

print('It may take a few moments before the path appears in the UI.')
input('Please wait...')
oneagent.shutdown()

For this, follow the provided sample application (see also Quickstart section in the documentation).

API Concepts

Initialization and SDK objects

Before first using any other SDK functions, you should initialize the SDK.

init_result = oneagent.try_init()
print('OneAgent SDK initialization result' + repr(init_result))
if init_result:
    print('SDK should work (but agent might be inactive).')
if not init_result:
    print('SDK will definitely not work (i.e. functions will be no-ops).')

See the documentation for the try_init function and the InitResult class for more information.

To then use the SDK, get a reference to the SDK singleton by calling its static get static method. The first thing you may want to do with this object, is checking if the agent is active by comparing the value of the agent_state property to the oneagent.common.AgentState constants.

import oneagent.sdk
from oneagent.common import AgentState
# Initialize oneagent, as above

sdk = oneagent.sdk.SDK.get()
if sdk.agent_state not in (AgentState.ACTIVE,
        AgentState.TEMPORARILY_INACTIVE):
    print('Too bad, you will not see data from this process.')

Tracers

To trace any kind of call you first need to create a Tracer, using one of the various trace_* methods of the SDK object. The Tracer object controls the “life cycle” of a trace: Entering a with-block with a tracer starts the trace, exiting it ends it. Exiting the with block with an exception causes the trace to be marked as failed with the exception message (if you do not want or need this behavior, tracers have explicit methods for starting, ending and attaching error information too; see the documentation).

There are different tracer types requiring different information for creation. As an example, to trace an incoming remote call, this would be the most simple way to trace it:

from oneagent.sdk import SDK

with SDK.get().trace_incoming_remote_call('method', 'service', 'endpoint'):
    pass # Here you would do the actual work that is timed

See the section on remote calls for more information.

Some tracers also support attaching additional information before ending it.

Important: In Python 2, tracers accept both byte (“normal”) and unicode strings. Byte strings must always use the UTF-8 encoding!

Features and how to use them

Remote calls

You can use the SDK to trace communication from one process to another. This will enable you to see full Service Flow, PurePath and Smartscape topology for remoting technologies that Dynatrace is not aware of.

To trace any kind of remote call you first need to create a Tracer. The Tracer object represents the endpoint that you want to call, thus you need to supply the name of the remote service and method. In addition, you need to transport a tag in your remote call from the client side to the server side if you want to trace it end to end.

On the client side, you would trace the outgoing remote call like this:

outcall = sdk.trace_outgoing_remote_call(
    'remoteMethodToCall', 'RemoteServiceName', 'rmi://Endpoint/service',
    oneagent.sdk.Channel(oneagent.sdk.ChannelType.TCP_IP, 'remoteHost:1234'),
    protocol_name='RMI/custom')
with outcall:
    # Note: You can access outgoing_dynatrace_*_tag only after the trace
    # has started!
    strtag = outcall.outgoing_dynatrace_string_tag
    do_actual_remote_call(extra_headers={'X-dynaTrace': strtag})

On the server side, you would trace it like this:

incall = sdk.trace_incoming_remote_call(
    'remoteMethodToCall', 'RemoteServiceName', 'rmi://Endpoint/service',
    protocol_name='RMI/custom',
    str_tag=my_remote_message.get_header_optional('X-dynaTrace'))
with incall:
    pass # Here you would do the actual work that is timed

See the documentation for more information:

SQL database requests

To trace database requests you need a database info object which stores the information about your database which does not change between individual requests. This will typically be created somewhere in your initialization code (after initializing the SDK):

dbinfo = sdk.create_database_info(
    'Northwind', oneagent.sdk.DatabaseVendor.SQLSERVER,
    oneagent.sdk.Channel(oneagent.sdk.ChannelType.TCP_IP, '10.0.0.42:6666'))

Then you can trace the SQL database requests:

with sdk.trace_sql_database_request(dbinfo, 'SELECT foo FROM bar;') as tracer:
    # Do actual DB request
    tracer.set_rows_returned(42) # Optional
    tracer.set_round_trip_count(3) # Optional

Note that you need to release the database info object. You can do this by calling close() on it or using it in a with block.

See the documentation for more information:

Incoming web requests

Like for database infos, to trace incoming web requests you need a web application info object which stores the information about your web application which does not change:

wappinfo = sdk.create_web_application_info(
    virtual_host='example.com',
    application_id='MyWebApplication',
    context_root='/my-web-app/')

Then you can trace incoming web requests:

wreq = sdk.trace_incoming_web_request(
    wappinfo,
    'http://example.com/my-web-app/foo?bar=baz',
    'GET',
    headers={'Host': 'example.com', 'X-foo': 'bar'},
    remote_address='127.0.0.1:12345')

with wreq:
    wreq.add_parameter('my_form_field', '1234')
    # Process web request
    wreq.add_response_headers({'Content-Length': '1234'})
    wreq.set_status_code(200) # OK

Note that you need to release the web application info object. You can do this by calling close() on it or using it in a with block.

Incoming web request tracers support some more features not shown here. Be sure to check out the documentation:

There is currently no explicit support for tracing outgoing web requests. You can use an outgoing remote call tracer instead.

Troubleshooting

To debug your OneAgent SDK for Python installation, execute the following Python code:

import oneagent
oneagent.logger.setLevel(0)
init_result = oneagent.try_init(['loglevelsdk=finest', 'loglevel=finest'])
print('InitResult=' + repr(init_result))

If you get output containing InitResult=InitResult(status=0, error=None), your installation should be fine.

Otherwise, hopefully the output is helpful in determining the issue.

Known gotchas:

  • ImportError or ModuleNotFoundError in line 1 that says that there is no module named oneagent.

    Make sure that the pip install or equivalent succeeded (see here). Also make sure you use the pip corresponding to your python (if in doubt, use python -m pip instead of pip for installing).

Repository contents

If you are viewing the GitHub repository, you will see:

  • LICENSE: License under which the whole SDK and sample applications are published.
  • src/: Actual source code of the Python OneAgent SDK.
  • docs/: Source files for the (Sphinx-based) HTML documentation. For the actual, readable documentation, see here.
  • tests/, test-util-src/: Contains tests and test support files that are useful (only) for developers wanting contribute to the SDK itself.
  • setup.py, setup.cfg, MANIFEST.in, project.toml: Development files required for creating e.g. the PyPI package for the Python OneAgent SDK.
  • tox.ini, pylintrc: Supporting files for developing the SDK itself. See https://tox.readthedocs.io/en/latest/ and https://www.pylint.org/.

Help & Support

Read the manual

Let us help you

Make sure your issue is not already solved in the available documentation before you ask for help. Especially the troubleshooting section in this README may prove helpful.

  • Ask a question in the product forums.

  • Open a GitHub issue to:

    • Report minor defects or typos.
    • Ask for improvements or changes in the SDK API.
    • Ask any questions related to the community effort.

    SLAs don't apply for GitHub tickets.

Release notes

Please see the GitHub releases page, and the PyPI release history.

License

See the LICENSE file for details. It should be included in your distribution. Otherwise, see the most recent version on GitHub.

Summary: This software is licensed under the terms of the Apache License Version 2.0 and comes bundled with the six library by Benjamin Peterson, which is licensed under the terms of the MIT license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

oneagent-sdk-1.0.0.tar.gz (48.7 kB view details)

Uploaded Source

Built Distributions

oneagent_sdk-1.0.0-py2.py3-none-win_amd64.whl (209.1 kB view details)

Uploaded Python 2Python 3Windows x86-64

oneagent_sdk-1.0.0-py2.py3-none-win32.whl (183.9 kB view details)

Uploaded Python 2Python 3Windows x86

oneagent_sdk-1.0.0-py2.py3-none-manylinux1_x86_64.whl (58.2 kB view details)

Uploaded Python 2Python 3

oneagent_sdk-1.0.0-py2.py3-none-manylinux1_i686.whl (57.9 kB view details)

Uploaded Python 2Python 3

File details

Details for the file oneagent-sdk-1.0.0.tar.gz.

File metadata

  • Download URL: oneagent-sdk-1.0.0.tar.gz
  • Upload date:
  • Size: 48.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for oneagent-sdk-1.0.0.tar.gz
Algorithm Hash digest
SHA256 ccc3afe2beb73c140a904800cb818de8d8b23613e95d4e2a40963ff072a39a2c
MD5 3855228304c0a950863341a8fc79b062
BLAKE2b-256 b14aae456adff3b3aaef818daf7b6ba371b5a0d4beba9e79da94bd04f9592958

See more details on using hashes here.

File details

Details for the file oneagent_sdk-1.0.0-py2.py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for oneagent_sdk-1.0.0-py2.py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 a36ca461954f42b0721eafe771cc380f5d59269f898c0c016e734c3f22730297
MD5 7d719d8e237addd2a1a06508ca61391a
BLAKE2b-256 88b587ae9173fd3658371188af46688073d182c281fbef450b669d31c7321f27

See more details on using hashes here.

File details

Details for the file oneagent_sdk-1.0.0-py2.py3-none-win32.whl.

File metadata

File hashes

Hashes for oneagent_sdk-1.0.0-py2.py3-none-win32.whl
Algorithm Hash digest
SHA256 6744538beb505466caf8d7927ec57b5d396728da8a7193fc1a2051dde1bc968c
MD5 c2649ff1f3c33e90c82c987f2b3476e6
BLAKE2b-256 6e8f300b9ee42df3ef84184adb19b0a00b6eafe87a7b995df7a5fe0bbfd0c78a

See more details on using hashes here.

File details

Details for the file oneagent_sdk-1.0.0-py2.py3-none-manylinux1_x86_64.whl.

File metadata

File hashes

Hashes for oneagent_sdk-1.0.0-py2.py3-none-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 fcb83efbfddfea618ddec5d853094748b54413c75ca056957aa17570c8f1d392
MD5 48788d77445de81be283795a20e730a9
BLAKE2b-256 583fd07b3788150748ccf6572f8fe1fbd0cbc25904982e14203a8cdf515750b3

See more details on using hashes here.

File details

Details for the file oneagent_sdk-1.0.0-py2.py3-none-manylinux1_i686.whl.

File metadata

File hashes

Hashes for oneagent_sdk-1.0.0-py2.py3-none-manylinux1_i686.whl
Algorithm Hash digest
SHA256 888b6a7789535a799e980cdc035a20ce6afe15f0cc108b79802cda704dbc571c
MD5 8ec181ca5cdc24c9c6aaf18ac82feab3
BLAKE2b-256 4dfb97bdf97913c537cf7c88c080b61ca65c752dfef89d053edb88aae212ab2c

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page