Пособие по источнику данных WMI

Пособие по источнику данных WMI

Это пошаговое руководство по созданию расширения на основе источника данных WMI. Вы создадите расширение WMI, которое работает на ЕдиномАгенте и отслеживает хост Windows.

Предустановка

Чтобы успешно разработать расширение 2.0 и выполнить это руководство, вам необходимо выполнить следующие предварительные условия:

• Доступ администратора к среде Ключ-АСТРОМ SaaS или Managed версии 1.227+
• Хост Windows (виртуальная машина)
• ЕдиныйАгент версии 1.227+ развернут на хосте
• Ключ-АСТРОМ CLI
  • Python 3.10
  • Доступ к установщику пакетов pip для Python
  • Установить dt-cli (pip install dt-cli)
• Ваш корневой сертификат загружен в Ключ-АСТРОМ и на хост ЕдиногоАгента

Сгенерируйте сертификат разработчика и ключ

dt extension genca dt extension generate-developer-pem -o developer.pem --ca-crt ca.pem --ca-key ca.key --name 'JDoe'

Команда генерирует следующие файлы:

• developer.pem- ваш сертификат разработчика
• ca.pem- ваш корневой сертификат
• ca.key- ваш корневой ключ

Распространение корневого сертификата на компоненты Ключ-АСТРОМ

Загрузить в хранилище учетных данных Ключ-АСТРОМ

1. Перейдите в хранилище учетных данных .
2. Выберите Добавить новые учетные данные.
3. В качестве типа учетных данных выберите Открытый сертификат.
4. Выберите область действия учетных данных проверки расширения.
5. Добавьте имя учетных данных.
6. Загрузите файл корневого сертификата.
7. Выберите Сохранить.

Загрузите на хост ЕдиныйАгент, на котором запущено расширение.

1. Перейдите в следующую директорию:
   • Windows : C:\ProgramData\astromkey\oneagent\agent\config
   • Linux : /var/lib/astromkey/oneagent/agent/config/
2. Перейдите в certificates папку (создайте ее, если ее нет)
3. Загрузите ваш корневой сертификат (ca.pem), сгенерированный ранее

Ваша среда Ключ-АСТРОМ готова к созданию расширения WMI.

Следующий шаг : Пакет расширения

WMI - пакет расширения

Расширения 2.0 основаны на файле конфигурации YAML. Его минимальное содержимое:

• namecustom:- Для пользовательских расширений необходимо начинать с
• version
• author
• minastromkeyVersion- Минимальная версия Ключ-АСТРОМ для обеспечения минимальной версии схемы расширения

Создать YAML-файл

Используйте следующий шаблон.

name: custom:demo.host-observability version: # add version minastromkeyVersion: "1.227" author:   name: # add your name

Сохраните свой ключ и сертификаты extension.yaml, а также ключ разработчика, используя следующую структуру:

my-sample-extension/   └── src/       ├── extension.yaml       dashboards/       └── dashboard.json       alerts/       └── alert.json

Создайте и подпишите свой пакет расширения

В директории extensions выполните следующую команду:

dt extension assemble dt extension sign --key ./developer.pem

Эти команды создают ваш пакет расширения, содержащий только архив extension.zip и файл подписи extension.zip.sig.

bundle.zip |    extension.zip |    extension.zip.sig

Загрузите свое расширение в Ключ-АСТРОМ

Чтобы загрузить и активировать расширение, выполните следующую команду:

dt extension upload bundle.zip

Пример успешного вывода:

C:\extension>dt extension upload bundle.zip Tenant url: your-tenant-url Api token: your-api-token Extension upload successful!

Результаты

Ваше расширение отображается в Ключ-АСТРОМ как активное.

Следующий шаг : источник данных WMI

WMI - источник данных

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

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

Для нашего расширения мы используем 3 запроса WMI. Мы добавим их в наш extension.yaml и воспользуемся их результатом как метриками Ключ-АСТРОМ:

• Извлечение данных об использовании ЦП, использовании ЦП пользователем и простое ЦП для каждого из процессоров хоста (с разделением по идентификатору ЦП).
  SELECT Name, PercentProcessorTime, PercentIdleTime, PercentUserTime FROM Win32_PerfFormattedData_PerfOS_Processor WHERE Name LIKE '_Total'
