Версия: 8.7

Oracle Requests

Общие сведения

Название плагина: oracleDbSqlRequest
Ссылка для загрузки плагина: скачать
Описание:
Данный плагин позволяет выполнить SQL запрос в СУБД Oracle

Соединение с БД осуществляется напрямую с использованием параметров: Username, Password, Host и Port.
Параметры будут передаваться в задании потока.
Подключение по умолчанию производится с ролью Normal.

возможна потеря данных

Помимо запросов SELECT, синтаксис позволяет использовать также и запросы INSERT, DELETE, UPDATE, REPLACE и другие, что потенциально может привести к потере данных при неаккуратном обращении.
Крайне рекомендуется использовать УЗ с правами только на чтение.

совместимость версий

Проверена и поддерживается совместимость с версиями Oracle DB: 19c, 21c, 23ai

Формат сценария задания потока данных

#Формат задания
 
jobs:
  - name: request to oracledb
    steps:
      - name: request to oracledb
      - plugin: oracleDbSqlRequest
        with:
          streamId: $.vars.stream.id
          streamKey: $.vars.stream.key
          # Имя хоста для подключения к серверу oracle.
          # Обязательный параметр.
          host: <string>
          # Номер порта для подключения к серверу oracle.
          # Опционально. По умолчанию 1521.
          port: <integer>
          # Подключиться, используя имя службы или идентификатор SID
          # Допустимые значения ServiceName, SID. По умолчанию ServiceName.
          connectionIdentifiers: <string>
          # Имя базы данных для подключения.
          # Обязательный параметр.
          dbname: <string>
          # Запрос в БД.
          # Обязательный параметр.
          query: <string>
          # Способ отправки результатов выполнения запроса.
          # Допустимые значения events и metrics.
          # Опционально. По умолчанию event.
          sendAs: <enum>
          # Параметры отправки результатов выполнения запроса как события.
          # Используется только если sendAs = events
          sendAsEvents:
            # Количество строк в выборке, отправляемых за раз в одном событии.
            # Опционально. По умолчанию 100.
            batchSize: <integer>
          # Параметры отправки результатов выполнения запроса как метрики.
          # Используется только если sendAs = metrics
          sendAsMetrics:
            # Количество строк в выборке, отправляемых за раз в коллектор метрик.
            # Опционально. По умолчанию 10.
            batchSize: <integer>
            # Указание имени, которое будет добавлено как суффикс к результирующему названию метрики, начинающейся с oracledb_mon.
            # Опционально. По умолчанию пустая строка.
            metricNameSuffix: <string>
            # Таймаут для запросов на отправку метрик в коллектор Monq. Допустимо указание в секундах (s), миллисекундах (ms).
            # Опционально. По умолчанию 30s.
            writeTimeout: <string>
            # Задержка начальной повторной попытки отправки метрик. Удваивается при каждой повторной попытке. Допустимо указание в секундах (s), миллисекундах (ms).
            # Опционально. По умолчанию 30ms.
            writeMinBackoff: <string>
            # Максимальная задержка повторной попытки отправки метрик. Допустимо указание в секундах (s), миллисекундах (ms).
            # Опционально. По умолчанию 5s.
            writeMaxBackoff: <string>
            # Список меток, добавляемых к полученным метрикам.
            # Опционально. По умолчанию пустой список.
            labels:
              label1: Label1_Value
              label2: Label2_Value
            # Параметры для преобразования таблицы с результатами запроса в метрики.
            tableConversion:
              # Указание имени колонки, ячейки которой будут содержать значение метрики.
              # Опционально. По умолчанию VALUE.
              valueColumn: <string>
              # Список колонок из ответа, которые надо преобразовать в метки.
              # Опционально. По умолчанию пустой список.
              labelColumns:
                - Column1
                - Column2
          # Фиксировать время выполнения запроса в БД в формате метрического ряда или нет.
          # Опционально. По умолчанию false. Измеряется в секундах.
          sendQueryResponseTime: <boolean>
          # Параметры отправки времени выполнения запроса. Используется только если sendQueryResponseTime = true
          queryResponseTimeMetric:
            # Список меток, добавляемых к полученным метрикам.
            # Опционально. По умолчанию пустой список.
            labels:
              label1: Label1_Value
              label2: Label2_Value
          # Допустимые значения для LogLevel: trace, debug, information, warning, error, critical, none
          # Опционально. Уровень логирования выполнения заданий, выводящихся в лог работы агента. По умолчанию error
          consoleSyncLogLevel: <string>
          # Опционально. Уровень логирования выполнения заданий, отправляющихся в коллектор событий. По умолчанию error
          syncLogLevel: <string>
        with-secured:
            # Username - для подключения к серверу oracledb
            username: <string>
            # Password - для подключения к серверу oracledb
            password: <string>

