Create WMI extension

Dynatrace provides you with a framework that you can use to extend your observability into data acquired directly from your Windows Management Instrumentation (WMI) monitored devices.

We assume the following:

Prerequisites and support

Learn the prerequisites and scope of the supported technologies. For limits applying to your extension, see Extensions 2.0 limits.

Supported Dynatrace versions

  • Dynatrace version 1.215+
  • Windows-based ActiveGate version 1.215+
  • OneAgent version 1.221+ (local extensions)

Monitored host

Local WMI extensions can be run on any OneAgent-supported Windows host without any special requirements. Make sure Extension Execution Controller is enabled at the environment or selected host level. For more information, see Extension Execution Controller.

A host you want to monitor using a remote WMI extension must meet the requirements described below, including remote permissions enabled and connectivity details configured to allow your ActiveGate to access the WMI monitoring data.

Remote enable permission on the host

A monitored host must have the Remote enable permission set.

  1. In the Microsoft Server Manager console, go to Administrative Tools > Computer Management.
  2. Expand Services and Applications, right-click WMI Control, and select Properties.
  3. Select the Security tab and then select the Security button.
  4. Add the user you'll use to call WMI and then select Remote Enable in the Allow column.

For more information, see Allowing Users Access to a Specific WMI Namespace in the Microsoft documentation.

Configure firewall to access remote WMI

To configure the firewall to access remote WMI, issue the following commands:

netsh advfirewall firewall set rule group="windows management instrumentation (wmi)" new enable=yes

and

netsh firewall set service RemoteAdmin enable

For more information, see Setting up a Remote WMI Connection in the Microsoft documentation.

Disable Remote UAC

Disable Remote UAC when using a local administrator account (without Active Directory).

PS> New-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System -Name LocalAccountTokenFilterPolicy -PropertyType DWord -Value 1 -Force

For more information, see Handling Remote Connections Under UAC in the Microsoft documentation.

Set up local user

To establish a connection to a WMI remote host, you need to use either a standard user or a user with administrator privileges, depending on the kind of data you want. You will add this user in monitoring configuration. We recommend that you create a dedicated local user group or user account on the target computer specifically for remote connections.

To limit user privileges to access only a remote connection to WMI

  1. In Windows, run the DCOMCNFG command.
  2. Go to Component Services > Computers, right-click My Computer, and select Properties.
  3. Select the COM Security tab.
  4. Under Launch and Activation Permissions, select Edit Limits.
  5. Select the ANONYMOUS LOGON name in the Group or user names box. Under Permissions for ANONYMOUS LOGON, select Remote Access in the Allow column.
  6. Select OK to save.

For more information, see the Microsoft documentation:

Set up a fixed port for WMI

  1. At the command prompt, enter: winmgmt -standalonehost
  2. Stop the WMI service:
    net stop winmgmt
  3. Restart the WMI service in a new service host:
    net start winmgmt
  4. Establish a new port number for the WMI service:
    netsh firewall add portopening TCP 24158 WMIFixedPort

For more information, see Setting Up a Fixed Port for WMI in the Microsoft documentation.

Define data scope

Create the inventory of the devices you'd like to reference in your extension, as well WMI properties you'll use as the source for your metric and dimension values.

In our example, we create a simple extension collecting disk and network details data from your WMI monitored devices.

Download
name: custom:wmi-extension
version: 0.0.1
minDynatraceVersion: "1.217"
author:
  name: Dynatrace
vars:
  - id: deviceFilter
    displayName: Filter
    type: variable

wmi:
  - group: WMIClasses
    interval: 1m
    featureSet: basic
    dimensions:
    - key: counter.name
      value: Name
    subgroups:
      - subgroup: LogicalDisk
        wmiNamespace: root\cimv2
        query: SELECT DeviceID, FreeSpace, Name, Size, DriveType FROM Win32_LogicalDisk WHERE var:deviceFilter
        dimensions:
        - key: disk.id
          value: column:DeviceID
        - key: disk.type
          value: column:DriveType
        metrics:
        - key: size
          value: column:Size
          type: gauge
          featureSet: basic
        - key: freeSpace
          value: column:FreeSpace
          type: gauge
          featureSet: basic
      - subgroup: Network
        interval: 1m
        wmiNamespace: root\cimv2
        query: SELECT Name, MACAddress, Speed, ServiceName FROM Win32_NetworkAdapter
        dimensions:
        - key: mac
          value: column:MACAddress
        - key: service.name
          value: column:ServiceName
        metrics:
        - key: speed
          value: column:Speed
          type: gauge
          featureSet: basic

