Dynatrace Extensions SDK for Python

https://dynatrace-extensions.github.io/dt-extensions-python-sdk
Admin
A Python library and toolbox for building, testing, packaging, and deploying Python extensions for...
Tokens:39,998
Snippets:293
Trust Score:8.3
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### setup.py example

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/guides/extension_structure.html

Standard Python setup file used to package the extension and install it on the ActiveGate or OneAgent. Must include dt-extensions-sdk in install_requires. Version must match extension.yaml. Extension size must not exceed 15MB.

```python
from setuptools import setup, find_packages

setup(
    name="my_extension",
    version="0.0.1",
    description="My_extension python EF2 extension",
    author="Dynatrace",
    packages=find_packages(),
    python_requires=">=3.10",
    include_package_data=True,
    install_requires=["dt-extensions-sdk"],
    extras_require={"dev": ["dt-extensions-sdk[cli]"]},
)

```

--------------------------------

### Install dt-extensions-sdk in a virtual environment

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/index.rst.txt

Recommended approach when working on multiple extensions. Creates a virtual environment, activates it, and installs the SDK to isolate dependencies.

```bash
python -m venv .venv
source .venv/bin/activate
pip install dt-extensions-sdk
```

--------------------------------

### Start extension loop with initial iterations

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Starts the main extension loop, scheduling pre-run callbacks and running initial metric, event, SFM metrics, and time difference iterations before starting the scheduler.

```python
def _start_extension_loop(self):
    api_logger.debug(f"Starting main loop for monitoring configuration: '{self.monitoring_config_name}'")

    # These were scheduled before the extension started, schedule them now
    for callback in self._scheduled_callbacks_before_run:
        self._schedule_callback(callback)
    self._metrics_iteration()
    self._events_iteration()
    self._sfm_metrics_iteration()
    self._timediff_iteration()
    self._scheduler.run()
```

--------------------------------

### Install dt-extensions-sdk with CLI support

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/guides/installation.rst.txt

Installs the SDK along with optional CLI dependencies. This makes the dt-sdk binary available in the PATH.

```bash
pip install dt-extensions-sdk[cli]
```

--------------------------------

### Extension.run()

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/api/extension.html

Launches the extension instance and starts the main loop.

```APIDOC
## Extension.run()

### Description
Launches the extension instance. This method starts the main loop of the extension and must be invoked once to start the extension. If `--fastcheck` is set, the extension runs in fastcheck mode; otherwise, the main loop periodically runs scheduled callbacks, the heartbeat method, and the metrics publisher method.

### Method
run()

### Parameters
None

### Returns
None

### Example
```python
extension.run()
```
```

--------------------------------

### run method to start extension

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Launches the extension instance. If --fastcheck is set, runs in fastcheck mode; otherwise starts the main loop that periodically runs scheduled callbacks, heartbeat, and metrics publisher.

```python
def run(self):
        """Launch the extension instance.

        Calling this method starts the main loop of the extension.

        This method must be invoked once to start the extension,

        if `--fastcheck` is set, the extension will run in fastcheck mode,
        otherwise the main loop is started, which periodically runs:

        * The scheduled callbacks
        * The heartbeat method
        * The metrics publisher method
        """

        self._setup_signal_handlers()
        if self._is_fastcheck:
            return self._run_fastcheck()
        self._start_extension_loop()
```

--------------------------------

### Setup.py for Python Extension

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/guides/extension_structure.rst.txt

Standard Python setup file for packaging the extension. Must include dt-extensions-sdk in install_requires. Version must match extension.yaml. Dependencies increase size; keep under 15MB.

```python
from setuptools import setup, find_packages

setup(
    name="my_extension",
    version="0.0.1",
    description="My_extension python EF2 extension",
    author="Dynatrace",
    packages=find_packages(),
    python_requires=">=3.10",
    include_package_data=True,
    install_requires=["dt-extensions-sdk"],
    extras_require={"dev": ["dt-extensions-sdk[cli]"]},
)
```

--------------------------------

### Extension.initialize()

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/api/extension.html

Callback to be executed when the extension starts.