• Извлеките общее количество отправленных и полученных байт в секунду для каждого сетевого адаптера, работающего на хосте.
  SELECT Name, BytesTotalPersec, BytesReceivedPersec, BytesSentPersec FROM Win32_PerfFormattedData_Tcpip_NetworkAdapter
• Извлечь общее количество отправленных и полученных байтов в секунду для каждого сетевого интерфейса, работающего на хосте.
  SELECT Name, BytesTotalPersec, BytesReceivedPersec, BytesSentPersec FROM Win32_PerfFormattedData_Tcpip_NetworkInterface

Советы

Лучшие практики использования метрик

Добавьте к вашим метрическим ключам префикс с именем расширения, чтобы избежать конфликтов с другими метриками в Ключ-АСТРОМ. Для этого упражнения мы добавляем к каждому метрическому ключу префикс custom.demo.host-observability.

Измерение хоста

Вы можете определить хост, на котором запущено расширение, с помощью this:device.host переданного в качестве значения измерения.

Статические размеры

Вы можете добавлять измерения, которые являются фиксированными строками, используя префикс const:.

Определите свой источник данных

Добавьте раздел wmi, используя шаблон extension.yaml ниже.

1. Создайте две группы с именами Host и Network которые запускаются каждую 1 мин. Обе группы должны иметь измерение, которое идентифицирует хост, на котором запущено расширение.
2. Создайте подгруппу для каждого запроса WMI, указанного выше, и сопоставьте полученные столбцы с метриками и измерениями.
3. Добавьте измерение с именем network.type, которое принимает значение Adapter или Interface, в зависимости от запроса WMI.
4. Упакуйте новую версию вашего расширения и загрузите ее.
5. Настройте его для мониторинга вашего хоста Windows. Вы можете сделать это во время активации расширения в Ключ-АСТРОМ.
6. Подождите минуту, а затем проверьте сбор показателей.

Дополнительную информацию о синтаксисе источника данных WMI см. в Справочнике по источнику данных WMI.

wmi:   - group: Host     interval:       minutes: 1     dimensions:       - key: host         value: this:device.host     subgroups:       - subgroup: CPU         query: SELECT Name, PercentProcessorTime, PercentIdleTime, PercentUserTime FROM Win32_PerfFormattedData_PerfOS_Processor WHERE Name LIKE '_Total'         metrics:           - key: custom.demo.host-observability.host.cpu.time.processor             value: column:PercentProcessorTime           - key: custom.demo.host-observability.host.cpu.time.idle             value: column:PercentIdleTime           - key: custom.demo.host-observability.host.cpu.time.user             value: column:PercentUserTime         dimensions:           - key: host.cpu.id             value: column:Name   - group: Network     interval:       minutes: 1     dimensions:       - key: host         value: this:device.host     subgroups:       - subgroup: Adapters         query: SELECT Name, BytesTotalPersec, BytesReceivedPersec, BytesSentPersec FROM Win32_PerfFormattedData_Tcpip_NetworkAdapter         metrics:           - key: custom.demo.host-observability.network.bytes.persec             value: column:BytesTotalPersec           - key: custom.demo.host-observability.network.bytes.received.persec             value: column:BytesReceivedPersec           - key: custom.demo.host-observability.network.bytes.sent.persec             value: column:BytesSentPersec         dimensions:           - key: network.type             value: const:Adapter           - key: network.name             value: column:Name       - subgroup: Interfaces         query: SELECT Name, BytesTotalPersec, BytesReceivedPersec, BytesSentPersec FROM Win32_PerfFormattedData_Tcpip_NetworkInterface         metrics:           - key: custom.demo.host-observability.network.bytes.persec             value: column:BytesTotalPersec           - key: custom.demo.host-observability.network.bytes.received.persec             value: column:BytesReceivedPersec           - key: custom.demo.host-observability.network.bytes.sent.persec             value: column:BytesSentPersec         dimensions:           - key: network.type             value: const:Interface           - key: network.name             value: column:Name

