IKuznetsov: Новая страница: «Это общее описание файла расширения '''YAML''' на основе источника данных '''SQL''' и способов об...»

2025-06-24T21:49:52Z

Новая страница: «Это общее описание файла расширения '''YAML''' на основе источника данных '''SQL''' и способов об...»

Новая страница

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

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

При разработке пользовательских расширений '''SQL''' мы рекомендуем следующее:

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

=== Контроль безопасности ===

* Доступны только запросы <code>SELECT</code>
** Запросы '''MySQL''' также могут начинаться с <code>SHOW GLOBAL STATUS</code>
* Одновременно может быть выполнен только один запрос.
* Запросы, содержащие комментарии, отклоняются.
* Для предотвращения нарушений целостности данных (манипулирования, изменения или удаления данных) источник данных '''SQL''' выполняет запросы в откатных транзакциях. По этой причине базы данных, не поддерживающие транзакции, не поддерживаются в качестве источника данных '''SQL'''.
* Убедитесь, что строка подключения, используемая в конфигурации мониторинга '''JDBC''', не раскрывает никаких конфиденциальных данных.

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

В нашем примере мы создаем простое расширение, собирающее основные данные о производительности '''ЦП''' из базы данных '''Oracle'''.
{| class="wikitable"
|name: com.astromkey.extension.sql-oracle

version: 1.0

minastromkeyVersion: '1.239'

author:

name: astromkey

sqlOracle:

- group: Number of CPU cores

featureSet: cpu

query: >

SELECT value AS cpu_count

FROM v$parameter

WHERE name = 'cpu_count'

metrics:

- key: com.astromkey.extension.sql-oracle.cpu.cores

value: col:cpu_count

type: gauge

- group: Background CPU Usage Per CPU Per Sec

featureSet: cpu

query: >

SELECT

DECODE(metric_name, 'Background CPU Usage Per Sec',

v$metric.value) AS background_cpu_usage,

DECODE(metric_name, 'CPU Usage Per Sec',

v$metric.value) AS foreground_cpu_usage,

DECODE(metric_name, 'Host CPU Usage Per Sec',

v$metric.value) AS host_cpu_usage

FROM v$metric,

v$metricgroup

WHERE v$metric.group_id = v$metricgroup.group_id

AND v$metric.metric_name IN ('Background CPU Usage Per Sec',

'CPU Usage Per Sec', 'Host CPU Usage Per Sec')

metrics:

- key: com.astromkey.extension.sql-oracle.cpu.backgroundTotal

value: col:background_cpu_usage

type: gauge

- key: com.astromkey.extension.sql-oracle.cpu.foregroundTotal

value: col:foreground_cpu_usage

type: gauge

- key: com.astromkey.extension.sql-oracle.cpu.hostTotal

value: col:host_cpu_usage

type: gauge
|}
В зависимости от поставщика определение области мониторинга '''SQL''' начинается с выделенного узла '''YAML'''. Для '''Oracle Database''' это <code>sqloracle</code>. Все настройки под узлом относятся к объявленному типу источника данных (в данном случае '''SQL''').

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

=== Объявите соединение JDBC в файле расширения YAML ===

# Начните определение расширения с узла <code>jdbc</code>.
# Объявите имя класса драйвера. Например <code>org.mariadb.jdbc.Driver</code>.
# Укажите шаблон для строки подключения и сообщения проверки. Они будут использоваться для проверки строки подключения, предоставленной пользователем в конфигурации мониторинга.
# Укажите самый простой запрос, который расширение выполнит для проверки подключения.

{| class="wikitable"
|jdbc:

driverClassName: “org.mariadb.jdbc.Driver”

connectionStringPattern: “jdbc:mariadb:(. |\\s)+$"

connectionStringPatternErrorMessage: “This isn't a correct connection string, please start with jdbc:mariadb."

validationQuery: “SELECT 1”
|}
Пользователям, запускающим ваше расширение, также необходимо загрузить соответствующий драйвер '''JDBC''' на АктивныйШлюз, принадлежащий группе, назначенной для запуска вашего расширения.

== SQL-запросы ==
Расширения '''SQL''' полагаются на запросы '''SQL'''. Запросы, объявленные в вашем расширении, извлекают значения для ваших метрик и измерений.

