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

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

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

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

Создайте список идентификаторов объектов SNMP (OID), на которые вы хотите ссылаться в своем расширении (в качестве значений для ваших метрик и измерений).

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

name: custom:snmp-example version: 1.0.0 minastromkeyVersion: '1.235' author:   name: astromkey metrics:   - key: snmp.generic.snmp.in.pkts   - key: snmp.generic.silentdrops   - key: snmp.generic.if.lastchange   - key: snmp.generic.if.in.errors snmp:   - group: generic-device     interval:       minutes: 5     dimensions:       - key: snmp.generic.device.address         value: this:device.address       - key: snmp.generic.device.port         value: this:device.port     subgroups:       - subgroup: SNMP health         table: false         metrics:           - key: snmp.generic.snmp.in.pkts             value: oid:1.3.6.1.2.1.11.1.0             type: count           - key: snmp.generic.silentdrops             value: oid:1.3.6.1.2.1.11.31.0             type: count       - subgroup: NIC status         table: true         dimensions:           - key: snmp.generic.if.descr             value: oid:1.3.6.1.2.1.2.2.1.2           - key: snmp.generic.if.type             value: oid:1.3.6.1.2.1.2.2.1.3         metrics:           - key: snmp.generic.if.lastchange             value: oid:1.3.6.1.2.1.2.2.1.9             type: gauge           - key: snmp.generic.if.in.errors             value: oid:1.3.6.1.2.1.2.2.1.14             type: count dashboards:   - path: 'generic-device-dashboard.json'

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

Расширения SNMP используют OID, которые идентифицируют все объекты MIB, включая значения показателей и сведения об устройствах.

Размерность

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

Например:

dimensions:   - key: cisco-catalyst-health.temperature.desc     value: oid:1.3.6.1.4.1.9.9.13.1.3.1.2

Размерность ключа

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

Значение размерности

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

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

- key: snmp.com.dt.generic.extension.owner   value: const:Joe.Doe@somedomain.com

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

- key: snmp.com.dt.generic.activation.tag   value: var:ext.activationtag

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

- key: snmp.com.dt.generic.device.address   value: this:device.address - key: snmp.com.dt.generic.device.port   value: this:device.port

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

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

vars: - id: ifNameFilter    displayName: Pattern matching interfaces for which metrics should be queried    type: pattern - id: ext.activationtag    displayName: Extension activation tag    type: pattern

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

dimensions: - key: interface_description    value: oid:.1.3.6.1.2.1.2.2.1.2    filter: var:ifNameFilter - key: snmp.com.dt.generic.activation.tag    value: var:ext.activationtag

Фильтр извлеченных метрических строк

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

filter: var:ifNameFilter

Определите фильтр на основе условия следующим образом:

• Начинается с – используйте определитель const:$prefix. Пример:

filter: const:$prefix(xyz)

• Заканчивается на – используйте определитель const:$suffix. Пример:

filter: const:$suffix(xyz)

• Содержит – используйте квалификатор const:$contains. Пример:

filter: const:$contains(xyz)

• Равно – используйте квалификатор const:$eq. Пример:

filter: const:$eq(xyz)

Для выражений, упомянутых выше, вы также можете использовать определители:

• const:$and– для соединения двух или более выражений с помощью оператора AND. Пример:

filter: const:$and(<expr1>,<expr2>)

• const:$or– для соединения двух или более выражений с помощью оператора OR. Пример:

filter: const:$or(<expr1>,<expr2>)

• const:$not– для отрицания выражения. Пример:

filter: const:$not(<expr>)

Метрики

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

Например:

snmp:   - group: catalyst-health     featureSet: temperature     interval:       minutes: 5     dimensions:       - key: device_name         value: oid:1.3.6.1.2.1.1.5       - key: this.device.address         value: this:device.address     metrics:       - key: cisco-catalyst-health.temperature.value         value: oid:1.3.6.1.4.1.9.9.13.1.3.1.3         type: gauge         featureSet: basic         interval:           minutes: 5

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

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

Для схем Расширений 2.0 версии 1.215 метрический узел требует параметр id вместо key. Начиная с версии 1.217 схемы Расширений 2.0 требуется использовать параметр key.

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

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

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

OID, из которого вы хотите извлечь значение метрики.

Тип

Фреймворк Ключ-АСТРОМ Расширений 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

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

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