Параметры конфигурации, используемые в сценарии

Параметр	Тип	Обязательно	По умолчанию	Возможные значения	Описание
streamId	string	+	-	Любая строка	Идентификатор текущего потока (`$.vars.stream.id`)
streamKey	string	+	-	Любая строка	API ключ текущего потока (`$.vars.stream.key`)
username	string	+	-	Любая строка	Логин для подключения к серверу oracledb
password	string	+	-	Любая строка	Пароль для подключения к серверу oracledb
host	string	+	-	Любая строка	Адрес для подключения к серверу oracledb
port	integer	-	1521	От 1 до 65535	Порт - для подключения к серверу oracledb
connectionIdentifiers	string	-	ServiceName	ServiceName, SID	SID = уникальное имя вашего экземпляра БД, ServiceName = псевдоним, используемый при подключении. Подключиться, используя имя службы или идентификатор SID.
dbname	string	-	-	Любая строка	Имя базы данных для подключения
query	string	+	-	Любая строка	Запрос в БД
sendAs	enum	-	event	events, metrics	Способ отправки результатов выполнения запроса: в виде json-объекта или в виде prometheus-метрики
sendAsEvents		-			Параметры отправки результатов выполнения запроса как события. Используется только если `sendAs = events`
batchSize	integer	-	100	От 1 до 65535	Количество строк в выборке, отправляемых за раз в одном событии
sendAsMetrics		-			Параметры отправки результатов выполнения запроса как метрики. Используется только если `sendAs = metrics`
batchSize	integer	-	10	От 1 до 65535	Количество строк в выборке, отправляемых за раз в коллектор метрик
metricNameSuffix	string	-	-	Любая строка	Указание имени, которое будет добавлено как суффикс к результирующему названию метрики, начинающейся с `oracledb_mon`
writeTimeout	string	-	30s	Только в секундах (s) или миллисекундах (ms)	Таймаут для запросов на отправку метрик в коллектор Monq
writeMinBackoff	string	-	30ms	Только в секундах (s) или миллисекундах (ms)	Задержка начальной повторной попытки отправки метрик
writeMaxBackoff	string	-	5s	Только в секундах (s) или миллисекундах (ms)	Максимальная задержка повторной попытки отправки метрик
labels	enum	-	-	Перечисление в виде ключ-значение	Список меток, добавляемых к полученным метрикам
tableConversion		-			Параметры для преобразования таблицы с результатами запроса в метрики
valueColumn	string	-	VALUE	Любая строка	Указание имени колонки, ячейки которой будут содержать значение метрики
labelColumns	enum	-	-	Перечисление в виде ключ-значение	Список колонок из ответа, которые надо преобразовать в метки
sendQueryResponseTime	boolean	-	false	true/false	Фиксировать время выполнения запроса в БД в формате метрического ряда или нет
queryResponseTimeMetric					Параметры отправки времени выполнения запроса. Используется только если `sendQueryResponseTime = true`
labels	enum	-	-	Перечисление в виде ключ-значение	Список меток, добавляемых к полученным метрикам
consoleSyncLogLevel	string	-	error	trace, debug, information, warning, error, critical, none	Уровень логирования выполнения заданий, выводящихся в лог работы агента
syncLogLevel	string	-	error	trace, debug, information, warning, error, critical, none	Уровень логирования выполнения заданий, отправляющихся в коллектор событий

