Version 1.5.0 (#25)

Author: Oberon00

.gitignore

@@ -1,5 +1,10 @@
 *.pyc
 *.pyo
+*.lib
+*.pdb
+*.so
+*.a
+*.launch
 build/
 __pycache__/
 onesdk_shared.dll
@@ -10,7 +15,13 @@ dist/
 /tmp/
 *.egg-info
 .pytest_cache/
+venv/
+.venv/
+.tox/
+.vscode
+*.whl
+db.sqlite3
+/.checkstyle
 /.project
 /.pydevproject
-/.README.md.html
-/.settings
+.settings/

README.md

@@ -24,26 +24,38 @@ This SDK enables Dynatrace customers to extend request level visibility into Pyt
   * [Messaging](#messaging)
     + [Outgoing Messages](#outgoing-messages)
     + [Incoming Messages](#incoming-messages)
+- [W3C trace context](#w3c-trace-context)
 - [Using the OneAgent SDK for Python with forked child processes (only available on Linux)](#using-the-oneagent-sdk-for-python-with-forked-child-processes-only-available-on-linux)
 - [Troubleshooting](#troubleshooting)
   * [Extended SDK State](#extended-sdk-state)
+  * [Shutdown crashes](#shutdown-crashes)
 - [Repository contents](#repository-contents)
 - [Help & Support](#help--support)
   * [Read the manual](#read-the-manual)
   * [Let us help you](#let-us-help-you)
 - [Release notes](#release-notes)
+  * [Version 1.5.0](#version-150)
 - [License](#license)
 
 <!-- tocstop -->
 
 <a name="requirements"></a>
 ## 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
+The latest release of the SDK supports Python 3 only, see below for exact support status of Python versions.
+
+Only the official CPython (that is, the "normal" Python, i.e. the Python implementation
 from <https://python.org>) is supported and only on Linux (musl libc which is used, e.g., on Alpine Linux, is currently not supported)
 and Windows with the x86 (including x86-64) architecture.
-Additionally, `pip` ≥ 8.1.0 (2016-03-05) is required for installation, and on Linux, the system should be
-[`manylinux1`-compatible](https://www.python.org/dev/peps/pep-0513/) to ensure a smooth installation via `pip`.
+It is always advised to use the latest patch version of your minor versoin of Python, as these usually contain security
+fixes and other important bugfixes.
+
+Additionally, `pip` with the `wheel` and `setuptools` package installed is required for installation,
+and on Linux, the system needs to be [`manylinux1`-compatible](https://www.python.org/dev/peps/pep-0513/).
+`pip` versions before 8.1.0 are known not to work, but generally it is advised to always use the latest pip version.
+Due to factors such as changes in package hosting by PyPI and Python itself,
+Dynatrace cannot guarantee that SDK installation is, or will continue to be,
+possible with old pip versions.
 
 The Dynatrace OneAgent SDK for Python is a wrapper of the [Dynatrace OneAgent SDK for C/C++](https://github.com/Dynatrace/OneAgent-SDK-for-C)
 and therefore the SDK for C/C++ is required and delivered with the Python SDK. See
@@ -56,17 +68,34 @@ Dynatrace OneAgent version (it is the same as
 
 <a name="pycversiontab"></a>
 
-|OneAgent SDK for Python|OneAgent SDK for C/C++|Dynatrace OneAgent|Support status     |
-|:----------------------|:---------------------|:-----------------|:------------------|
-|1.4                    |1.6.1                 |≥1.179            |Supported          |
-|1.3                    |1.5.1                 |≥1.179            |Supported          |
-|1.2                    |1.4.1                 |≥1.161            |Deprecated¹        |
-|1.1                    |1.3.1                 |≥1.151            |Deprecated¹        |
-|1.0                    |1.1.0                 |≥1.141            |EAP (not supported)|
+|OneAgent SDK for Python|Bundled OneAgent SDK for C/C++|Required OneAgent|Required Python|Support status |
+|:----------------------|:-----------------------------|:----------------|:--------------|:--------------|
+|1.5                    |1.7.1                         |≥1.251           |≥3.5           |Supported|
+|1.4                    |1.6.1                         |≥1.179           |2.7.x or ≥3.4  |Supported|
+|1.3                    |1.5.1                         |≥1.179           |2.7.x or ≥3.4  |Deprecated with support ending 2023-07-01|
+|1.2                    |1.4.1                         |≥1.161           |2.7.x or ≥3.4  |Deprecated with support ending 2023-07-01|
+|1.1                    |1.3.1                         |≥1.151           |2.7.x or ≥3.4  |Deprecated with support ending 2023-07-01|
+|1.0                    |1.1.0                         |≥1.141           |2.7.x or ≥3.4  |Deprecated with support ending 2023-07-01|
+
+Note that this table only states the support status of the mentioned OneAgent SDK for Python version
+with the included OneAgent SDK for C/C++, not the OneAgent itself.
+
+The "required Python" column indicates the Python versions with which the SDK version was developed and tested.
+We may additionally announce deprecations for older versions of Python in combination with specific or all versions of the SDK,
+meaning that we will no longer provide support for these combinations after the given date, even if the SDK version itself
+is supported and technically running on that Python version.
+We also strongly advise against using Python versions that are no longer supported by your Python vendor.
+
+We intend to deprecate Python versions effective around 6 months after the Python project stops supporting them as documented by the
+Python project: <https://devguide.python.org/versions/>. We will announce every deprecation explicitly, usually 6 months before
+it becomes effective.
 
-> 1. *Deprecated* releases of the OneAgent SDK for Python are still supported but this
-> might change with a future release. Applications using those deprecated versions should
-> be upgraded to the latest release.
+<a name="pysupporttab"></a>
+
+| Python version | Deprecation status |
+|:---------------|:---------------|
+| 3.4.x-3.6.x    | Deprecation announcement with exact date pending, *not before* 2023-07-01 |
+| 2.7.x          | Deprecated with support (with compatible SDK versions) ending 2023-07-01 |
 
 <a name="#using-the-oneagent-sdk-for-python-in-your-application"></a>
 ## Using the OneAgent SDK for Python in your application
@@ -80,6 +109,8 @@ To install the latest version of the OneAgent SDK for Python, use the PyPI packa
 python -m pip install --upgrade oneagent-sdk
 ```
 
+`pip`, `setuptools` and `wheel` need to be installed and should be up to date before running this command.
+
 To verify your installation, execute
 
 ```bash
@@ -218,6 +249,7 @@ A more detailed specification of the features can be found in [Dynatrace OneAgen
 
 |Feature                                   |Required OneAgent SDK for Python version|
 |:-----------------------------------------|:--------|
+|W3C trace context for log enrichment      |≥1.5.0   |
 |Custom services                           |≥1.2.0   |
 |Messaging                                 |≥1.2.0   |
 |In-process linking                        |≥1.1.0   |
@@ -546,6 +578,35 @@ See the documentation for more information:
 * [General information on tagging](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/tagging.html)
 * [Messaging tracers in the specification repository](https://github.com/Dynatrace/OneAgent-SDK#messaging)
 
+<a name="w3c-trace-context"></a>
+## W3C trace context
+
+This feature allows you to retrieve a W3C TraceContext trace ID and span ID referencing the current PurePath node,
+as defined in <https://www.w3.org/TR/trace-context>.
+
+This trace ID and span ID information is not intended for tagging and
+context-propagation scenarios and primarily designed for log-enrichment use
+cases. Refer to [General information on tagging](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/tagging.html)
+for tagging traces (see also the usage examples elsewhere in this document).
+
+The following example shows how to print the current trace & span ID to stdout
+in a format that works well with Dynatrace Log Monitoring
+(see <https://www.dynatrace.com/support/help/shortlink/log-monitoring-log-enrichment> for more):
+
+```python
+with sdk.trace_custom_service('onTimer', 'CleanupTask'): # Or any other tracer
+	tinfo = sdk.tracecontext_get_current()
+	print('[!dt dt.trace_id={},dt.span_id={}] handle incoming message'.format(tinfo.trace_id, tinfo.span_id))
+```
+
+See the documentation for more information:
+
+* [`tracecontext_get_current`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.SDK.tracecontext_get_current)
+* [Information on trace tagging](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/tagging.html)
+* [W3C trace context in the SDK specification repository](https://github.com/Dynatrace/OneAgent-SDK#tracecontext)
+
+
+
 <a name="forking"></a>
 <a name="using-the-oneagent-sdk-for-python-with-forked-child-processes-only-available-on-linux"></a>
 ## Using the OneAgent SDK for Python with forked child processes (only available on Linux)
@@ -708,7 +769,6 @@ Make sure your issue is not already solved in the [available documentation](#doc
 
 **Open a [GitHub issue](https://github.com/Dynatrace/OneAgent-SDK-for-Python/issues) 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.
@@ -722,25 +782,20 @@ SLAs apply according to the customer's support level.
 <a name="release-notes"></a>
 ## Release notes
 
-### Version 1.4.0
+### Version 1.5.0
 
-* Don't look for agent module in `PATH/LD_LIBRARY_PATH/..`. and
-disallow a relative path in the `DT_HOME` directory on Windows to prevent DLL hijacking issues.
+Changes:
 
-* Fixed a bug that might lead to crashes in the SDK's shutdown phase
+* Adds limited [W3C trace context](#w3c-trace-context) support (for log enrichment).
+* This version **no longer supports Python 2 (Python 2.7.x)**.
+* This version **no longer supports Python 3.4.x**.
 
-* Support for **Python versions < 3.5** is deprecated. The OneAgent SDK for Python
-will still work with this release, but this might change in the future.
+Announcements:
 
-* Following versions of the **OneAgent SDK for Python** are considered deprecated
-and might not be supported in the future. Applications using it should be upgraded to the latest release.
-  * [Version 1.1.0](https://github.com/Dynatrace/OneAgent-SDK-for-Python/releases/tag/v1.1.0)
-  * [Version 1.2.0](https://github.com/Dynatrace/OneAgent-SDK-for-Python/releases/tag/v1.2.0)
-  * [Version 1.2.1](https://github.com/Dynatrace/OneAgent-SDK-for-Python/releases/tag/v1.2.1)
+* ⚠️ **Deprecation announcement for older SDK versions:** Version 1.3 and all older versions have been put on the path to deprecation and will no longer be supported starting July 1, 2023. We strongly advise customers to upgrade to newest versions to avoid incompatibility and security risks. Customers need to upgrade to at least 1.4 but are encouraged to upgrade to the newest available version (1.5) if using Python >3.4 as there are no known incompatibilities or breaking changes other than the increased minimum Python version.
+* ⚠️ **Deprecation announcement for using any SDK version with older Python versions:** Python 2.7.x has been put on the path to deprecation and no version of the SDK will be supported on this Python version starting July 1, 2023. Furthermore, we intend to release a similar deprecation announcement regarding versions 3.4-3.6 (which are no longer maintained by the Python project) soon (we plan that this will not become effective before 2023-07-01).
 
-> For older versions of the OneAgent SDK for Python, please see
-the [GitHub releases page](https://github.com/Dynatrace/OneAgent-SDK-for-Python/releases),
-and the [PyPI release history](https://pypi.org/project/oneagent-sdk/#history).
+See <https://github.com/Dynatrace/OneAgent-SDK-for-Python/releases> for older releases.
 
 <a name="license"></a>
 ## License

constraints.txt

@@ -1 +1,6 @@
-pylint<2.5
+tox<4
+pylint<2.5; python_version >= '3.0'
+pylint<1.10; python_version < '3.0'
+sphinx<6
+pytest<5; python_version < '3.5'
+pytest<7.2; python_version >= '3.5'

docs/conf.py

@@ -39,17 +39,6 @@
 
 from oneagent.version import __version__ as version
 
-# Fix spurious "= None" for instance attributes
-# https://github.com/sphinx-doc/sphinx/issues/2044
-from sphinx.ext.autodoc import (
-    ClassLevelDocumenter, InstanceAttributeDocumenter)
-
-def iad_add_directive_header(self, sig):
-    ClassLevelDocumenter.add_directive_header(self, sig)
-
-InstanceAttributeDocumenter.add_directive_header = iad_add_directive_header
-
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -96,7 +85,7 @@ def iad_add_directive_header(self, sig):
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -121,7 +110,7 @@ def iad_add_directive_header(self, sig):
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {'sidebarwidth': 500}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/tagging.rst

@@ -120,3 +120,6 @@ Note these points:
 * You should take care that obtaining the incoming tag is not an expensive
   operation, as it can not be accounted for in the timings of the resulting
   path.
+* Both the string and byte tag are returned as a :class:`bytes` object
+  (:code:`str` bytestring in Python 2).
+  This is due to an oversight that cannot be fixed anymore without breaking compatibility.

samples/basic-sdk-sample/basic_sdk_sample.py

@@ -219,7 +219,12 @@ def mock_process_incoming_message():
             # the tracer ends.
             tracer.set_vendor_message_id('message_id')
             with tracer:
-                print('handle incoming message')
+
+                # Use tracecontext_get_current to log a trace/span ID identifiying the current node.
+                tinfo = sdk.tracecontext_get_current()
+                print('[!dt dt.trace_id={},dt.span_id={}] handle incoming message'.format(
+                    tinfo.trace_id, tinfo.span_id))
+
                 tracer.set_correlation_id('correlation_id')
 
 def mock_outgoing_message():

src/oneagent/__init__.py

@@ -242,7 +242,7 @@ def initialize(sdkopts=(), sdklibname=None, forkable=False):
         Python SDK version.
     :param bool forkable: Use the SDK in 'forkable' mode.
 
-    :rtype: .InitResult
+    :rtype: InitResult
     '''
 
     global _sdk_ref_count #pylint:disable=global-statement

src/oneagent/_impl/native/sdkctypesiface.py

@@ -41,6 +41,9 @@
 CCSID_UTF16_BE = 1201
 CCSID_UTF16_LE = 1203
 
+_ONESDK_TRACE_ID_BUFFER_SIZE = 33
+_ONESDK_SPAN_ID_BUFFER_SIZE = 17
+
 bool_t = ctypes.c_int32
 result_t = ctypes.c_uint32 if WIN32 else ctypes.c_int32
 xchar_p = ctypes.c_wchar_p if WIN32 else ctypes.c_char_p
@@ -503,6 +506,8 @@ def __init__(self, libname):
 
         self._init_custom_service()
 
+        self._init_trace_context()
+
 
     def _init_custom_service(self):
         initfn = self._initfn
@@ -566,6 +571,15 @@ def _init_messaging(self):
             (handle_t, CCStringPInArg),
             None).__doc__ = '(tracer_handle, correlation_id)'
 
+    def _init_trace_context(self):
+        initfn = self._initfn
+        initfn(
+            'tracecontext_get_current',
+            (ctypes.c_char_p, ctypes.c_size_t, ctypes.c_char_p, ctypes.c_size_t,),
+            result_t,
+            public=False)
+
+
 
     def initialize(self, init_flags=0):
         result = self._initialize_2(init_flags)
@@ -761,6 +775,14 @@ def tracer_get_outgoing_tag(self, tracer, use_byte_tag=False):
         assert cnt + 1 == tagsz.value
         return buf.value
 
+    def tracecontext_get_current(self):
+        trace_id_buf = ctypes.create_string_buffer(b'0' * (_ONESDK_TRACE_ID_BUFFER_SIZE - 1))
+        span_id_buf = ctypes.create_string_buffer(b'0' * (_ONESDK_SPAN_ID_BUFFER_SIZE - 1))
+        result = self._tracecontext_get_current(
+            trace_id_buf, len(trace_id_buf), span_id_buf, len(span_id_buf))
+        return result, u8_to_str(trace_id_buf.value), u8_to_str(span_id_buf.value)
+
+
     def tracer_set_incoming_byte_tag(self, tracer, tag):
         self._tracer_set_incoming_dynatrace_byte_tag(tracer, tag, len(tag))
 

src/oneagent/_impl/native/sdknulliface.py

@@ -209,9 +209,9 @@ def tracer_error(self, tracer_h, error_class, error_message):
         pass
 
     def tracer_get_outgoing_tag(self, tracer_h, use_byte_tag=False):
-        if use_byte_tag:
-            return six.binary_type()
-        return six.text_type()
+        # This was originally meant to return a string for use_byte_tag=False
+        # but the real implementation doesn't do it that way.
+        return six.binary_type()
 
     def tracer_set_incoming_string_tag(self, tracer_h, tag):
         pass
@@ -281,3 +281,6 @@ def incomingmessageprocesstracer_set_correlation_id(self, handle, correlation_id
 
     def customservicetracer_create(self, service_method, service_name):
         return NULL_HANDLE
+
+    def tracecontext_get_current(self):
+        return (ErrorCode.NO_DATA, '00000000000000000000000000000000', '0000000000000000')