```APIDOC
## Extension.initialize()

### Description
Callback to be executed when the extension starts. Called once after the extension starts and the process arguments are parsed. This method can be used for tasks that must happen before runtime but after the activation config has been received, such as setting the schedule frequency based on user input.

### Method
initialize()

### Parameters
None

### Returns
Status | None - None or Status(StatusValue.OK) to indicate successful initialization. A Status with any error StatusValue to abort startup.

### Example
```python
def initialize(self):
    return Status(StatusValue.OK)
```
```

--------------------------------

### activationSchema.json example

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/guides/extension_structure.html

Example activation schema for a Python remote extension. Defines a single 'host' field and includes metadata like schemaId, maturity, and allowedScopes. The schema generated by the Create command is larger and contains more fields, passwords, and list items.

```json
{
    "types": {
        "pythonRemote": {
            "type": "object",
            "properties": {
                "host": {
                "displayName": "Host",
                "type": "text",
                "nullable": false,
                "default": ""
                }
            }
        }
    },
    "dynatrace": "1",
    "description": "Extension configuration",
    "schemaId": "python-extension.activation",
    "displayName": "Extension configuration",
    "ownerProductManagement": "Albus Dumbledore",
    "ownerDevelopment": "Peter Parker",
    "maturity": "GENERAL_AVAILABILITY",
    "allowedScopes": ["environment"],
    "multiObject": false,
    "properties": {
        "pythonRemote": {
        "displayName": "Python Remote Extension",
            "type": {
                "$ref": "#/types/pythonRemote"
            }
        }
    }
}
```

--------------------------------

### Signal handler setup

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Sets up signal handlers for SIGBREAK on Windows and SIGINT on all platforms, delegating to _shutdown_signal_handler.

```python
def _setup_signal_handlers(self):
        if sys.platform == "win32":
            signal.signal(signal.SIGBREAK, self._shutdown_signal_handler)
        signal.signal(signal.SIGINT, self._shutdown_signal_handler)
```

--------------------------------

### Build with local PyPI mirror from Windows PowerShell

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/guides/building.rst.txt

Use when building from Windows PowerShell to use a local PyPI mirror. Sets the same environment variables as the Linux example.

```bash
$ENV:PIP_INDEX_URL="http://my-pypi-server:8080/simple"; $ENV:PIP_TRUSTED_HOST="my-pypi-server"; dt-sdk build
```

--------------------------------

### Get version method

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Return the extension version from activation config.

```python
    def get_version(self) -> str:
        """Return the extension version."""
        return self.activation_config.version
```

--------------------------------

### Sample extension.yaml configuration

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/guides/extension_structure.rst.txt

Example of the main configuration file for a Dynatrace extension. It defines the extension name, version, minimal Dynatrace version, Python runtime, and activation schema paths.

```yaml
name: custom:my-extension
version: 0.0.1
minDynatraceVersion: "1.285"
author:
  name: "Dynatrace"

python:
  runtime:
    module: my_extension
    version:
      min: "3.10"

  activation:
    remote:
      path: activationSchema.json
    local:
      path: activationSchema.json
```

--------------------------------

### Get activation config method

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Retrieve the activation config assigned to this extension instance.

```python
    def get_activation_config(self) -> ActivationConfig:
        """Retrieve the activation config.

        Represents activation configuration assigned to this particular
        extension instance.

        Returns:
            ActivationConfig object.
        """
        return self.activation_config
```

--------------------------------

### Schedule a method in extension initialize

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/index.rst.txt

Shows how to override the initialize method to schedule a custom method to run at a different interval. The example schedules 'my_method' to run every 5 minutes.

```python
def initialize(self):
    # Schedule the my_method method to run every 5 minutes
    self.schedule(self.my_method, timedelta(minutes=5))
```

--------------------------------

### Build with local PyPI mirror using PIP_INDEX_URL and PIP_TRUSTED_HOST

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/guides/building.rst.txt

Use to build against a local PyPI mirror. The SDK uses pip under the covers, so all environment variables that pip supports can be used with the SDK. This example assumes a Linux build machine.

```bash
 PIP_INDEX_URL=http://my-pypi-server:8080/simple PIP_TRUSTED_HOST=my-pypi-server dt-sdk build
```

--------------------------------

### Schedule a method with self.schedule in initialize()

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/index.html