Например, следующий '''SQL'''-запрос возвращает количество ядер '''ЦП'''.
{| class="wikitable"
|SELECT value AS cpu_count

FROM v$parameter

WHERE name = 'cpu_count'
|}
Вы можете использовать его в своем расширении и сообщать значение, возвращаемое запросом <code>com.astromkey.extension.sql-oracle.cpu.cores</code>, в качестве метрики в Ключ-АСТРОМ.
{| class="wikitable"
|sqlOracle:
- group: Number of CPU cores

featureSet: cpu

query:

SELECT value AS cpu_count

FROM v$parameter

WHERE name = 'cpu_count'

metrics:

- key: com.astromkey.extension.sql-oracle.cpu.cores

value: col:cpu_count

type: gauge
|}
По соображениям безопасности источник данных поддерживает только подмножество языка '''SQL'''. Подробнее см. в разделе '''Управление безопасностью''' (ниже).

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

Вы можете использовать одно из двух исключительных свойств для управления тем, когда запрашивается поставщик базы данных, <code>interval</code> или <code>schedule</code>. Вы можете определить его на уровне группы или подгруппы.

=== Интервал ===
'''АктивныйШлюз версии 1.253+'''

Значение интервала принимает целочисленное значение, выражающее минуты. Например, чтобы запрашивать поставщика базы данных каждые '''10 минут''', добавьте следующую запись:
{| class="wikitable"
|sqlOracle:

- group: Number of CPU cores

featureSet: cpu

interval:

minutes: 10

query:

SELECT value AS cpu_count

FROM v$parameter

WHERE name = 'cpu_count'

metrics:

- key: com.astromkey.extension.sql-oracle.cpu.cores

value: col:cpu_count

type: gauge
|}

=== Расписание ===
'''АктивныйШлюз версии 1.301+'''

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

Выражение должно соответствовать формату '''cron Unix''':
{| class="wikitable"
|# * * * * *

<nowiki>#</nowiki> | | | | |

<nowiki>#</nowiki> | | | | day of the week (1–7) (Sunday to Saturday)

<nowiki>#</nowiki> | | | month (1–12)

<nowiki>#</nowiki> | | day of the month (1–31)

<nowiki>#</nowiki> | hour (0–23)

<nowiki>#</nowiki> minute (0–59)
|}
Значения также поддерживают списки (<code>1,2,3,4</code>), шаги (<code>0-23/2</code>) и диапазоны (<code>2-5</code>).

Формат не поддерживает указание одновременно значения дня недели и дня месяца. В одном из этих полей необходимо использовать символ ''''?'''<nowiki/>'.

Например, чтобы выполнить запрос в 12:00 каждого буднего дня (с понедельника по пятницу), используйте следующую запись:
{| class="wikitable"
|sqlOracle:

- group: Number of CPU cores

featureSet: cpu

schedule: "0 12 ? * 2-6"

query:

SELECT value AS cpu_count

FROM v$parameter

WHERE name = 'cpu_count'

metrics:

- key: com.astromkey.extension.sql-oracle.cpu.cores

value: col:cpu_count

type: gauge
|}

=== Позвольте пользователям расширения контролировать частоту ===
'''АктивныйШлюз версии 1.303+'''

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

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

Например, чтобы позволить пользователю контролировать интервал:

1. Сначала объявите переменную в вашем файле расширения '''YAML'''.
{| class="wikitable"
|vars:

- id: myInterval

displayName: Interval

description: Interval at which your database provider is queried in minutes. 10 minutes by default.

defaultValue: 10

pattern: ^[0-9]+$

type: text
|}
2. Затем укажите переменную вместо фиксированного значения в вашем файле расширения '''YAML'''.
{| class="wikitable"
|sqlOracle:

- group: Number of CPU cores

interval: var:myInterval

featureSet: cpu

query:

SELECT value AS cpu_count

FROM v$parameter

WHERE name = 'cpu_count'

metrics:

- key: com.astromkey.extension.sql-oracle.cpu.cores

value: col:cpu_count

type: gauge
|}
Дополнительную информацию об использовании переменных см. в разделе [[Расширения YAML-файла|Файл расширения YAML]].

== Тайм-ауты ==
При разработке расширения можно указать значение тайм-аута для данного запроса как на уровне группы, так и на уровне подгруппы. Тайм-ауты указываются в секундах; значение по умолчанию — <code>10</code>. Предоставленное значение должно быть строкой, например: <code>20</code>, <code>60</code>, <code>120</code>, и т. д.