Your WMI monitoring scope definition starts with the wmi YAML node. All the settings under the node pertain to the declared data source type (in this case, WMI).

WQL queries

WMI extensions rely on WMI namespaces and their classes. Your WMI extension extracts the dimension and metric values from WMI class properties using the WQL queries.

Most extension-related classes and properties reside in the root\civm2 namespace. To learn more about WMI namespaces and classes, see Windows Management Instrumentation in the Microsoft documentation.

In this example, we query the disk-related properties from the Win32_LogicalDisk class (DeviceID, FreeSpace, and Size) in the root\cimv2 namespace (wmiNamespace defined at the group level) and we filter the results to drive C with some FreeSpace left. Filtering is achieved with a variable; see monitoring configuration below. The values queried from WMI are then assigned to dimension and metric values and ingested into Dynatrace.

name: custom:wmi.wql.example
version: 0.0.1
minDynatraceVersion: "1.218"
author:
  name: Dynatrace
vars:
  - id: deviceFilter
    displayName: Filter
    type: variable

wmi:
  - group: WMIClasses
    featureSet: basic
    interval: 1m
    wmiNamespace: root\cimv2
    query: SELECT DeviceID, FreeSpace, Size FROM Win32_LogicalDisk WHERE var:deviceFilter
    dimensions:
      - key: disk.id
        value: column:DeviceID
    metrics:
      - key: size
        value: column:Size
        type: gauge
      - key: freeSpace
        value: column:FreeSpace
        type: gauge

Example monitoring configuration for your WQL query

This example shows how to pass the deviceFilter variable declared earlier in the extension.yaml.

[
  {
    "scope": "ag_group-my-activegate-group",
    "value": {
      "version": "1.0.0",
      "description": "WMI Simple",
      "enabled": true,
      "activationContext": "REMOTE",
      "wmiRemote": {
        "devices": [
          {
            "host" : "192.168.0.1",
            "user" : "DOMAIN\\Administrator",
            "password" : "Password1"
          }
        ]
      },
      "featureSets": ["basic"],
      "vars": {
        "deviceFilter": "DeviceID = 'C:' and FreeSpace > 0"
      }
    }
  }
]

Dimensions

For each level (extension, group, subgroup), you can define up to 25 dimensions.

Dimension key

The dimension key string must conform to the metrics ingestion protocol.

Note: For Dynatrace versions 1.215 and 1.217, a dimension node requires the id parameter in place of 'key'. Starting with Dynatrace version 1.219, it is recommended to use the key parameter, as id will be considered as deprecated.

Dimension value

Apart from simply instructing the extension to extract a dimension value from a property, you can also use the following methods:

  • WQL query extracted value. Prefix with column:.
    dimensions:
    - key: disk.id
      value: column:DeviceID
    
    Note that you must first query the DeviceID property in a related group or subgroup to use it as the dimension value.
  • Plain text. Prefix with const:.
    dimensions:
    - key: extension.owner
      value: const:Joe.Doe@somedomain.com
    
  • Monitoring configuration defined variable. Prefix with var:.
    dimensions:
    - key: public_ip
      value: var:public_ip
    - key: agent_version
      value: var:agent_version
    
  • Monitoring configuration–defined device details, such as device IP address or port. Use this:device.host.
    dimensions:
    - key: hostname
      value: this:device.host
    

Use variables with dimensions

If you want to make your extension dimension customizable with the data from the monitoring configuration, you can use variables that will be replaced by values passed from the monitoring configuration. To use variables, you must first declare them in your extension YAML file:

vars:
   - id: oneagent_version
     displayName: OneAgent version
     type: variable

Then you can reference them in the dimension definition. Prefix the variable name with var.

dimensions:
   - key: oneagent_version
     value: var:agent_version

Filter extracted dimensions

When extracting the dimension value, you can add filtering logic that will result in reporting only the dimensions matching the filtering criteria. To this, apply the WQL logic combined with monitoring configuration defined variables. See WQL queries as an example

Metrics

For each level (extension, group, subgroup), you can define up to 100 metrics.

For example:

wmi:
  - group: WMIClasses
    interval: 1m
    wmiNamespace: root\cimv2
    query: SELECT DeviceID, FreeSpace, Size FROM Win32_LogicalDisk
    dimensions:
      - key: disk.id
        value: column:DeviceID
    metrics:
      - key: size
        value: column:Size
        type: gauge
      - key: freeSpace
        value: column:FreeSpace
        type: gauge

