Справка о источнике данных WMI

Материал из Документация Ключ-АСТРОМ

Это общее описание файла YAML расширения на основе источника данных WMI и способов объявления показателей и измерений, которые вы хотели бы собирать с помощью вашего расширения.

Вы также можете попробовать наш учебник по источнику данных WMI для пошагового руководства по созданию расширения WMI. Для получения дополнительной информации см. учебник по источнику данных WMI.

Область действия данных

Создайте список устройств, на которые вы хотите ссылаться в своем расширении, а также свойства WMI, которые вы будете использовать в качестве источника для значений метрик и измерений.

В нашем примере мы создаем простое расширение, собирающее данные о дисках и сети с устройств, отслеживаемых с помощью WMI.

name: custom:wmi-extension

version: 0.0.1

minastromkeyVersion: '1.236'

author:

  name: astromkey

vars:

  - id: deviceFilter

    displayName: Filter

    type: variable

wmi:

  - group: WMIClasses

    interval:

      minutes: 1

    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:

          minutes: 1

        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

Определение области мониторинга WMI начинается с узла YAML wmi. Все настройки в узле относятся к объявленному типу источника данных (в данном случае WMI).

WQL-запросы

Расширения WMI опираются на пространства имен WMI и их классы. Ваше расширение WMI извлекает значения измерений и метрик из свойств класса WMI с помощью запросов WQL.

Большинство классов и свойств, связанных с расширением, находятся в пространстве имен root\civm2. Чтобы узнать больше о пространствах имен и классах WMI, см. Windows Management Instrumentation в документации Microsoft.

В этом примере мы запрашиваем свойства, связанные с диском Win32_LogicalDisk, из класса (DeviceID , FreeSpace и Size) в пространстве имен root\cimv2 (определенном на уровне группы wmiNamespace) и фильтруем результаты по диску C с некоторым остатком FreeSpace. Фильтрация достигается с помощью переменной; см. конфигурацию мониторинга ниже. Затем запрашиваемые из WMI значения назначаются значениям измерений и метрик и загружаются в Ключ-АСТРОМ.

name: custom:wmi.wql.example

version: 0.0.1

minastromkeyVersion: "1.236"

author:

  name: astromkey

vars:

  - id: deviceFilter

    displayName: Filter

    type: variable

wmi:

  - group: WMIClasses

    featureSet: basic

    interval:

      minutes: 1

    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

Пример конфигурации мониторинга для вашего запроса WQL

В этом примере показано, как передать переменную deviceFilter, объявленную ранее в 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"

      }

    }

  }

]

Размеры

Для каждого уровня (расширение, группа, подгруппа) можно определить до 25 измерений.

Размерный ключ

Строка ключа измерения должна соответствовать протоколу приема метрик .

Значение размера

Помимо простого указания расширению извлечь значение измерения из свойства, вы также можете использовать следующие методы:

  • Извлеченное значение запроса WQL. Префикс с column:.
dimensions:

- key: disk.id

  value: column:DeviceID

Обратите внимание, что для использования свойства в качестве значения измерения необходимо сначала запросить DeviceID в связанной группе или подгруппе.

  • Обычный текст. Префикс const:.
dimensions:

- key: extension.owner

  value: const:Joe.Doe@somedomain.com

  • Переменная, определенная конфигурацией мониторинга. Префикс с var:.
dimensions:

- key: public_ip

  value: var:public_ip

- key: agent_version

  value: var:agent_version

  • Мониторинг конфигурации — определенные сведения об устройстве, такие как IP-адрес устройства или порт. Используйте this:device.host.
dimensions:

- key: hostname

  value: this:device.host

Используйте переменные с измерениями

Если вы хотите сделать свое измерение расширения настраиваемым с помощью данных из конфигурации мониторинга, вы можете использовать переменные, которые будут заменены значениями, переданными из конфигурации мониторинга. Чтобы использовать переменные, вы должны сначала объявить их в файле расширения YAML:

vars:

   - id: oneagent_version

     displayName: OneAgent version

     type: variable

Затем вы можете ссылаться на них в определении измерения. Добавьте префикс имени переменной var.

dimensions:

   - key: oneagent_version

     value: var:agent_version

Фильтровать извлеченные размеры

При извлечении значения измерения можно добавить логику фильтрации с помощью запросов WQL, которые приведут к отображению только тех измерений, которые соответствуют критериям фильтрации.

query: SELECT DeviceID, FreeSpace, Size FROM Win32_LogicalDisk WHERE var:deviceFilter

Определите фильтр как запрос в конфигурации мониторинга и передайте его расширению как переменную :

"vars": {

  "deviceFilter": "DeviceID = 'C:' and FreeSpace > 0"

}

Метрики

Для каждого уровня (расширение, группа, подгруппа) можно определить до 100 показателей.

Например:

wmi:

  - group: WMIClasses

    interval:

      minutes: 1

    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

Метрический ключ

Строка ключа метрики должна соответствовать протоколу приема метрик .

Для Ключ-АСТРОМ версий 1.215 и 1.217 метрический узел требует параметр id вместо key. Начиная с Ключ-АСТРОМ версии 1.219 рекомендуется использовать параметр key, так как id будет считаться устаревшим.

