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>
        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	Уровень логирования выполнения заданий, выводящихся в лог работы агента

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

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