Override `dynatrace_extension.Extension.initialize()` to schedule additional methods at custom intervals. This example schedules `my_method` to run every 5 minutes using `self.schedule`.

```python
def initialize(self):
    # Schedule the my_method method to run every 5 minutes
    self.schedule(self.my_method, timedelta(minutes=5))

```

--------------------------------

### Extension class initialization with executors and state

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Initializes thread pools for callbacks, internal tasks, and heartbeat, along with locks and data structures for metrics, logs, self-monitoring, and endpoint statuses. Also parses arguments, schedules decorators, and logs the starting message.

```python
# Executors for the callbacks and internal methods
        self._callbacks_executor = ThreadPoolExecutor(max_workers=CALLBACKS_THREAD_POOL_SIZE)
        self._internal_executor = ThreadPoolExecutor(max_workers=INTERNAL_THREAD_POOL_SIZE)
        self._heartbeat_executor = ThreadPoolExecutor(max_workers=HEARTBEAT_THREAD_POOL_SIZE)

        # Extension metrics
        self._metrics_lock = RLock()
        self._metrics: list[str] = []

        # Extension logs
        self._logs_lock = RLock()
        self._logs: list[dict] = []

        # Self monitoring metrics
        self._sfm_metrics_lock = Lock()
        self._callbackSfmReport: dict[str, WrappedCallback] = {}

        # Count metric delta signals
        self._delta_signal_buffer: set[str] = set()
        self._registered_count_metrics: set[str] = set()

        # Self tech rule
        self._techrule = ""

        # Error message from caught exception in self.initialize()
        self._initialization_error: str = ""

        # Map of all Endpoint Statuses
        self._sfm_logs_allowed = not self.extension_name.startswith("custom:")
        if not self._sfm_logs_allowed:
            self.logger.warning("SFM logs not allowed for custom extensions.")

        self._ep_statuses = EndpointStatusesMap(send_sfm_logs_function=self._send_sfm_logs)

        self._parse_args()

        for function, interval, args, activation_type in Extension.schedule_decorators:
            params = (self,)
            if args is not None:
                params = params + args
            self.schedule(function, interval, params, activation_type)

        starting_message = f"Starting {self}"
        api_logger.info("-" * len(starting_message))
        api_logger.info(starting_message)
        api_logger.info("-" * len(starting_message))
```

--------------------------------

### dt-sdk build --help output

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/cli/build.html

Shows the help output for the dt-sdk build command. The command runs wheel, assemble, and sign, downloading dependencies and creating and signing the extension zip file. The extension_dir argument defaults to the current directory, and options include --private-key, --target-directory, --extra-platform, --extra-index-url, --find-links, --only-extra-platforms, --python-version, and --no-index.

```bash
$ dt-sdk build --help
                                                                                
 Usage: dt-sdk build [OPTIONS] [extension_dir]                                  
                                                                                
 Runs wheel, assemble and sign. Downloads dependencies, creates and signs the   
 extension zip file                                                            
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   extension_dir      <path>  Path to the python extension [default: .]       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --private-key           -k      <path>  Path to the dev fused                │
│                                         key-certificate                      │
│                                         [default:                            │
│                                         /home/runner/.dynatrace/certificate… │
│ --target-directory      -t      <path>                                       │
│ --extra-platform        -e      <str>   Download wheels for an extra         │
│                                         platform                             │
│ --extra-index-url       -i      <str>   Extra index url to use when          │
│                                         downloading dependencies             │
│ --find-links            -f      <str>   Extra index url to use when          │
│                                         downloading dependencies             │
│ --only-extra-platforms  -o              Only build for the extra platforms,  │
│                                         useful when building from arm64      │
│                                         (mac)                                │
│ --python-version        -p      <str>   Python versions to download wheels   │
│                                         for. Supported: 3.10, 3.14           │
│ --no-index                              Pass --no-index to pip, ignoring the │
│                                         package index (only --find-links     │
│                                         sources will be used)                │
│ --help                                  Show this message and exit.          │
╰──────────────────────────────────────────────────────────────────────────────╯
```

--------------------------------

### Get and set next internal callback timestamp method

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Method to get the next timestamp for an internal callback and increment it by the interval.