Вы также можете использовать ссылку на переменную для указания тайм-аута. Для получения дополнительной информации об использовании переменных см. [[Расширения YAML-файла|Расширение YAML-файла]].
{| class="wikitable"
|sqlOracle:

- group: Number of CPU cores

timeout: "20"

featureSet: cpu

query: |

SELECT value AS cpu_count

FROM v$parameter

WHERE name = 'cpu_count'

metrics:

- key: com.astromkey.extension.sql-oracle.cpu.cores

value: col:cpu_count

type: gauge
|}
Важные уточнения при установке тайм-аутов

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

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

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

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

=== Значение размера ===
Вы используете '''SQL'''-запрос для получения значения для вашего измерения (префикс с <code>col:</code>) или используете фиксированную строку (префикс с <code>const:</code>). Например:
{| class="wikitable"
|query: >

SELECT event, wait_class

FROM v$system_event

dimensions:

- key: event

value: col:event

- key: wait_class

value: col:wait_class

- key: stage

value: const:dev
|}

=== Фильтровать извлеченные метрические строки ===
'''АктивныйШлюз версии 1.311+'''

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

Фильтры можно задать как постоянное значение или как переменную.
{| class="wikitable"
|dimensions:

- key: event

value: col:event

filter: var:event_filter

- key: wait_class

value: col:wait_class

filter: const:$not(0)

- key: stage

value: const:dev
|}

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

* Начинается с – используйте определитель <code>const:$prefix</code>. Пример: <code>filter: const:$prefix(xyz)</code>
* Заканчивается на – используйте определитель <code>const:$suffix</code>. Пример: <code>filter: const:$suffix(xyz)</code>
* Содержит – используйте квалификатор <code>const:$contains</code>. Пример: <code>filter: const:$contains(xyz)</code>
* Равно – используйте квалификатор <code>const:$eq</code>. Пример: <code>filter: const:$eq(xyz)</code> Для выражений, упомянутых выше, вы также можете использовать определители:
** <code>const:$and</code>– для соединения двух или более выражений с помощью оператора '''AND'''. Пример: <code>filter: const:$and(<expr1>,<expr2>)</code>
** <code>const:$or</code>– для соединения двух или более выражений с помощью оператора '''OR'''. Пример: <code>filter: const:$or(<expr1>,<expr2>)</code>
** <code>const:$not</code>– для '''отрицания''' выражения. Пример: <code>filter: const:$not(<expr>)</code>

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

Например:
{| class="wikitable"
|sqlOracle:
- group: Number of CPU cores

featureSet: cpu

query:

SELECT value AS cpu_count

FROM v$parameter

WHERE name = 'cpu_count'

metrics:

- key: com.astromkey.extension.sql-oracle.cpu.cores

value: col:cpu_count

type: gauge
|}

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

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

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

=== Значение метрики ===
Значение столбца, запрошенное из вашей базы данных.

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

== Метаданные метрики ==
Расширение может определять метаданные для каждой метрики, доступной в Ключ-АСТРОМ. Например, вы можете добавить отображаемое имя метрики и единицу измерения, которые можно использовать для фильтрации в Визуализации метрик.
{| class="wikitable"
|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
|}

== Набор функций ==
Наборы функций — это категории, в которые вы организуете данные, собранные расширением. В этом примере мы создаем расширение '''Oracle SQL''', собирающее метрики, связанные с производительностью '''ЦП''' и ввода/вывода. Это отражается в организации метрик в связанные наборы функций <code>cpu</code> и <code>io</code>.
{| class="wikitable"
|sqlOracle:

- group: Number of CPU cores

featureSet: cpu

query:

SELECT value AS cpu_count

FROM v$parameter

WHERE name = 'cpu_count'

metrics:

- key: com.astromkey.extension.sql-oracle.cpu.cores

value: col:cpu_count

type: gauge

- group: Physical read bytes

featureSet: io

query: >

SELECT

DECODE(name, 'physical read total bytes', value) AS bytes_written,

DECODE(name, 'physical write total bytes', value) AS bytes_read

FROM v$sysstat

WHERE name IN ('physical read total bytes', 'physical write total bytes')

metrics:

- key: com.astromkey.extension.sql-oracle.io.bytesRead

value: col:bytes_read

type: count

- key: com.astromkey.extension.sql-oracle.io.bytesWritten

value: col:bytes_written

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

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

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

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

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

Формат конфигурации мониторинга зависит от поставщика базы данных. Для получения дополнительной информации см. [[Конфигурация Oracle Database|Конфигурация мониторинга Oracle Database]].

Справка о источнике данных SQL - История изменений

IKuznetsov: Новая страница: «Это общее описание файла расширения '''YAML''' на основе источника данных '''SQL''' и способов об...»