{"id":10002,"library":"oneagent-sdk","title":"Dynatrace OneAgent SDK for Python","description":"The Dynatrace OneAgent SDK for Python allows developers to extend Dynatrace's monitoring capabilities for custom components and frameworks. It integrates with the Dynatrace OneAgent to provide deep visibility into custom services, databases, and messaging systems, enabling end-to-end tracing and performance analysis. The current version is 1.5.2.20260107.153442. Releases are generally tied to new versions of the Dynatrace OneAgent SDK for C/C++, with bugfix releases in between.","status":"active","version":"1.5.2.20260107.153442","language":"en","source_language":"en","source_url":"https://github.com/Dynatrace/OneAgent-SDK-for-Python","tags":["apm","observability","tracing","monitoring","dynatrace","sdk"],"install":[{"cmd":"pip install oneagent-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"SDKConfig","correct":"from oneagent_sdk import SDKConfig"},{"symbol":"OneAgentSDK","correct":"from oneagent_sdk import OneAgentSDK"},{"note":"All core SDK components are directly available under the `oneagent_sdk` namespace.","wrong":"from oneagent_sdk.sdk_state import SDKState","symbol":"SDKState","correct":"from oneagent_sdk import SDKState"}],"quickstart":{"code":"import os\nfrom oneagent_sdk import SDKConfig, OneAgentSDK, SDKState, ChannelType, DatabaseVendor, MessageBusVendor\n\ndef initialize_sdk():\n    \"\"\"Initializes the Dynatrace OneAgent SDK.\"\"\"\n    # SDKConfig can be customized, e.g., to enable/disable specific features.\n    # For most cases, the default configuration is sufficient as it connects\n    # to the local OneAgent automatically.\n    config = SDKConfig()\n    sdk = OneAgentSDK(config)\n\n    if sdk.get_current_state() != SDKState.ACTIVE:\n        print(\"Dynatrace OneAgent SDK is not active. Is OneAgent running and configured?\")\n        print(f\"Current state: {sdk.get_current_state().name}\")\n        # In a production environment, you might log this as a warning or error\n        # and ensure your application can run gracefully without SDK full functionality.\n    else:\n        print(\"Dynatrace OneAgent SDK is active.\")\n    return sdk\n\ndef example_tracing_and_database_call(sdk: OneAgentSDK):\n    \"\"\"Demonstrates basic tracing for a custom service, database, and message bus.\"\"\"\n    print(\"\\n--- Starting example tracing ---\")\n    # Trace a custom service method\n    with sdk.trace_custom_service(\"MyPythonApplication\", \"process_order\"):\n        print(\"Processing an order...\")\n\n        # Simulate a database call\n        db_info = sdk.create_database_info(\n            name=\"CustomerDB\",\n            vendor=DatabaseVendor.POSTGRESQL,\n            channel_type=ChannelType.TCP_IP,\n            channel_endpoint=\"db.example.com:5432\",\n            # You can also specify user, port, etc., but avoid sensitive data\n        )\n        with sdk.trace_database_request(db_info, \"SELECT * FROM orders WHERE status = 'pending';\"):\n            print(\"Executing database query...\")\n            import time\n            time.sleep(0.1) # Simulate network/DB latency\n        print(\"Database operation complete.\")\n\n        # Simulate a message bus interaction (e.g., receiving a message)\n        msg_bus_info = sdk.create_message_bus_info(\n            vendor=MessageBusVendor.RABBITMQ,\n            destination_name=\"order_queue\",\n            # You might specify topic, broker, etc., depending on the vendor\n        )\n        with sdk.trace_message_bus_receive_activity(msg_bus_info, \"order_msg_001\"):\n            print(\"Receiving message from message bus...\")\n            time.sleep(0.05) # Simulate message processing\n        print(\"Message bus interaction complete.\")\n\n    print(\"Order processing finished. OneAgent should have captured this trace.\")\n    print(\"--- Example tracing finished ---\\n\")\n\nif __name__ == \"__main__\":\n    sdk_instance = initialize_sdk()\n    if sdk_instance.get_current_state() == SDKState.ACTIVE:\n        example_tracing_and_database_call(sdk_instance)\n    else:\n        print(\"SDK not active, skipping tracing examples. Please ensure Dynatrace OneAgent is running.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the OneAgent SDK, check its status, and use it to trace a custom service, a database request, and a message bus interaction. The SDK automatically connects to a local Dynatrace OneAgent for data reporting. Ensure the OneAgent is running for the SDK to be active."},"warnings":[{"fix":"Upgrade to OneAgent SDK for Python version 1.5.x or newer: `pip install --upgrade oneagent-sdk`.","message":"Dynatrace OneAgent SDK for Python versions 1.4 and older were officially deprecated as of November 2023 and are no longer supported since June 1, 2024. Running unsupported versions may lead to compatibility issues or lack of new features.","severity":"deprecated","affected_versions":"<1.5.0"},{"fix":"Ensure your Dynatrace OneAgent installation is updated to meet or exceed the minimum version specified in the release notes of your Python SDK version.","message":"The OneAgent SDK requires a compatible Dynatrace OneAgent to be installed and running on the host. SDK versions are typically bundled with a specific C/C++ SDK version, which in turn dictates the minimum required OneAgent version. For example, SDK v1.5.x requires OneAgent v1.251+.","severity":"breaking","affected_versions":"All versions"},{"fix":"Upgrade to `oneagent-sdk` version 1.5.2 or newer, which includes packaging fixes to address these issues: `pip install --upgrade oneagent-sdk`.","message":"Installing `oneagent-sdk` with newer versions of `uv` (0.9.16+) or `setuptools` (v81+) could fail on musl/Alpine platforms or due to a hard dependency on `pkg_resources`.","severity":"gotcha","affected_versions":"<1.5.2"},{"fix":"If using Python 3.12 or higher, upgrade to `oneagent-sdk` version 1.5.1 or newer: `pip install --upgrade oneagent-sdk`.","message":"Versions prior to 1.5.1 had issues with full compatibility for Python 3.12 and newer, potentially leading to crashes or unexpected behavior.","severity":"gotcha","affected_versions":"<1.5.1"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Upgrade to `oneagent-sdk>=1.5.1` to ensure support for Python 3.12 and later: `pip install --upgrade oneagent-sdk`.","cause":"Older `oneagent-sdk` versions (prior to 1.5.1) did not have full compatibility with Python 3.12 and newer.","error":"Application crashes or unexpected behavior on Python 3.12+"},{"fix":"Upgrade to `oneagent-sdk>=1.5.2` to resolve these installation and dependency issues: `pip install --upgrade oneagent-sdk`.","cause":"Versions of `oneagent-sdk` prior to 1.5.2 had a hard dependency on `pkg_resources` which was removed in recent `setuptools` versions, or packaging issues affecting `uv` on specific platforms.","error":"ModuleNotFoundError: No module named 'pkg_resources' (when installing with setuptools>=81) or installation failures with uv>=0.9.16 on musl/Alpine."},{"fix":"Verify that the Dynatrace OneAgent is installed and running on the host. Ensure the OneAgent version meets the minimum requirements specified by your `oneagent-sdk` version (e.g., v1.251+ for SDK v1.5.x).","cause":"The Python SDK could not connect to a running Dynatrace OneAgent. This can happen if the OneAgent is not installed, not running, or an incompatible version is present.","error":"Dynatrace OneAgent SDK is not active. Is OneAgent running?"}]}