Просмотр кода страницы Расширения YAML-файла

Ваш файл <code>extension.yaml</code> определяет общую область действия вашего расширения и является основным элементом вашего пакета расширения. Он хранит конфигурацию вашей среды и загружается в вашу среду как часть пакета расширения '''ZIP'''.

В этой теме описываются основные элементы файла <code>extension.yaml</code>, применимые к любому виду расширения из фреймворка Ключ-АСТРОМ '''Расширения 2.0'''. Для элементов, специфичных для определенных типов источников данных, см.:

* Расширение SNMP
* Расширение WMI
* Расширение Prometheus
* Расширение JMX
* Расширение SQL

== Схемы ==
При создании файла <code>extension.yaml</code> обязательно используйте схемы, предоставляемые через '''API Расширения 2.0'''. Мы рекомендуем использовать редактор, поддерживающий проверку схемы и сниппетов, что значительно упрощает редактирование <code>extension.yaml</code>.

Мы рекомендуем использовать дополнение Ключ-АСТРОМ Extensions VS Code, предоставленное Ключ-АСТРОМ. 

Чтобы загрузить схемы Расширения 2.0:

1. Проверьте доступные версии схем с помощью конечной точки '''GET all schemas'''. Версия схемы относится к версиям кластерам Ключ-АСТРОМ.
{| class="wikitable"
|curl -X GET "{env-id}.live.astromkey.com/api/v2/extensions/schemas" \

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

-H "Authorization: Api-Token {api-token}"
|}
Ответ :
{| class="wikitable"
|{

   "versions": [

     "1.213.0",

     "1.215.0",

   ]

}
|}
2. Используйте конечную точку '''GET all files''' для получения списка всех доступных схем для определенной версии Ключ-АСТРОМ. Например:
{| class="wikitable"
|curl -X GET "{env-id}.live.astromkey.com/api/v2/extensions/schemas/{astromkey-version}" \

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

-H "Authorization: Api-Token {api-token}"
|}
Ответ :
{| class="wikitable"
|{

  "files": [

    "metric.metadata.schema.json",

    "topology.schema.json",

    "generic.types.schema.json",

    "generic.relationships.schema.json",

    "snmp.schema.json",

    "metric.schema.json",

    "wmi.schema.json",

    "extension.schema.json"

  ]

}
|}
3. Используйте конечную точку '''GET a file''' для загрузки определенного файла в определенной версии. Например, чтобы загрузить <code>extension.schema.json</code>, версии <code>1.215</code>:
{| class="wikitable"
|curl -X GET "{env-id}.live.astromkey.com/api/v2/extensions/schemas/1.215/extension.schema.json" \

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

-H "Authorization: Api-Token {api-token}"
|}
В качестве альтернативы вы можете использовать репозиторий Ключ-АСТРОМ GitHub для [https://github.com/dynatrace-extensions/extensions-schemas схем расширений].

== Запуск файла расширения YAML ==
Файл расширения '''YAML''' начинается с базовой информации о расширении. Он также содержит необязательные ссылки на активы, используемые расширением.

* <code>name</code>— имя вашего расширения. Имя пользовательского расширения (расширение, не разработанное Ключ-АСТРОМ) должно начинаться с <code>custom:</code>. Строка должна соответствовать требованиям протокола приема метрик для измерений.
* <code>version</code>— версия вашего расширения в формате <code>major</code>, <code>minor</code>, <code>build</code>, например <code>1.0.0</code>. Ваша среда Ключ-АСТРОМ может хранить '''10''' версий расширения, но только одна может быть активна в данный момент.
* <code>minastromkeyVersion</code>— самая ранняя версия Ключ-АСТРОМ, поддерживаемая расширением, заключенным в кавычки (<code>"</code>), например <code>"1.213"</code>.
* <code>author</code>— разработчик расширения или компания.
* <code>dashboards</code>— путь к определениям панели мониторинга в архиве <code>extension.zip</code> относительно файла расширения '''YAML'''. Можно добавить до '''10''' определений.
* <code>alerts</code>—путь к определениям событий пользовательских метрик в архиве <code>extension.zip</code> относительно файла расширения '''YAML'''. Можно добавить до '''10''' определений.

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

Для каждого расширения можно определить '''10 групп''', а каждая группа может содержать '''10 подгрупп'''.

Например:
{| class="wikitable"
|name: com.astromkey.cisco-catalyst-health

version: 1.0.0

minastromkeyVersion: "1.238"

author:

  name: Joe Doe

snmp:

  - group: Device health

    interval:

      minutes: 1

    dimensions:

      - key: device.name

        value: oid:1.3.6.1.2.1.1.5.0

      - key: device.contact

        value: oid:1.3.6.1.2.1.1.4.0

    subgroups:

      - subgroup: Device health (Temperature)

        table: true

        dimensions:

          - key: envmon.temperature.desc

            value: oid:1.3.6.1.4.1.9.9.13.1.3.1.2

        metrics:

          - key: envmon.temperature.value

            value: oid:1.3.6.1.4.1.9.9.13.1.3.1.3

            type: gauge
|}

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

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

Например :
{| class="wikitable"
|interval:

     minutes: 5
|}
<u>Вышеуказанный формат поддерживается, начиная с версии схемы '''1.217'''. Для более ранних версий схемы используйте следующий формат (поддерживается до версии схемы 1.251):</u>
{| class="wikitable"
|interval: 5m
|}

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

* SNMP
* WMI

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

== Размеры ==
Вы можете определить измерение на уровне метрики, группы и подгруппы. Подробности того, как извлекать значения измерения, зависят от типа источника данных. Смотрите:

* SNMP
* WMI
* Prometheus

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

- id: ifNameFilter

   displayName: Pattern matching interfaces for which metrics should be queried

   type: text

- id: ext.activationtag

   displayName: Extension activation tag

   type: text
|}
В определении переменных можно использовать три типа переменных:

* <code>text</code>— позволяет указать простое текстовое значение.
** <code>displayName</code>— имя, видимое в Dynatrace Hub.
** <code>maxLength</code>—максимальная длина значения переменной (до 10 000).
** <code>required</code>— требуется ли указывать значение для этой переменной.
** <code>defaultValue</code>— значение по умолчанию, если в REST API значение не указано.
** <code>pattern</code>— шаблон регулярного выражения, которому должно соответствовать предоставленное значение.

{| class="wikitable"
|<nowiki>- id: textVariable</nowiki>

  type: text

  displayName: Variable

  description: "Detailed information about this variable"

  maxLength: 2000

  required: true

  defaultValue: "#ff1"

  pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
|}

* <code>multiline-text</code>— позволяет вам предоставить простой текст с символами новой строки. Подробности о многострочном синтаксисе '''YAML''' см. в разделе [https://yaml-multiline.info/ YAML Multiline].
** <code>maxLength</code>—максимальная длина значения переменной (до 10 000).
** <code>required</code>— требуется ли указывать значение для этой переменной.
** <code>defaultValue</code>— значение по умолчанию, если в REST API значение не указано.

{| class="wikitable"
|<nowiki>- id: multilineVariable</nowiki>

  type: multiline-text

  displayName: Variable

  description: Detailed information about this variable

  maxLength: 2000

  required: true

  defaultValue: |

    Pipe

    style

    multiline
|}

* <code>enum</code>— позволяет вам определить собственный набор возможных значений.
** необязательный <code>defaultValue</code>— если определено, устанавливает значение по умолчанию для всего набора и делает переменную обязательной.
* Определите возможные значения в списке <code>availableValues</code>:
** <code>value</code>— значение, переданное расширению.
** <code>displayName</code>— имя, видимое в Ключ-АСТРОМ Hub.

{| class="wikitable"
|<nowiki>- id: Colors</nowiki>

  type: enum

  defaultValue: green

  description: Choose your favorite color!

  availableValues:

    - value: red

      displayName: Red as a rose

    - value: green

      displayName: Green as grass

    - value: white

      displayName: White as snow
|}

== Фильтры ==
После определения фильтра как переменной можно добавить логику фильтрации, которая приведет к отображению только тех измерений, которые соответствуют критериям фильтрации.
{| class="wikitable"
|filter: var:ifNameFilter
|}
Определите фильтр на основе условия следующим образом:

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

{| class="wikitable"
|filter: const:$prefix(xyz)
|}

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

{| class="wikitable"
|filter: const:$suffix(xyz)
|}

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

{| class="wikitable"
|filter: const:$contains(xyz)
|}

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

{| class="wikitable"
|filter: const:$eq(xyz)
|}


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

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

{| class="wikitable"
|filter: const:$and(<expr1>,<expr2>)
|}

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

{| class="wikitable"
|filter: const:$or(<expr1>,<expr2>)
|}

* <code>const:$not</code>– для отрицания выражения. Пример:

{| class="wikitable"
|filter: const:$not(<expr>)
|}