Лучшие практики для метрических ключей

Метрики, которые вы вставляете в Ключ-АСТРОМ с помощью вашего расширения, — это лишь некоторые из тысяч метрик, встроенных и пользовательских, обрабатываемых Ключ-АСТРОМ. Чтобы сделать ключи метрик уникальными и легко идентифицируемыми в Ключ-АСТРОМ, лучше всего добавлять к имени метрики префикс имени расширения. Это гарантирует уникальность ключа метрики, и вы можете легко назначить метрику определенному расширению в вашей среде.

Значение метрики

Свойство WMI, из которого вы хотите извлечь значение метрики.

Тип

Фреймворк Ключ-АСТРОМ Расширения 2.0 поддерживает метрические полезные данные в форматах gauge (gauge) или count value (count). Чтобы указать тип метрики, используйте атрибут type.

Метаданные метрики

Расширение может определять метаданные для каждой метрики, доступной в Ключ-АСТРОМ. Например, вы можете добавить отображаемое имя метрики и единицу измерения, которые можно использовать для фильтрации в Визуализации метрик.

name: custom:example-extension-name

version: 1.0.0

minastromkeyVersion: "1.236"

author:

  name: astromkey

metrics:

  - key: your.metric.name

    metadata:

        displayName: Display name of the metric visible in Metrics browser

        unit: Count

Набор функций

Наборы функций — это категории, в которые вы организуете данные, собранные расширением. В этом примере мы создаем расширение WMI, которое отслеживает ваши устройства и собирает метрики, связанные со статистикой транспортного протокола и дисками устройств. Это отражается в организации метрик в связанные наборы функций tcp и physicalDisks.

wmi:

  group: Network_TCP

  interval:

    minutes: 1

  featureSet: tcp

  subgroups:

    - subgroup: TCPv4

      query: SELECT  ConnectionsActive, ConnectionsEstablished FROM Win32_PerfFormattedData_Tcpip_TCPv4

      metrics:

      - key: com.astromkey.extension.host-observability.network.tcp.connections.active

        value: column:ConnectionsActive

      - key: com.astromkey.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.astromkey.extension.host-observability.disk.bytes.persec

        value: column:DiskBytesPersec

      - key: com.astromkey.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

При активации расширения с помощью конфигурации мониторинга вы можете ограничить мониторинг одним из наборов функций. Для корректной работы расширение должно собрать как минимум одну метрику после активации.

В высокосегментированных сетях наборы функций могут отражать сегменты вашей среды. Затем, когда вы создаете конфигурацию мониторинга, вы можете выбрать набор функций и соответствующую группу ActiveGate, которая может подключаться к этому конкретному сегменту.

Все показатели, которые не отнесены ни к одному набору характеристик, считаются показателями по умолчанию и всегда включаются в отчет.

Метрика наследует набор признаков подгруппы, которая в свою очередь наследует набор признаков группы. Кроме того, набор признаков, определенный на уровне метрики, переопределяет набор признаков, определенный на уровне подгруппы, который в свою очередь переопределяет набор признаков, определенный на уровне группы.

Интервал

Интервал, с которым будет производиться измерение данных. Вы можете определить интервалы на уровне группы, подгруппы или индивидуальной метрики. Вы можете определить интервалы с гранулярностью в одну минуту. Максимальный интервал составляет 2880 минут (2 дня, 48 часов).

Установка интервала невозможна для источников данных JMX.

Например:

interval:

     minutes: 5

Вышеуказанный формат поддерживается, начиная с версии схемы 1.217. Для более ранних версий схемы используйте следующий формат (поддерживается до версии схемы 1.251):

interval: 5m
wmi:

  - group: Host

    interval:

      minutes: 1

    query: SELECT Name, PercentProcessorTime FROM Win32_PerfFormattedData_PerfOS_Processor

    metrics:

    - key: com.astromkey.extension.host-observability.host.cpu.time.processor

      value: column:PercentProcessorTime

    dimensions:

    - key: host.cpu.id

      value: column:Name

Конфигурация мониторинга WMI

После определения области действия конфигурации вам необходимо определить сетевые устройства, с которых вы хотите собирать данные, а также указать АктивныеШлюзы, которые будут выполнять расширение и подключаться к вашим устройствам.

Убедитесь, что все АктивныеШлюзы из группы АктивногоШлюза, которую вы определите как область, могут подключаться к соответствующему источнику данных. Вы можете назначить АктивныйШлюз группе во время или после установки.

Конфигурация мониторинга — это полезная нагрузка JSON, определяющая детали соединения, учетные данные и наборы функций, которые вы хотите отслеживать.

Пример полезной нагрузки для активации расширения WMI:

[

  {

    "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"

      }

    }

  }

]

Когда у вас будет готово начальное расширение YAML, упакуйте его, подпишите и загрузите в среду Ключ-АСТРОМ. Подробности см. в разделе Управление жизненным циклом расширения.

Мастер активации расширения на базе Ключ-АСТРОМ содержит динамически обновляемую полезную нагрузку JSON с вашей конфигурацией мониторинга.