snmp:   - group: health     interval:       minutes: 5     dimensions:       - key: device_name         value: oid:1.3.6.1.2.1.1.5       - key: this.device.address         value: this:device.address     subgroups:     - subgroup: Traffic       featureSet: total traffic       metrics:         - key: outgoing_packets           value: oid:.1.3.6.1.2.1.11.1           type: count         - key: incoming_packets           value: oid:.1.3.6.1.2.1.11.1           type: count     - subgroup: TCP       featureSet: transport layer statistics       metrics:         - key: tcpActiveOpens           value: oid:1.3.6.1.2.1.6.5.0           type: count         - key: tcpPassiveOpens           value: oid:1.3.6.1.2.1.6.6.0           type: count     - subgroup: UDP       featureSet: transport layer statistics       metrics:         - key: udpNoPorts           value: oid:1.3.6.1.2.1.7.2.0           type: count         - key: udpInErrors           value: oid:1.3.6.1.2.1.7.3.0           type: count

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

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

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

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

Интервал

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

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

Например:

interval:      minutes: 5

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

interval: 5m

Например:

snmp:   - group: snmp-generic     interval:       minutes: 5     dimensions:       - key: device_name         value: oid:1.3.6.1.2.1.1.5     metrics:       - key: incoming_packets         value: oid:.1.3.6.1.2.1.11.1

MIB-файлы

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

АктивныйШлюз поставляется с набором MIB-файлов по умолчанию. Вы также можете расширить набор по умолчанию собственными файлами.

Разрешение OID

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

subgroups:   - subgroup: Device health (Temperature)       table: true       dimensions:       - key: envmon.temperature.desc           value: oid:ciscoEnvMonTemperatureStatusDescr       metrics:       - key: envmon.temperature.value           value: oid:ciscoEnvMonTemperatureStatusValue           name: The current testpoint temperature (deg Celsius)           type: gauge

Разрешение сетевого адреса

IP-адрес, возвращаемый из OID, может быть автоматически преобразован в строку в формате IPv4 или IPv6. Файл MIB определяет, какой формат использовать.

Например, OID 1.3.6.1.4.1.3375.2.2.10.1.2.1.3 (ltmVirtualServAddr), IP-адрес виртуального сервера, возвращается как двоичное (шестнадцатеричное) значение. С MIB он сообщается в формате IPv4 или IPv6, как определено информацией из ltmVitualServAddrType.

subgroups:   - subgroup: virtualServer       table: true       dimensions:       - key: ltmvirtualserveraddrvalue           value: oid:1.3.6.1.4.1.3375.2.2.10.1.2.1.3

Переводы данных с использованием$networkFormat

Функция $networkFormat позволяет извлекать данные из OID с помощью форматирующих OID. Доступные типы для извлечения: interfaceAlias, interfaceName, portComponent, networkAddress (ipv4, ipv6, mac, dns), local address, macAddress, и agentCircuitId.

В вашем файле extension.yaml используйте $networkFormat под любым значением измерения (например, network.translation), чтобы указать, как следует преобразовывать значения OID:

• Укажите два OID (один для форматирования и один для целевых данных).
  • *$networkFormat (oid:<formatter OID>, oid:<data OID>)
• Один OID с типом форматировщика: используйте один OID с определенным типом форматировщика.
  • $networkFormat (const:<formatter type>, oid:<OID>)
• Два OID или один OID и один форматировщик с полем по умолчанию: включите значение default на случай, если перевод не удастся.
  • $networkFormat (oid:<formatter OID>, oid:<data OID>, default:<default value>)

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

Чтобы избежать проблем с переводом, убедитесь, что необходимые файлы MIB доступны. Отсутствие файлов MIB приводит к непереведенным выводам.

Перевод перечисленных значений

Если OID является перечислимым типом, расширение сообщает значение OID как строку с именем, а не просто число.

Например, OID 1.3.6.1.2.1.2.2.1.7 (ifAdminStatus) — это перечислимый тип с возможными значениями (1-up, 2-down, 3-testing). С MIB расширение будет сообщать полную строку в качестве своего значения (например, 1-up вместо 1) для интерфейса с состоянием up.

Добавьте свой собственный MIB-файл

Если некоторые OID вашего расширения отсутствуют в файлах MIB по умолчанию, вы можете добавить в расширение свой собственный файл MIB.

Отправьте MIB-файл с вашим расширением

Создайте директорию snmp рядом с вашим extension.yaml и поместите туда файл MIB. Например:

extension.zip │   extension.yaml │ └───alerts │   |   alert.json │ └───dashboards |   │   dashboard.json | └───snmp │   |   IF-MIB.txt

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