Результаты

Ваши шесть метрик должны отображаться в Видуализации метрик. Чтобы найти их, отфильтруйте по тексту custom.demo.

WMI - метрические метаданные

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

Раздел расширения metrics предназначен для определения дополнительных метаданных для метрик. Мы можем определить следующее:

• displayName- Понятное для человека название метрики
• description- Описание того, что на самом деле представляет собой эта метрика
• unit- Единица измерения метрики
• tags- Как мы можем найти эту метрику в директории Метрик
• metricProperties
  • minValue- Минимально возможное значение метрики
  • maxValue- Максимально возможное значение метрики
  • impactRelevant- Зависит ли эта метрика от аномалий других метрик, чтобы сформировать первопричину проблемы
  • rootCauseRelevant- Может ли этот показатель сам по себе быть первопричиной проблемы
  • valueType- Являются ли высокие значения хорошими (score) или плохими (error)

Определить метаданные

1. Добавьте раздел metrics, используя шаблон extension.yaml ниже.
2. Определите метаданные для каждой собранной метрики.
3. Как минимум, определите displayName, description, и unit
4. Упакуйте и загрузите новую версию вашего расширения
5. Проверьте метаданные.

metrics:   - key: custom.demo.host-observability.network.bytes.persec     metadata:       displayName: Traffic bytes/s       description: Network traffic bytes per second       unit: BytePerSecond   #   # add content here, for all other metrics   #

Дополнительную информацию о синтаксисе источника данных WMI см. в Справочнике по источнику данных WMI.

Результаты

Теперь вы должны увидеть метаданные, отраженные в браузере метрик:

Следующий шаг : Пользовательская топология

WMI — пользовательская топология

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

Для расширения 2.0 все это происходит в topology разделе, который разделен на две части:

• types- определяет, какие новые типы сущностей отслеживает расширение
• relationships- определяет, связаны ли эти типы сущностей друг с другом и как это сделать

Ключевые аспекты при определении типов

• idPattern- Должен быть достаточно уникальным, чтобы представлять каждый экземпляр устройства, не дублируя его.
• sources- Необходимо определить правила для всех метрик расширения, которые должны быть разделены этой сущностью.
• condition- Можно использовать такие функции, как определение шаблонов для метрических ключей $prefix(...).
• attributes- Являются ли необязательными сведения, которые можно извлечь из измерений метрик

Ключевые аспекты при определении отношений

• sources- Любая метрика, которая соответствует шаблону, будет оценена для связи. Это означает, что она должна принадлежать к обоим типам сущностей, входящим в связь

Найдите новые сущности в пользовательском интерфейсе

Перейдите в среду Ключ-АСТРОМ ../ui/entity/list/{entity-type}. Например:

• ../ui/entity/list/wmi:generic_host
• ../ui/entity/list/wmi:generic_network_device

Задачи

1. Добавьте раздел topology, используя шаблон extension.yaml ниже.
2. Определите два типа сущностей: универсальный хост и универсальное сетевое устройство.
3. Убедитесь, что сетевые устройства знают тип (Adapterили Interface).
4. Создайте связь между ними, где универсальное сетевое устройство работает на универсальном хосте.
5. Упакуйте и загрузите новую версию вашего расширения.
6. Проверьте, созданы ли новые сущности.

topology:   types:     - name: wmi:generic_host       displayName: Generic Host       enabled: true       rules:         - idPattern: wmi_generic_host_{dt.entity.host}           sources:             - sourceType: Metrics               condition: $prefix(custom.demo.host-observability)           attributes: []           requiredDimensions: []           instanceNamePattern: Generic Host on {dt.entity.host}     - name: wmi:generic_network_device       displayName: Network device       enabled: true       rules:         - idPattern: wmi_generic_{dt.entity.host}_{network.type}_{network.name}           sources:             - sourceType: Metrics               condition: $prefix(custom.demo.host-observability.network)           attributes:             - pattern: '{network.name}'               key: wmi_network_name               displayName: Name             - pattern: '{network.type}'               key: wmi_network_type               displayName: Type           requiredDimensions: []           instanceNamePattern: Network {network.type} {network.name} on {dt.entity.host}   relationships:     - typeOfRelation: RUNS_ON       fromType: wmi:generic_network_device       toType: wmi:generic_host       enabled: true       sources:         - sourceType: Metrics           condition: $prefix(custom.demo.host-observability)