Пример сценария задания на получение метрик

name: request to oracle
jobs:
  - name: request to oracle
    steps:
      - plugin: oracleDbSqlRequest
        with:
          streamId: $.vars.stream.id
          streamKey: $.vars.stream.key
          host: 10.25.0.10
          port: 1521
          dbName: oracle
          query: >
            SELECT COUNT(*) AS COUNT
            FROM TESTTABLE.WORKGROUPS
          sendAsEvents:
            batchSize: 5
            labels:
              event_label1: number_1
              event_label2: number_2
          sendQueryResponseTime: true
          queryResponseTimeMetric:
            labels:
              server: 10.25.0.10
          consoleSyncLogLevel: information
          syncLogLevel: information
        with-secured:
          username: $.vars.stream.params.username
          password: $.vars.stream.params.password

Шаблон ответа

Получаемый результат запроса на стороне плагина преобразовывается в зависимости от установленного параметра sendAs

sendAs = events: в json-формате для отправки в коллектор событий
При этом возможны следующие варианты:
- Запрос подразумевает возврат набора строк,
  например: вывести все записи из таблицы с пользователями мужского пола с информацией о поле и возрасте
```
// QUERY RESULT

name,age,gender
John,30,Male
Alik,25,Male


// FINAL JSON

{
  "source": {
    "requestedData": [
      {
        "name": "John",
        "age": 30,
        "gender": "Male"
      },
      {
        "name": "Alik",
        "age": 25,
        "gender": "Male"
      }
    ]
  }
}
```
  Также можно сформировать запрос для получения нескольких значений подсчета строк с разными условиями и получить следующий результат:
  { "source": { "requestedData": [ { "total": 7, "count1": 2, "count2": 5 } ] } }
- Запрос подразумевает возврат одного значения,
  например: вывести количество записей в таблице, удовлетворяющих заданному в запросе условию
```
// QUERY RESULT

count
2


// FINAL JSON

{
 "source": {
  "requestedData": [
      {
         "count": 2
      }  
    ] 
  }
}
```
  Также можно использовать оператор AS для именования результирующего столбца в выборе и получить следующий результат:
  { "source": { "requestedData": [ { "customCountName": 2 } ] } }
sendAs = metrics: в text/plain формате метрического ряда для отправки в коллектор метрик,
например: результат выполнения select-запроса не превышает заданное пороговое значение, а его превышение свидетельствует о нарушении поведения системы.

Каждое полученное значение упаковывается в отдельный метрический ряд.
Итоговое имя метрики задается пользователем через указание суффикса в параметре metricNameSuffix.
```
// QUERY RESULT

count
7


// FINAL PLAIN TEXT TO METRICS STREAM

oracledb_mon_counter_metric{userLabel="requestToOracle", columnName="count"} 7 1666702336924


// QUERY RESULT

total,count1,count2
7,2,5


// FINAL PLAIN TEXT TO METRICS STREAM

oracledb_mon_counter_metric{userLabel="requestToOracle1", columnName="total"} 7 1666702336924
oracledb_mon_counter_metric{userLabel="requestToOracle1", columnName="count1"} 2 1666702336924
oracledb_mon_counter_metric{userLabel="requestToOracle1", columnName="count2"} 5 1666702336924
```

Общие сведения​

Формат сценария задания потока данных​

Параметры конфигурации, используемые в сценарии​

Пример сценария задания на получение метрик​

Шаблон ответа​

Общие сведения

Формат сценария задания потока данных

Параметры конфигурации, используемые в сценарии

Пример сценария задания на получение метрик

Шаблон ответа