```python
    def _get_and_set_next_internal_callback_timestamp(self, callback_name: str, interval: float) -> float:
        next_timestamp = self._next_internal_callbacks_timestamps[callback_name]
        self._next_internal_callbacks_timestamps[callback_name] += interval
        return next_timestamp
```

--------------------------------

### dt-sdk create --help

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/cli/create.html

Displays the help and usage information for the `dt-sdk create` command. Shows that the command requires an `extension_name` argument and supports an optional `--output`/`-o` path option.

```bash
$ dt-sdk create --help
                                                                                
 Usage: dt-sdk create [OPTIONS] {extension_name}                                
                                                                                
 Creates a new python extension                                                 
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    extension_name      <str>  [required]                                   │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --output  -o      <path>                                                     │
│ --help                    Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯

```

--------------------------------

### dt-sdk upload --help

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/cli/upload.html

Displays the help and usage information for the dt-sdk upload command, including the extension_path argument and options for tenant URL, API token, and validation.

```bash
$ dt-sdk upload --help
                                                                                
 Usage: dt-sdk upload [OPTIONS] [extension_path]                                
                                                                                
 Upload the extension to a Dynatrace environment                                
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   extension_path      <path>  Path to the extension folder or built zip file │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --tenant-url  -u      <str>  Dynatrace tenant URL                            │
│ --api-token   -t      <str>  Dynatrace API token                             │
│ --validate    -v             Validate only                                   │
│ --help                       Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯

```

--------------------------------

### Run command help: dt-sdk run --help

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/cli/run.html

Displays the help and usage information for the `dt-sdk run` command. It lists the `extension_dir` argument (default `.`) and options such as `--activation-config` (default `activation.json`), `--secrets` (default `secrets.json`), `--fastcheck`, `--local-ingest`, `--local-ingest-port` (default `14499`), and `--print-metrics`/`--no-print-metrics` (default `print-metrics`). Use this to see how to run an extension locally during development.

```bash
$ dt-sdk run --help
                                                                                
 Usage: dt-sdk run [OPTIONS] [extension_dir]                                    
                                                                                
 Runs an extension, this is used during development to locally run and test an  
 extension                                                                      
                                                                                
 :param extension_dir: The directory of the extension, by default this is the   
 current directory                                                              
 :param activation_config: The activation config file, by default this is       
 activation.json                                                                
 :param secrets: The secrets file to be used to enrich the activation config,   
 by default this is secrets.json                                                
 :param fast_check: If true, run a fastcheck and exits                          
 :param local_ingest: If true, send metrics to localhost:14499 on top of        
 printing them                                                                  
 :param local_ingest_port: The port to send metrics to, by default this is      
 14499                                                                          
 :param print_metrics: If true, print metrics to the console                    
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   extension_dir      <path>  [default: .]                                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --activation-config                          <str>  [default:                │
│                                                     activation.json]         │
│ --secrets                                    <str>  [default: secrets.json]  │
│ --fastcheck                                                                  │
│ --local-ingest                                                               │
│ --local-ingest-port                          <int>  [default: 14499]         │
│ --print-metrics        --no-print-metrics           [default: print-metrics] │
│ --help                                              Show this message and    │
│                                                     exit.                    │
╰──────────────────────────────────────────────────────────────────────────────╯

```

--------------------------------

### dt-sdk --help output

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/cli/help.html

Output of the dt-sdk --help command. Displays available options like --install-completion and --help, and lists commands include run, build, assemble, wheel, sign, upload, gencerts, create, format, lint, ruff-init, and version.

```bash
$ dt-sdk --help
                                                                                
 Usage: dt-sdk [OPTIONS] COMMAND [ARGS]...                                      
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.      │
│ --show-completion             Show completion for the current shell, to copy │
│                               it or customize the installation.              │
│ --help                        Show this message and exit.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ run        Runs an extension, this is used during development to locally run │
│            and test an extension                                             │
│ build      Runs wheel, assemble and sign. Downloads dependencies, creates    │
│            and signs the extension zip file                                  │
│ assemble   Creates the extension zip file, without signing it yet            │
│ wheel      Downloads the dependencies of the extension to the lib folder     │
│ sign       Signs the extension zip file using the provided fused             │
│            key-certificate                                                   │
│ upload     Upload the extension to a Dynatrace environment                   │
│ gencerts   Generate root and developer certificates and key                  │
│ create     Creates a new python extension                                    │
│ format     Runs ruff format on the extension code                            │
│ lint       Runs ruff check on the extension code                             │
│ ruff-init  Adds ruff rules if they don't exist already                       │
│ version    Version commands                                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

```