Результаты

Вы должны увидеть новые сущности, созданные для типов сущностей вашего универсального хоста и универсального сетевого устройства:

WMI - унифицированный анализ

Унифицированные страницы анализа — это окна для анализа производительности и устранения неполадок для этой новой контролируемой технологии.

Они предлагают возможность исключить дальнейшую панель мониторинга или построение диаграмм ad hoc. Раздел screens определит детали, которые будут отображаться на странице каждой сущности, а также диаграммы и списки других связанных сущностей для быстрой детализации.

Подробная страница унифицированного анализа

Страница сведений staticContent организована в виде динамического контента layout, включающего в себя cards (диаграммы и списки).

staticContent

• showProblems- Показать панель для любых проблем, связанных с этой сущностью
• showProperties- Показать раздел Свойства и теги
• showTags- Показать теги, примененные к этой сущности
• showGlobalFilter- Показать глобальную панель фильтрации
• showAddTag- Показать кнопку Добавить тег

Состоит из различных карт layout, определенных в chartsCards и entitiesListCards подразделах.

Карточка диаграмм

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

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

Пример простой карты-схемы:

chartsCards:   - key: "host-cpu-metrics"     displayName: "Host CPU"     numberOfVisibleCharts: 2     charts:       - displayName: "Idle CPU"         metrics:           - metricSelector: "custom.demo.host-observability.host.cpu.time.idle:SplitBy()"       - displayName: "User CPU"         metrics:           - metricSelector: "custom.demo.host-observability.host.cpu.time.user:SplitBy()"

Список сущностей

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

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

Пример простого списка сущностей:

entitiesListCards:   - key: "nic-list"     displayName: "Network Interfaces"     entitySelectorTemplate: "type(wmi:generic_network_device),fromRelationships.runsOn($(entityConditions)),wmi_network_type(Interface)"     displayCharts: false     displayIcons: true     enableDetailsExpandability: true

$(entityConditions)— это функция, которая автоматически сопоставляется с текущей просматриваемой сущностью. Это обязательно для селекторов сущностей, используемых в расширении.

Карточка свойств

Сущности propertiesCard также можно изменять, чтобы включить дополнительные свойства или скрыть ненужные. Свойства извлекаются из атрибутов сущности (когда тип — ATTRIBUTE) или через селектор сущности (когда тип — RELATION).

Определите унифицированные страницы для вашего расширения

1. Добавьте раздел screens, eиспользуя шаблон xtension.yaml ниже.
2. Настройте параметры страницы сведений для типов сущностей Универсальный хост и Универсальное сетевое устройство.
3. Используйте карты диаграмм для отображения всех показателей каждой сущности.
4. Добавьте карточки списка сущностей, чтобы универсальный хост мог перечислить все работающие на нем сетевые адаптеры и интерфейсы.
5. Добавьте свойство на основе отношения, чтобы универсальное сетевое устройство отображало, на каком универсальном хосте оно работает.
6. Упакуйте и загрузите новую версию вашего расширения.
7. Убедитесь, что ваши экраны отображаются так, как и ожидалось.