Metric key

The metric key string must conform to the metrics ingestion protocol.

Note: For Dynatrace versions 1.215 and 1.217, a metric node requires the id parameter in place of 'key'. Starting with Dynatrace version 1.219, it is recommended to use the key parameter, as id will be considered as deprecated.

Best practices for metric keys

The metrics you ingest into Dynatrace using your extension are just some of the thousands of metrics, built-in and custom, processed by Dynatrace. To make your metrics keys unique and easy to identify in Dynatrace, the best practice is to prefix the metric name with the extension name. This guarantees that the metric key is unique and you can easily appoint a metric to a particular extension in your environment.

Metric value

The WMI property from which you want to extract the metric value.

Type

The Dynatrace Extensions 2.0 framework supports metric payloads in the gauge (gauge) or count value (count) formats. For details, see Metric payload. To indicate the metric type, use the type attribute.

Metric metadata

An Extension can define metadata for each metric available in Dynatrace. For example, you might want to add the metric display name and the unit, both of which can be used for filtering in the Metrics browser.

name: custom:example-extension-name
version: 1.0.0
minDynatraceVersion: "1.218"
author:
  name: Dynatrace

metrics:
  - key: your.metric.name
    metadata:
        displayName: Display name of the metric visible in Metrics browser
        unit: Count

Feature set

Feature sets are categories into which you organize the data collected by the extension. In this example, we create a WMI extension monitoring your devices and collecting metrics related to the transport protocol statistics and device disks. This is reflected by metrics organization into related feature sets tcp and physicalDisks.

wmi:
  group: Network_TCP
  interval: 1m
  featureSet: tcp
  subgroups:
    - subgroup: TCPv4
      query: SELECT  ConnectionsActive, ConnectionsEstablished FROM Win32_PerfFormattedData_Tcpip_TCPv4
      metrics:
      - key: com.dynatrace.extension.host-observability.network.tcp.connections.active
        value: column:ConnectionsActive
      - key: com.dynatrace.extension.host-observability.network.tcp.connections.established
        value: column:ConnectionsEstablished
      dimensions:
      - key: network.tcp.version
        value: const:ipv4
      - key: this.device
        value: this:device.host
    - subgroup: disk
      query: SELECT Name, DiskBytesPersec, DiskReadBytesPersec FROM Win32_PerfFormattedData_PerfDisk_PhysicalDisk
      featureSet: physicalDisks
      metrics:
      - key: com.dynatrace.extension.host-observability.disk.bytes.persec
        value: column:DiskBytesPersec
      - key: com.dynatrace.extension.host-observability.disk.read.persec.bytes
        value: column:DiskReadBytesPersec
      dimensions:
      - key: disk.type
        value: const:Physical
      - key: disk.name
        value: column:Name
      - key: this.device
        value: this:device.host

When activating your extension in monitoring configuration, you can limit monitoring to one of the feature sets.

In highly segmented networks, feature sets can reflect the segments of your environment. Then, when you create monitoring configuration, you can select a feature set and a corresponding ActiveGate group that can connect to that particular segment.

All metrics that aren't categorized into any feature set are considered to be default and are always reported.

Interval

The interval at which the data measurement will be taken. You can define intervals at the group, subgroup, or individual metric level. You can define intervals with the granularity of one minute (for example, 5m). The maximum interval is 2880m (2 days, 48 hours).

wmi:
  - group: Host
    interval: 1m
    query: SELECT Name, PercentProcessorTime FROM Win32_PerfFormattedData_PerfOS_Processor
    metrics:
    - key: com.dynatrace.extension.host-observability.host.cpu.time.processor
      value: column:PercentProcessorTime
    dimensions:
    - key: host.cpu.id
      value: column:Name

Monitoring configuration

After you define the scope of your configuration, you need to identify the network devices you'd like to collect data from and identify the ActiveGates that will execute the extension and connect to your devices.

Make sure that all the ActiveGates from the ActiveGate group you'll define as the scope can connect to a respective data source. You can assign an ActiveGate to a group during installation by using the --set-group-name installation parameter, or by configuring your ActiveGate.

The monitoring configuration is a JSON payload defining the connection details, credentials, and feature sets that you want to monitor. For details, see Start monitoring.