--------------------------------

### Build from Linux with --extra-platform

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/guides/building.html

Builds an extension from Linux, adding Windows-compatible wheel files.

```bash
dt-sdk build --extra-platform win_amd64
```

--------------------------------

### Techrule property getter

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Internal property used by the EEC to get the techrule.

```python
    @property
    def techrule(self) -> str:
        """Internal property used by the EEC."""

        return self._techrule
```

--------------------------------

### Build and sign extension with dt-sdk build

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/index.rst.txt

Shows the output of running `dt-sdk build` for an extension named my_extension. It downloads dependencies, builds a wheel, assembles the extension zip, signs it with a certificate, and places the signed file in the dist directory. The output includes stages 1, 2, and 3, and notes that the signed build is placed in the dist directory.

```bash
$ dt-sdk build
Building and signing extension from my_extension to None
Stage 1 - Download and build dependencies
Cleaning my_extension/extension/lib
Downloading dependencies to my_extension/extension/lib
Running: .venv/dt-extensions-sdk/bin/python -m pip wheel -w extension/lib .
Processing my_extension
Preparing metadata (setup.py) ... done
Collecting dt-extensions-sdk (from my-extension==0.0.1)
Using cached dt_extensions_sdk-1.1.0-py3-none-any.whl.metadata (1.8 kB)
Using cached dt_extensions_sdk-1.1.0-py3-none-any.whl (42 kB)
Saved ./extension/lib/dt_extensions_sdk-1.1.0-py3-none-any.whl
Building wheels for collected packages: my-extension
Building wheel for my-extension (setup.py) ... done
Created wheel for my-extension: filename=my_extension-0.0.1-py3-none-any.whl size=1985 sha256=19039181b70d68105512ad52b80129368724b3f15e0ba2a2b5fdb98cc710e705
Stored in directory: /private/var/folders/jd/s1xmb3jj31gcd11g3p4ncctm5q47pj/T/pip-ephem-wheel-cache-zqkysr41/wheels/9c/1c/44/e47f092abb0d0b281251f7cfc7b8d5993c2c5678b3acd80751
Successfully built my-extension
Installed dependencies to my_extension/extension/lib
Stage 2 - Create the extension zip file
Running: dt ext assemble --source my_extension/extension --output my_extension/dist/extension.zip --force
my_extension/dist/extension.zip file already exists, it will be overwritten!
Building my_extension/dist/extension.zip from my_extension/extension
Adding file: my_extension/extension/lib/my_extension-0.0.1-py3-none-any.whl as lib/my_extension-0.0.1-py3-none-any.whl
Adding file: my_extension/extension/lib/dt_extensions_sdk-1.1.0-py3-none-any.whl as lib/dt_extensions_sdk-1.1.0-py3-none-any.whl
Adding file: my_extension/extension/extension.yaml as extension.yaml
Adding file: my_extension/extension/activationSchema.json as activationSchema.json
Built the extension zip file to my_extension/dist/extension.zip
Stage 3 - Sign the extension
Signing file my_extension/dist/extension.zip to my_extension/dist/custom_my-extension-0.0.1.zip with certificate
/Users/myuser/.dynatrace/certificates/developer.pem
Running: dt ext sign --src my_extension/dist/extension.zip --output my_extension/dist/custom_my-extension-0.0.1.zip
--key /Users/myuser/.dynatrace/certificates/developer.pem --force
Created signed extension file my_extension/dist/custom_my-extension-0.0.1.zip
Stage 4 - Delete my_extension/dist/extension.zip
```

--------------------------------

### Get tags and fields dimensions method

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Parse primaryFields and primaryTags from an endpoint dict into a merged dimensions dictionary.

```python
    def get_tags_and_fields_dimensions(self, endpoint: dict) -> dict:
        """Parse primaryFields and primaryTags from an endpoint dict into a merged dimensions dictionary.

        Returns:
            Merged dictionary from primaryFields and primaryTags entries.
        """
        return {**self.get_fields_dimensions(endpoint), **self.get_tags_dimensions(endpoint)}
```