Затем вы можете использовать API Ключ-АСТРОМ для загрузки схемы для вашего расширения, которая поможет вам создать полезную нагрузку JSON для вашей конфигурации мониторинга.

Используйте конечную точку схемы расширения GET .

Отправьте следующий запрос:

curl -X GET "{env-id}.live.astromkey.com/api/v2/extensions/{extension-name}/{extension-version}/schema" \

   -H "accept: application/json; charset=utf-8" \

   -H "Authorization: Api-Token {api-token}"

Обязательно замените {extension-name} и {extension-version} значениями из вашего файла расширения YAML. Успешный вызов возвращает схему JSON.

Применение

Обратите внимание, что каждый хост ЕдиногоАгента или АктивногоШлюза, на котором запущено ваше расширение, нуждается в корневом сертификате для проверки подлинности вашего расширения.

Удаленное расширение

Для удаленного расширения областью действия является группа АктивногоШлюза, которая будет выполнять расширение. Только один АктивныйШлюз из группы будет запускать эту конфигурацию мониторинга. Если вы планируете использовать один АктивныйШлюз, назначьте его выделенной группе. Вы можете назначить АктивныйШлюз группе во время или после установки.

При определении группы АктивногоШлюза используйте следующий формат:

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

Замените <ActiveGate-group-name> фактическим именем.

Локальное расширение

Для локального расширения областью действия является хост, группа хостов, зона управления или среда, для которой вы будете выполнять расширение.

  • При определении хоста в качестве области действия используйте следующий формат: "scope": "<HOST_ID>",
    Замените <HOST_ID> идентификатором сущности хоста, как в этом примере: "scope": "HOST-A1B2345678C9D001",
  • При определении группы хостов в качестве области действия используйте следующий формат: "scope": "HOST_GROUP-<HOST_GROUP_ID>",
    Замените <HOST_GROUP_ID> идентификатором сущности группы хостов, как в этом примере: "scope": "HOST_GROUP-AB123C4D567E890", Идентификатор группы хостов можно найти в URL-адресе страницы настроек группы хостов . Например: https://{your-environment-id}.live.astromkey.com/#settings/hostgroupconfiguration;id=HOST_GROUP-AB123C4D567E890;hostGroupName=my-host-group
  • При определении менеджмет-зоны в качестве области действия используйте следующий формат: "scope": "management_zone-<MANAGEMENT-ZONE>",
    Замените <MANAGEMENT-ZONE> на имя менеджмет-зоны, как в этом примере: "scope": "management_zone-sampleManagementZone",
  • При определении среды в качестве области действия используйте следующий формат: "scope": "environment",
    Вы также можете добавить теги для фильтрации хостов, на которых будет работать эта конфигурация:
    "activationTags": [
      "dt.owner:lama"
    ]

Версия

Версия этой конфигурации мониторинга. Обратите внимание, что одно расширение может запускать несколько конфигураций мониторинга.

Описание

Понятное для человека описание особенностей данной конфигурации мониторинга.

Включение

Если установлено значение true, конфигурация активируется, и Ключ-АСТРОМ немедленно начинает мониторинг.

Контекст активации

Установите activationContext на значение REMOTE для удаленных расширений и на значение LOCAL для локальных расширений.

Устройства

Только удаленные расширения.

Вы можете определить до 100 устройств в одной конфигурации мониторинга в разделе wmiRemote. Чтобы определить устройство, добавьте следующие данные:

  • Хост
  • Учетные данные аутентификации

Аутентификация

Только удаленные расширения.

Данные аутентификации, передаваемые в API Ключ-АСТРОМ при активации конфигурации мониторинга, запутаны, и их невозможно получить.

При аутентификации вашего расширения на хосте Windows применяются общие концепции управления пользователями Windows. Если АктивныйШлюз, на котором запущено расширение, находится в том же домене, вам нужно указать только имя пользователя и пароль. Вы также можете указать домен, но не забудьте экранировать обратную косую черту (\).

Например:

"devices": [

  {

    "host" : "172.18.147.100",

    "user" : ".\\WMIUser",

    "password" : "SomePassword"

  },

  {

    "host" : "exchange.lab.astromkey.org",

    "user" : "Exchange-Domain\\WMIUser",

    "password" : "SomePassword2"

  }

]

Мы рекомендуем вам создать специальную локальную группу пользователей или учетную запись пользователя на целевом компьютере специально для удаленных подключений.

Наборы функций

Добавьте список наборов функций, которые вы хотите отслеживать. Чтобы сообщить обо всех наборах функций, добавьте all.

"featureSets": [

  "basic",

  "advanced"

  ]

Переменные

Если ваше расширение объявляет переменные, вы можете определить значения, которые будут переданы в качестве фильтров или простых строк в ваше расширение.

"vars": {

   "mailboxName": "win-4u1vg1uqvla",

   "deviceFilter": "DeviceID = 'C:'",

   "ipFilter" : "DNSDomain='home'"

   }

Источник — https://doc.fit4u.kz/index.php?title=Справка_о_источнике_данных_WMI&oldid=5373