Example payload to activate a WMI extension:

[
  {
    "scope": "ag_group-ActiveGate-group-name",
    "value": {
      "version": "1.0.0",
      "description": "WMI Simple",
      "enabled": true,
      "activationContext": "REMOTE",
      "wmiRemote": {
        "devices": [
          {
            "host" : "192.168.0.1",
            "user" : "DOMAIN\\Administrator",
            "password" : "Password1"         
          }
        ]
      },
      "featureSets": ["basic"],
      "vars": {
        "deviceFilter": "DeviceID = 'C:' and FreeSpace > 0"
      }
    }
  }
]

When you have your initial extension YAML ready, package it, sign it, and upload it to your Dynatrace environment. For details, see Manage extension lifecyle.

Then you can use the Dynatrace API to download the schema for your extension that will help you create the JSON payload for your monitoring configuration.

Use the GET an extension schema endpoint.

Issue the following request:

curl -X GET "{env-id}.live.dynatrace.com/api/v2/extensions/{extension-name}/{extension-version}/schema" \
   -H "accept: application/json; charset=utf-8" \
   -H "Authorization: Api-Token {api-token}"

Make sure to replace {extension-name} and {extension-version} with values from your extension YAML file. A successful call returns the JSON schema.

Scope

Note that each OneAgent or ActiveGate host running your extension needs the root certificate to verify the authenticity of your extension. For more information, see Sign extension.

Remote extension

For a remote extension, the scope is an ActiveGate group that will execute the extension. Only one ActiveGate from the group will run this monitoring configuration. If you plan to use a single ActiveGate, assign it to a dedicated group. You can assign an ActiveGate to a group during installation with the --set-group-name installation parameter for Linux and Windows, or by configuring your ActiveGate.

Use the following format when defining the ActiveGate group:

"scope": "ag_group-<ActiveGate-group-name>",

Replace <ActiveGate-group-name> with the actual name.

Local extension

For a local extension, the scope is a host or a host group where you will execute the extension.

  • When defining a host as the scope, use this format:
    "scope": "<HOST_ID>",
    
    Replace <HOST_ID> with the entity ID of the host as in this example:
    "scope": "HOST-A1B2345678C9D001",
    
  • When defining a host group as the scope, use this format:
    "scope": "host_group-<HOST_GROUP_ID>",
    
    Replace <HOST_GROUP_ID> with the entity ID of the host group as in this example:
    "scope": "host_group-HOST_GROUP-AB123C4D567E890",
    
    You can find the host group ID in the host group settings page URL. For example:
    https://{your-environment-id}.live.dynatrace.com/#settings/hostgroupconfiguration;id=HOST_GROUP-AB123C4D567E890;hostGroupName=my-host-group
    

Version

Version of this monitoring configuration. Note that a single extension can run multiple monitoring configurations.

Description

Human-readable description of the specifics of this monitoring configuration.

Enabled

If set to true, the configuration is active and Dynatrace starts monitoring immediately.

Activation context

Set activationContext to REMOTE for remote extensions and to LOCAL for local extensions.

Devices

Remote extensions only.

You can define up to 100 devices in a single monitoring configuration in the wmiRemote section. To define a device, add the following details:

  • Host
  • Authentication credentials

Authentication

Remote extensions only.

Authentication details passed to Dynatrace API when activating monitoring configuration are obfuscated and it's impossible to retrieve them.

When authenticating your extension into a Windows host, the general Windows user management concepts apply. If an ActiveGate running the extension is in the same domain, you only need to provide a user name and password. You can also provide a domain, but remember to escape the backward slash (\).

For example:

"devices": [
  {
    "host" : "172.18.147.100",
    "user" : ".\\WMIUser",
    "password" : "SomePassword"
  },
  {
    "host" : "exchange.lab.dynatrace.org",
    "user" : "Exchange-Domain\\WMIUser",
    "password" : "SomePassword2"
  }
]

We recommend that you create a dedicated local user group or a user account on the target computer specifically for remote connections.

Feature sets

Add a list of feature sets you want to monitor. To report all feature sets, add all.

"featureSets": [
  "basic",
  "advanced"
  ]

Variables

If your extension declares variables, you can define values that will be passed as filters or plain strings to your extension. For more information, see Declare variable.

"vars": {
   "mailboxName": "win-4u1vg1uqvla",
   "deviceFilter": "DeviceID = 'C:'",
   "ipFilter" : "DNSDomain='home'"
   }