--------------------------------

### Get tags dimensions method

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Parse primaryTags from an endpoint dict into a dimensions dictionary. Returns empty dict if absent.

```python
    def get_tags_dimensions(self, endpoint: dict) -> dict:
        """Parse primaryTags from an endpoint dict into a dimensions dictionary.

        Returns:
            Dictionary mapping each tag's 'key' to its 'value', or empty dict if absent.
        """
        return {e["key"]: e.get("value") for e in endpoint.get("primaryTags") or [] if "key" in e}
```

--------------------------------

### Build from Linux with --extra-platform win_amd64

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/guides/building.rst.txt

Use when building from Linux to download Windows-compatible wheel files for the ActiveGate/OneAgent.

```bash
 dt-sdk build --extra-platform win_amd64
```

--------------------------------

### Get fields dimensions method

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Parse primaryFields from an endpoint dict into a dimensions dictionary. Returns empty dict if absent.

```python
    def get_fields_dimensions(self, endpoint: dict) -> dict:
        """Parse primaryFields from an endpoint dict into a dimensions dictionary.

        Returns:
            Dictionary mapping each field's 'key' to its 'value', or empty dict if absent.
        """
        return {e["key"]: e.get("value") for e in endpoint.get("primaryFields") or [] if "key" in e}
```

--------------------------------

### Build with local wheel directory using --find-links

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/guides/building.rst.txt

Use when you have manually downloaded the required wheel files into a directory on the build machine. The SDK uses that directory as the source for dependencies.

```bash
dt-sdk build --find-links /path/to/whl/files
```

--------------------------------

### Get snapshot method

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Retrieves an oneagent snapshot. If running in sim, checks snapshot file existence and raises FileNotFoundError if missing.

```python
    def get_snapshot(self, snapshot_file: Path | str | None = None) -> Snapshot:
        """Retrieves an oneagent snapshot.

        Args:
            snapshot_file: Optional path to the snapshot file, only used when running from dt-sdk run

        Returns:
            Snapshot object.
        """
        if self._running_in_sim:
            if snapshot_file is None:
                snapshot_file = Path("snapshot.json")
            if isinstance(snapshot_file, str):
                snapshot_file = Path(snapshot_file)
            if not snapshot_file.exists():
                msg = f"snapshot file '{snapshot_file}' not found"
                raise FileNotFoundError(msg)

        return Snapshot.parse_from_file(snapshot_file)
```

--------------------------------

### dt-sdk assemble --help

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/cli/assemble.html

Shows the help output for the `dt-sdk assemble` command, which creates an unsigned extension zip file. The `extension_dir` argument defaults to the current directory, and the `--force` option defaults to True, meaning the output zip file is overwritten by default.

```bash
$ dt-sdk assemble --help
                                                                                
 Usage: dt-sdk assemble [OPTIONS] [extension_dir]                               
                                                                                
 Creates the extension zip file, without signing it yet                         
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   extension_dir      <path>  Path to the python extension [default: .]       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --output  -o      <path>                                                     │
│ --force   -f              Force overwriting the output zip file              │
│                           [default: True]                                    │
│ --help                    Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯

```

--------------------------------

### Upload extension with dt-sdk upload

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/index.rst.txt

Shows the output of running `dt-sdk upload` to upload the signed extension to the environment. Requires the environment URL and an API token with upload permissions, provided via environment variables or command line arguments. The output confirms successful upload to the specified URL.

```bash
$ dt-sdk upload
Uploading extension dist/custom_my-extension-0.0.1.zip to https://<your_environment_url_here>/
Extension upload successful!
Extension dist/custom_my-extension-0.0.1.zip uploaded to https://<your_environment_url_here>/
```

--------------------------------

### Create a new extension with dt-sdk create

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/index.rst.txt

Generates a new extension named 'my_extension' from scratch. The command outputs a confirmation message.

```bash
$ dt-sdk create my_extension
Extension created at my_extension
```

--------------------------------

### report_dt_event

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Reports an event to Dynatrace using the event ingest API. Accepts event type, title, and optional parameters like start time, end time, timeout, entity selector, and properties.