screens:   - entityType: wmi:generic_host     detailsSettings:       staticContent:         showProblems: true         showProperties: true         showTags: true         showGlobalFilter: true         showAddTag: true       layout:         autoGenerate: false         cards:           - type: "CHART_GROUP"             key: "wmi_host-chart-metrics"           - type: "ENTITIES_LIST"             key: "wmi_host-list-network_interfaces"           - type: "ENTITIES_LIST"             key: "wmi_host-list-network_adapters"     chartsCards:       - key: "wmi_host-chart-metrics"         displayName: "Generic Host Metrics"         numberOfVisibleCharts: 2         charts:           - displayName: "CPU Usage Breakdown"             visualization:               themeColor: BLUE               seriesType: AREA             metrics:               - metricSelector: "custom.demo.host-observability.host.cpu.time.idle:SplitBy()"               - metricSelector: "custom.demo.host-observability.host.cpu.time.user:SplitBy()"               - metricSelector: "custom.demo.host-observability.host.cpu.time.processor:SplitBy()"           - displayName: "CPU User"             visualization:               themeColor: BLUE               seriesType: LINE             metrics:               - metricSelector: "custom.demo.host-observability.host.cpu.time.user:SplitBy()"           - displayName: "CPU Idle"             visualization:               themeColor: BLUE               seriesType: LINE             metrics:               - metricSelector: "custom.demo.host-observability.host.cpu.time.idle:SplitBy()"           - displayName: "CPU Used"             visualization:               themeColor: BLUE               seriesType: LINE             metrics:               - metricSelector: "custom.demo.host-observability.host.cpu.time.processor:SplitBy()"     entitiesListCards:       - key: "wmi_host-list-network_interfaces"         displayName: "Network Interfaces"         entitySelectorTemplate: "type(wmi:generic_network_device),fromRelationships.runsOn($(entityConditions)),wmi_network_type(Interface)"         pageSize: 5         displayCharts: false         displayIcons: true         enableDetailsExpandability: true         numberOfVisibleCharts: 1         charts:           - displayName: "Traffic"             visualization:               themeColor: BLUE               seriesType: AREA             metrics:               - metricSelector: "custom.demo.host-observability.network.bytes.sent.persec:SplitBy()"               - metricSelector: "custom.demo.host-observability.network.bytes.received.persec:SplitBy()"       - key: "wmi_host-list-network_adapters"         displayName: "Network Adapters"         entitySelectorTemplate: "type(wmi:generic_network_device),fromRelationships.runsOn($(entityConditions)),wmi_network_type(Adapter)"         pageSize: 5         displayCharts: false         displayIcons: true         enableDetailsExpandability: true         numberOfVisibleCharts: 1         charts:           - displayName: "Traffic"             visualization:               themeColor: BLUE               seriesType: AREA             metrics:               - metricSelector: "custom.demo.host-observability.network.bytes.sent.persec:SplitBy()"               - metricSelector: "custom.demo.host-observability.network.bytes.received.persec:SplitBy()"   - entityType: wmi:generic_network_device     propertiesCard:       properties:         - type: ATTRIBUTE           attribute:             key: wmi_network_name             displayName: Name         - type: ATTRIBUTE           attribute:             key: wmi_network_type             displayName: Type         - type: RELATION           relation:             entitySelectorTemplate: type(wmi:generic_host),toRelationships.runsOn($(entityConditions))             displayName: Host     detailsSettings:       staticContent:         showProblems: true         showProperties: true         showTags: true         showGlobalFilter: true         showAddTag: true       layout:         autoGenerate: false         cards:         - type: "CHART_GROUP"           key: "wmi_network_device-chart-traffic"     chartsCards:       - key: "wmi_network_device-chart-traffic"         displayName: "Traffic"         numberOfVisibleCharts: 2         charts:           - displayName: "Traffic breakdown"             visualization:               themeColor: BLUE               seriesType: AREA             metrics:               - metricSelector: "custom.demo.host-observability.network.bytes.persec:SplitBy()"               - metricSelector: "custom.demo.host-observability.network.bytes.sent.persec:SplitBy()"               - metricSelector: "custom.demo.host-observability.network.bytes.received.persec:SplitBy()"           - displayName: "Bytes sent"             visualization:               themeColor: BLUE               seriesType: LINE             metrics:               - metricSelector: "custom.demo.host-observability.network.bytes.sent.persec:SplitBy()"           - displayName: "Bytes received"             visualization:               themeColor: BLUE               seriesType: LINE             metrics:               - metricSelector: "custom.demo.host-observability.network.bytes.sent.persec:SplitBy()"           - displayName: "Bytes"             visualization:               themeColor: BLUE               seriesType: LINE             metrics:               - metricSelector: "custom.demo.host-observability.network.bytes.sent.persec:SplitBy()"

Результаты

Ваши настроенные страницы унифицированного анализа отображаются и заполняются так, как и ожидалось.