"inetAddress translation: Unable to find inetAddress type. X, dimension: Y"`.

Расположение файлов MIB

Файлы MIB по умолчанию сохраняются в:

• Linux: /opt/dynatrace/remotepluginmodule/agent/res/mib-files
• Windows: C:\%PROGRAMFILES%\dynatrace\remotepluginmodule\agent\res\mib-files

Файл MIB, добавленный к расширению, сохраняется в:

• Linux: /var/lib/dynatrace/remotepluginmodule/agent/runtime/datasources/working_directories/[ID]/snmp
• Windows: C:\%PROGRAMDATA%\dynatrace\remotepluginmodule\agent\runtime\datasources\working_directories\[ID]\snmp

где [ID]— строка, содержащая идентификатор конфигурации мониторинга и временную метку.

Пользовательский каталог MIB АктивногоШлюза

В качестве альтернативы вы можете добавить свои собственные файлы MIB непосредственно в АктивномШлюзе. Затем эти файлы MIB используются всеми расширениями SNMP и SNMP Traps, работающими на этом АктивномШлюзе.

Поместите ваши пользовательские файлы MIB в директорию mib-files-custom:

• Linux: /var/lib/dynatrace/remotepluginmodule/agent/conf/userdata/mib-files-custom/
• Windows: C:\%PROGRAMDATA%\dynatrace\remotepluginmodule\agent\conf\userdata\mib-files-custom\

Файлы, хранящиеся в директории mib-files-custom, сохраняются между обновлениями.

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

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

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

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

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

[ {     "scope": "ag_group-my-activegate-group",     "value": {       "version": "1.0.0",       "description": "my monitoring configuration",       "enabled": true,       "snmp": {         "devices": [           {             "ip": "snmp.company.org",             "port": 161,             "authentication": {               "type": "SNMPv2c",               "community": "public"             },             "advanced": {               "timeoutSecs": 5,               "retries": 0,               "maxRepetitions": 50,               "maxOidsPerQuery": null,               "enableUnconnectedUdp": true             }           }         ]       },       "featureSets": [         "all"       ]     }   } ]

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

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

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

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

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

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

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

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

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

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

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

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

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

Версия

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

Описание

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

Включение

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

Устройства

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

• IP-адрес или имя устройства
• Порт
• Учетные данные аутентификации
  • Тип: SNMPv2c или SNMPv3 (обратите внимание, что SNMPv2c по смыслу используется в аутентификации сообщества)

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

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

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

• Уровень безопасности: authPriv

{ "ip": "10.10.10.10", "port": 161, "authentication": { "type": "SNMPv3", "userName": "snmptest_SHA_AES256", "securityLevel": "AUTH_PRIV", "authPassword": "916cb7fe3c80fc273413797bd063b8e320237e6159a47c06278ec818da58e3a4fb5f715bdb63313439f2d5e25a434386b3fe82dd0a643507d7452340b3c56d30=", "authProtocol": "SHA512", "privPassword": "EAB559FF7A04D73D77FE017271A3250B786FB2FD4DA0D45F60C9BE31311221262DB510A4AEC53A418297FC260DB6C91429880030BCAA8416FA1C2810C8E7B928=", "privProtocol": "AES256C" }

• Уровень безопасности: authNoPriv

{ "ip": "10.10.10.10", "port": 161, "authentication": { "type": "SNMPv3", "userName": "snmptest_SHA_AES256", "securityLevel": "AUTH_NO_PRIV", "authPassword": "916cb7fe3c80fc273413797bd063b8e320237e6159a47c06278ec818da58e3a4fb5f715bdb63313439f2d5e25a434386b3fe82dd0a643507d7452340b3c56d30=", "authProtocol": "SHA512" }

• Уровень безопасности: NoAuthNoPriv

{ "ip": "10.10.10.12", "port": 161, "authentication": { "type": "SNMPv3", "userName": "snmptest_SHA_AES256", "securityLevel": "NO_AUTH_NO_PRIV" }

Дополнительные свойства

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

• timeoutSecs - Максимальное время (в секундах) ожидания возврата данных по запросу SNMP. По умолчанию 1 секунда.
• retries - Максимальное количество повторных попыток для запроса в случае сбоя (общее время запроса равно timeoutSecsxretries). По умолчанию 3 повторных попытки.
• maxRepetitions - Может использоваться для ограничения объема данных, возвращаемых для одного запроса, и, в свою очередь, может увеличить количество запросов, отправляемых на устройство, пока не будут собраны все необходимые данные. По умолчанию 100 повторений.
• maxOidsPerQuery - Может использоваться для ограничения количества OID, которые можно запросить в одном запросе SNMP. По умолчанию 60.
• enableUnconnectedUdp - АктивныйШлюз версии 1.297+ При включении сокет UDP становится неподключенным. Это позволяет ему принимать ответы с другого адреса, нежели тот, на который был отправлен запрос, или игнорировать пакеты ICMP.

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

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

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

Переменные

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

"vars":   {   "ifNameFilter": "$contains(1/1/1)",   "ifSpeedFilter": "$eq(4294967295)"   }