```APIDOC
## report_dt_event

### Description
Reports an event to Dynatrace using the event ingest API. Accepts event type, title, and optional parameters like start time, end time, timeout, entity selector, and properties.

### Method
POST

### Endpoint
https://www.dynatrace.com/support/help/dynatrace-api/environment-api/events-v2/post-event

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **event_type** (string) - Required - The event type chosen from type Enum
- **title** (string) - Required - The title of the event
- **start_time** (integer) - Optional - The start time of event in UTC ms, if not set, current timestamp
- **end_time** (integer) - Optional - The end time of event in UTC ms, if not set, current timestamp + timeout
- **timeout** (integer) - Optional - The timeout of event in minutes, if not set, 15
- **entity_selector** (string) - Optional - The entity selector, if not set, the event is associated with environment entity
- **properties** (object) - Optional - A map of event properties

### Request Example
```json
{
  "eventType": "CUSTOM_INFO",
  "title": "Example event",
  "startTime": 1620000000000,
  "endTime": 1620003600000,
  "timeout": 15,
  "entitySelector": "entityId=HOST-123",
  "properties": {
    "key": "value"
  }
}
```

### Response
#### Success Response (200)
- **eventId** (string) - The ID of the created event

#### Response Example
```json
{
  "eventId": "string"
}
```
```

--------------------------------

### dt-sdk wheel --help

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/cli/wheel.html

Shows the help output for the wheel command, listing its arguments and options. The extension_dir argument defaults to '.' and the --python-version option supports 3.10 and 3.14.

```bash
$ dt-sdk wheel --help
                                                                                
 Usage: dt-sdk wheel [OPTIONS] [extension_dir]                                  
                                                                                
 Downloads the dependencies of the extension to the lib folder                  
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   extension_dir      <path>  Path to the python extension [default: .]       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --extra-platform        -e      <str>  Download wheels for an extra platform │
│ --extra-index-url       -i      <str>  Extra index url to use when           │
│                                        downloading dependencies              │
│ --find-links            -f      <str>  Extra index url to use when           │
│                                        downloading dependencies              │
│ --only-extra-platforms  -o             Only build for the extra platforms,   │
│                                        useful when building from arm64 (mac) │
│ --python-version        -p      <str>  Python versions to download wheels    │
│                                        for. Supported: 3.10, 3.14            │
│ --no-index                             Pass --no-index to pip, ignoring the  │
│                                        package index (only --find-links      │
│                                        sources will be used)                 │
│ --help                                 Show this message and exit.           │
╰──────────────────────────────────────────────────────────────────────────────╯

```

--------------------------------

### Argument parsing and client initialization in Extension.__init__

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Parses command-line arguments for the extension, distinguishing between production (EEC) and development (sim) modes. In dev mode, it creates a DebugClient with local ingest options; in EEC mode, it creates an HttpClient. Also initializes activation config, extension config, and feature sets.

```python
    def _parse_args(self):
        parser = ArgumentParser(description="Python extension parameters")

        # Production parameters, these are passed by the EEC
        parser.add_argument("--dsid", required=False, default=None)
        parser.add_argument("--url", required=False)
        parser.add_argument("--idtoken", required=False)
        parser.add_argument(
            "--loglevel",
            help="Set extension log level. Info is default.",
            type=str,
            choices=["debug", "info"],
            default="info",
        )
        parser.add_argument("--fastcheck", action="store_true", default=False)
        parser.add_argument("--monitoring_config_id", required=False, default=None)
        parser.add_argument("--local-ingest", action="store_true", default=False)
        parser.add_argument("--local-ingest-port", required=False, default=14499)

        # Debug parameters, these are used when running the extension locally
        parser.add_argument("--extensionconfig", required=False, default=None)
        parser.add_argument("--activationconfig", required=False, default="activation.json")
        parser.add_argument("--secrets", required=False, default="secrets.json")
        parser.add_argument("--no-print-metrics", required=False, action="store_true")

        args, _ = parser.parse_known_args()
        self._is_fastcheck = args.fastcheck
        if args.dsid is None:
            # DEV mode
            self._running_in_sim = True
            print_metrics = not args.no_print_metrics
            self._client = DebugClient(
                activation_config_path=args.activationconfig,
                extensionconfig_path=args.extensionconfig,
                logger=api_logger,
                secrets_path=args.secrets,
                local_ingest=args.local_ingest,
                local_ingest_port=args.local_ingest_port,
                print_metrics=print_metrics,
            )
            RuntimeProperties.set_default_log_level(args.loglevel)
        else:
            # EEC mode
            self._client = HttpClient(args.url, args.dsid, args.idtoken, api_logger)
            self._task_id = args.dsid
            self._monitoring_config_id = args.monitoring_config_id
            api_logger.info(f"DSID = {self.task_id}, monitoring config id = {self._monitoring_config_id}")

        self.activation_config = ActivationConfig(self._client.get_activation_config())
        self.extension_config = self._client.get_extension_config()
        self._feature_sets = self._client.get_feature_sets()

        self.monitoring_config_name = self.activation_config.description
        self.extension_version = self.activation_config.version
```

