dt-extensions-sdk 1.1.2__tar.gz → 1.1.4__tar.gz

{dt_extensions_sdk-1.1.2 → dt_extensions_sdk-1.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dt-extensions-sdk
-Version: 1.1.2
+Version: 1.1.4
 Project-URL: Documentation, https://github.com/dynatrace-extensions/dt-extensions-python-sdk#readme
 Project-URL: Issues, https://github.com/dynatrace-extensions/dt-extensions-python-sdk/issues
 Project-URL: Source, https://github.com/dynatrace-extensions/dt-extensions-python-sdk

{dt_extensions_sdk-1.1.2 → dt_extensions_sdk-1.1.4}/docs/guides/extension_structure.rst

@@ -1,7 +1,7 @@
 Extension Structure
 ===================
 
-The basic barebone structure of an extension is as follows:
+The basic bare-bone structure of an extension is as follows:
 
 .. code:: bash
 

{dt_extensions_sdk-1.1.2 → dt_extensions_sdk-1.1.4}/docs/guides/installation.rst

@@ -9,7 +9,7 @@ Requirements
 ``dt-extensions-sdk`` requires only the following dependencies to be
 present in the environment.
 
-- Python >= 3.7, < 4.0
+- Python >= 3.10
 
 Installing from PyPI
 ^^^^^^^^^^^^^^^^^^^^

dt_extensions_sdk-1.1.4/docs/guides/migration.rst

@@ -0,0 +1,159 @@
+Migrating EF1 Extensions
+########################
+
+| Use this guide to understand how to migrate an existing Python EF1 extension to the new EF2 format.
+
+Requirements
+============
+
+* `Python 3.10 or later <https://www.python.org/downloads/>`_
+* ``dt-extensions-sdk`` installed and in your ``PATH`` (you can run with ``dt-sdk --help``).
+* `VSCode <https://code.visualstudio.com>`_ with the `Dynatrace Extensions <https://marketplace.visualstudio.com/items?itemName=DynatracePlatformExtensions.dynatrace-extensions>`_ extension installed.
+
+Step by Step
+============
+
+
+To migrate an existing python EF1 extension using VSCode, the steps are as follows:
+
+1. Create a new EF2 extension
+2. Import the EF1 extension using the ``Dynatrace extensions: Convert Python`` command
+3. Convert the code, moving the class from the original extension to the ``__main__.py`` file of the new extension
+
+
+Create a new EF2 extension
+""""""""""""""""""""""""""
+
+1. Open an empty folder in VSCode, then run the ``Dynatrace extensions: Initialize Workspace`` command
+2. Select the schema version (latest recommended), and the certificates you want to use to sign the extension
+
+|
+
+.. image:: ../_static/img/migrate-01-new-extension.png
+  :alt: Init workspace
+|
+
+3. Chose the ``Python Extension 2.0`` project type
+4. Give your extension a name, it must respect the python module naming convention (all lower case with optional underscores).
+
+|
+
+.. image:: ../_static/img/migrate-02-type.png
+  :alt: Chose project type
+|
+
+Import the Python EF1 extension
+"""""""""""""""""""""""""""""""
+
+| The first step is to convert the old ``plugin.json`` file to the new ``activationSchema.json`` format.
+| This will automatically create the **Settings 2.0 UI** for your extension, which defines the UI for the user to configure the extension.
+|
+| Run the command ``Dynatrace extensions: Convert Python``.
+| You can chose to import an existing python extension from:
+|
+* The extension zip file
+* The plugin.json file
+* From your Dynatrace environment
+
+|
+
+.. image:: ../_static/img/migrate-03-import.png
+  :alt: Import extension
+|
+
+| In this example we are importing from a Dynatrace environment, which gives you a list of all python extensions on that environment.
+|
+| If you would like to import from your computer, a file picker will open, and you can select the zip or plugin.json file of your extension.
+
+|
+
+.. image:: ../_static/img/migrate-04-import-remote.png
+  :alt: Import from dynatrace
+|
+
+| After you select an extension, your ``activationSchema.json`` will be overwritten with the correct settings.
+|
+| You should also review that file, to make sure your UI looks the way you want it to.
+|
+
+.. note::
+   | If you are importing a local (OneAgent) extension, delete the entry **activation > remote** from the extension.yaml file.
+   | If instead you are importing a remote (Activegate) extension, delete **activation > local**.
+   | You can also make your extension work both remotely and locally, by keeping both entries and modifying the **activationSchema.json** file accordingly.
+
+Modify the extension code
+"""""""""""""""""""""""""
+
+.. note::
+   | We are working on automating part of this step.
+
+
+| Move your existing extension code to the ``__main__.py`` file of the new extension.
+| The easiest way to accomplish this is by pasting the code from your existing extension class into the new ``ExtensionImpl`` class.
+|
+| Here are the most important changes you need to make to your code:
+|
+
+
+.. list-table:: Code conversion reference
+   :widths: 40 10 10 40
+   :header-rows: 1
+
+   * - Description
+     - EF1 method
+     - EF2 method
+     - Notes
+   * - Logging
+     - ``self.logger.info("message")``
+     - ``self.logger.info("message")``
+     - Stays the same
+   * - Obtaining user defined parameters
+     - ``self.config.get("param_name", "default_value")``
+     - ``self.activation_config.get("param_name", "default_value")``
+     - You can find and replace all ``self.config.`` entries with ``self.activation_config.``
+   * - Report an event
+     - ``self.results_builder.report_custom_info_event``
+     - ``self.report_dt_event``
+     - Try to keep topology (groups, device, IDs) out of the code, this is defined later in the ``extension.yaml`` file.
+   * - Report a metric
+     - ``device.absolute("metric_key", metric_value, {"dimension_name": "dimension_value"})``
+     - ``self.report_metric("metric_key", metric_value, {"dimension_name": "dimension_value"})``
+     - There is no concept of a ``device`` in the python code anymore, send metrics directly.
+   * - Create groups and custom devices
+     - ``self.topology_builder.create_group``, ``group.create_device``
+     - ``n/a``
+     - Doesn't exist, topology is defined in the ``extension.yaml`` file.
+
+
+
+Build and upload the extension
+""""""""""""""""""""""""""""""
+
+| Build the extension by running the command ``Dynatrace extensions: Build``.
+| If the build is successful, you will see a prompt to upload the extension to your Dynatrace environment and activate it.
+| Accept both prompts
+|
+| Navigate to your Dynatrace environment, to ``Infrastructure Observability > Extensions`` and find your extension.
+
+|
+.. image:: ../_static/img/migrate-05-activation.png
+  :alt: Extension config
+|
+
+| Click ``Add monitoring configuration``
+| Check that your UI looks the way you want it to, and fill in the parameters.
+
+.. note::
+   | You can copy the ``value`` from the right side JSON Snippet and use it in your ``activation.json`` file to test your extension locall with ``dt-sdk run``
+|
+.. image:: ../_static/img/migrate-06-activation-config.png
+  :alt: Extension config
+|
+
+
+Limitations
+"""""""""""
+
+* The ``process snapshot`` is not yet supported, but will be added in the future. As a workaround the file ``<dynatrace_log_path>/dynatrace/oneagent/plugin/oneagent_latest_snapshot.log`` can be read and parsed as JSON.
+* The metric metadata and topology must be added to the ``extension.yaml`` file, part of this will be automated in the future.
+

{dt_extensions_sdk-1.1.2 → dt_extensions_sdk-1.1.4}/docs/index.rst

@@ -273,6 +273,7 @@ Documentation
 
    guides/installation
    guides/extension_structure
+   guides/migration
 
 .. toctree::
    :caption: All Commands

{dt_extensions_sdk-1.1.2 → dt_extensions_sdk-1.1.4}/dynatrace_extension/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2023-present Dynatrace LLC
 #
 # SPDX-License-Identifier: MIT
-__version__ = "1.1.2"
+__version__ = "1.1.4"

{dt_extensions_sdk-1.1.2 → dt_extensions_sdk-1.1.4}/dynatrace_extension/sdk/communication.py

@@ -92,7 +92,7 @@ class CommunicationClient(ABC):
         pass
 
     @abstractmethod
-    def send_events(self, event: dict | list[dict]) -> dict | None:
+    def send_events(self, event: dict | list[dict], eec_enrichment: bool) -> dict | None:
         pass
 
     @abstractmethod
@@ -275,13 +275,16 @@ class HttpClient(CommunicationClient):
             responses.append(mint_response)
         return responses
 
-    def send_events(self, events: dict | list[dict]) -> dict | None:
+    def send_events(self, events: dict | list[dict], eec_enrichment: bool = True) -> dict | None:
         self.logger.debug(f"Sending log events: {events}")
         event_data = json.dumps(events).encode("utf-8")
         try:
             # EEC returns empty body on success
             return self._make_request(
-                self._events_url, "POST", event_data, extra_headers={"Content-Type": CONTENT_TYPE_JSON}
+                self._events_url,
+                "POST",
+                event_data,
+                extra_headers={"Content-Type": CONTENT_TYPE_JSON, "eec-enrichment": str(eec_enrichment).lower()},
             ).json()
         except json.JSONDecodeError:
             return None
@@ -394,8 +397,8 @@ class DebugClient(CommunicationClient):
             responses = [MintResponse(lines_invalid=0, lines_ok=len(mint_lines), error=None, warnings=None)]
         return responses
 
-    def send_events(self, events: dict | list[dict]) -> dict | None:
-        self.logger.info(f"send_events: {events}")
+    def send_events(self, events: dict | list[dict], eec_enrichment: bool = True) -> dict | None:
+        self.logger.info(f"send_events (enrichment = {eec_enrichment}): {events}")
         return None
 
     def send_sfm_metrics(self, mint_lines: list[str]) -> MintResponse:

{dt_extensions_sdk-1.1.2 → dt_extensions_sdk-1.1.4}/dynatrace_extension/sdk/extension.py

@@ -173,6 +173,9 @@ class Extension:
         self._task_id = "development_task_id"
         self._monitoring_config_id = "development_config_id"
 
+        # The user can override default EEC enrichment for logs
+        self.log_event_enrichment = True
+
         # The Communication client
         self._client: CommunicationClient = None  # type: ignore
 
@@ -456,6 +459,10 @@ class Extension:
             if "dt.techrule.id" not in dimensions:
                 dimensions["dt.techrule.id"] = techrule
 
+        if metric_type == MetricType.COUNT and timestamp is None:
+            # We must report a timestamp for count metrics
+            timestamp = datetime.now()
+
         metric = Metric(key=key, value=value, dimensions=dimensions, metric_type=metric_type, timestamp=timestamp)
         self._add_metric(metric)
 
@@ -984,7 +991,7 @@ class Extension:
             self._metrics.extend(lines)
 
     def _send_events_internal(self, events: Union[dict, List[dict]]):
-        response = self._client.send_events(events)
+        response = self._client.send_events(events, self.log_event_enrichment)
         with self._internal_callbacks_results_lock:
             self._internal_callbacks_results[self._send_events.__name__] = Status(StatusValue.OK)
             if not response or "error" not in response or "message" not in response["error"]:

{dt_extensions_sdk-1.1.2 → dt_extensions_sdk-1.1.4}/pyproject.toml

@@ -39,6 +39,9 @@ artifacts  = [
   "dynatrace_extension/cli/create/extension_template/**/*",
 ]
 
+[tool.hatch.build.targets.wheel]
+packages = ["dynatrace_extension"]
+
 [tool.hatch.envs.default]
 dependencies = [
     "coverage[toml]>=6.5",

{dt_extensions_sdk-1.1.2 → dt_extensions_sdk-1.1.4}/tests/sdk/test_extension.py

@@ -4,6 +4,8 @@ import unittest
 from datetime import datetime, timedelta
 from unittest.mock import MagicMock, mock_open, patch
 
+import pytest
+
 from dynatrace_extension import Status, StatusValue, get_helper_extension
 from dynatrace_extension.sdk.activation import ActivationConfig
 from dynatrace_extension.sdk.communication import HttpClient, MintResponse
@@ -681,13 +683,8 @@ class TestExtension(unittest.TestCase):
             def initialize(self):
                 raise AttributeError
 
-        ext = MyExtension()
-        ext._running_in_sim = True
-        ext._client = MagicMock()
-        ext._heartbeat_iteration()
-        current_status = ext._build_current_status()
-        assert current_status.status == StatusValue.GENERIC_ERROR
-        assert current_status.message == "Python datasource initialization error: AttributeError()"
+        with pytest.raises(AttributeError):
+            MyExtension()
 
     def test_report_mint_and_log_sending_failure(self):
         extension = get_helper_extension()