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

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

Безопасность расширения

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

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

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

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

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

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

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

В нашем примере мы создаем простое расширение, собирающее основные данные о производительности ЦП из базы данных Oracle.

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 это sqloracle. Все настройки под узлом относятся к объявленному типу источника данных (в данном случае SQL).

JDBC-коннектор

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

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

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

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-запрос возвращает количество ядер ЦП.

SELECT value AS cpu_count FROM v$parameter WHERE name = 'cpu_count'

Вы можете использовать его в своем расширении и сообщать значение, возвращаемое запросом com.astromkey.extension.sql-oracle.cpu.cores, в качестве метрики в Ключ-АСТРОМ.

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. Подробнее см. в разделе Управление безопасностью (ниже).

Частота запроса

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

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

Интервал

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

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

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:

# * * * * * # | | | | | # | | | | day of the week (1–7) (Sunday to Saturday) # | | | month (1–12) # | | day of the month (1–31) # | hour (0–23) # minute (0–59)

Значения также поддерживают списки (1,2,3,4), шаги (0-23/2) и диапазоны (2-5).

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

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

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.

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.

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.

Тайм-ауты

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

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

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-запрос для получения значения для вашего измерения (префикс с col:) или используете фиксированную строку (префикс с const:). Например:

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+

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

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

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

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

• Начинается с – используйте определитель 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 показателей.

Например:

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 метрический узел требует параметр id вместо key. Начиная с Ключ-АСТРОМ версии 1.219, следует использовать параметр key, так как id будет считаться устаревшим.

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

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

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

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

Тип

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

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

Наборы функций — это категории, в которые вы организуете данные, собранные расширением. В этом примере мы создаем расширение Oracle SQL, собирающее метрики, связанные с производительностью ЦП и ввода/вывода. Это отражается в организации метрик в связанные наборы функций cpu и io.

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.