--------------------------------

### Prepare self-monitoring metrics

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_modules/dynatrace_extension/sdk/extension.html

Builds a list of mint metric lines for self-monitoring, including thread count and callback execution metrics.

```python
    def _prepare_sfm_metrics(self) -> list[str]:
        """Prepare self monitoring metrics.

        Builds the list of mint metric lines to send as self monitoring metrics.
        """

        sfm_metrics: list[Metric] = []
        sfm_dimensions = {"dt.extension.config.id": self.monitoring_config_id}
        _add_sfm_metric(
            SfmMetric("threads", active_count(), sfm_dimensions, client_facing=True, metric_type=MetricType.DELTA),
            sfm_metrics,
        )

        for name, callback in self._callbackSfmReport.items():
            sfm_dimensions = {"callback": name, "dt.extension.config.id": self.monitoring_config_id}
            _add_sfm_metric(
                SfmMetric(
                    "execution.time",
                    f"{callback.duration_interval_total:.4f}",
                    sfm_dimensions,
                    client_facing=True,
                    metric_type=MetricType.GAUGE,
                ),
                sfm_metrics,
            )
            _add_sfm_metric(
                SfmMetric(
                    "execution.total.count",
                    callback.executions_total,
                    sfm_dimensions,
                    client_facing=True,
                    metric_type=MetricType.DELTA,
                ),
                sfm_metrics,
            )
            _add_sfm_metric(
                SfmMetric(
                    "execution.count",
                    callback.executions_per_interval,
                    sfm_dimensions,
                    client_facing=True,
                    metric_type=MetricType.DELTA,
                ),
                sfm_metrics,
            )
            _add_sfm_metric(
                SfmMetric(
                    "execution.ok.count",
                    callback.ok_count,
                    sfm_dimensions,
                    client_facing=True,
                    metric_type=MetricType.DELTA,
                ),
                sfm_metrics,
            )
            _add_sfm_metric(
                SfmMetric(
                    "execution.timeout.count",
                    callback.timeouts_count,
                    sfm_dimensions,
                    client_facing=True,
                    metric_type=MetricType.DELTA,
                ),
                sfm_metrics,
            )
            _add_sfm_metric(
                SfmMetric(
                    "execution.exception.count",
                    callback.exception_count,
                    sfm_dimensions,
                    client_facing=True,
                    metric_type=MetricType.DELTA,
                ),
                sfm_metrics,
            )
            callback.clear_sfm_metrics()
        return [metric.to_mint_line() for metric in sfm_metrics]
```

--------------------------------

### Activation Config JSON

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/_sources/guides/extension_structure.rst.txt

Sample activation config for local testing with the CLI run command. Must include all mandatory fields from the Activation Schema and can reference secrets from secrets.json using {{key}} syntax.

```json
{
    "enabled": true,
    "description": "my_extension activation",
    "version": "0.0.1",
    "activationContext": "REMOTE",
    "pythonRemote": {
        "endpoints": [
            {
                "url": "http://127.0.0.1:15672",
                "user": "guest",
                "password": "{{myPassword}}"
            }
        ]
    }
}
```

--------------------------------

### Signed extension output path

Source: https://dynatrace-extensions.github.io/dt-extensions-python-sdk/index.html

Shows the location of the signed extension file after the build command completes.

```bash
dist/custom_my-extension-0.0.1.zip

```
Tokens:
Raw