Обработчики телеметрии (предварительная версия) — Azure Monitor Application Insights для Java

Модуль Java 3.x для Application Insights может обрабатывать данные телеметрии перед их экспортом.

Некоторые варианты использования:

• Маскирование конфиденциальных данных.
• Условное добавление пользовательских измерений.
• Обновление имени диапазона, который используется для агрегирования сходных данных телеметрии на портале Azure.
• Удаление определенных атрибутов диапазона, чтобы контролировать расходы на прием данных.
• Отфильтруйте определенные метрики, чтобы контролировать расходы на сбор данных.

Терминология

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

Диапазон — это тип телеметрии, представляющий один из следующих типов:

• Входящий запрос.
• Исходящая зависимость (например, удаленный вызов другой службы).
• Внутрипроцессный набор зависимостей (например, работа, выполняемая подкомпонентами службы).

Журнал — это тип телеметрии, который представляет:

• данные журнала, полученные из Log4j, Logback и java.util.log

Для обработчиков телеметрии важны следующие компоненты: охват и журнал.

• Имя.
• Тело
• Атрибуты

Название промежутка является основным отображаемым элементом для запросов и зависимостей на портале Azure. Атрибуты диапазона представляют стандартные и пользовательские свойства заданного запроса или зависимости.

Сообщение трассировки или текст — это основной способ отображения журналов на портале Azure. Атрибуты журнала представляют как стандартные, так и пользовательские свойства заданного журнала.

Типы обработчиков данных телеметрии

В настоящее время четыре типа процессоров телеметрии являются

• Обработчики атрибутов
• Процессоры диапазона
• Обработчики журналов
• Фильтры метрик

Обработчик атрибутов может вставлять, обновлять, удалять или хэшировать атрибуты элемента телеметрии (span или log). Он также может извлекать один или несколько новых атрибутов из существующего атрибута с помощью регулярного выражения.

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

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

Фильтр метрик может отфильтровывать метрики для контроля затрат на обработку.

Начало работы

Для начала создайте файл конфигурации с именем applicationinsights.json. Сохраните его в том же каталоге, что и applicationinsights-agent-*.jar. Используйте следующий шаблон.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        ...
      },
      {
        "type": "attribute",
        ...
      },
      {
        "type": "span",
        ...
      },
      {
        "type": "log",
        ...
      },
      {
        "type": "metric-filter",
        ...
      }
    ]
  }
}

Обработчик атрибутов

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

• insert
• update
• delete
• hash
• extract
• mask

insert

Действие insert вставляет новый атрибут в элемент телеметрии, где пока нет key.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "value1",
        "action": "insert"
      }
    ]
  }
]

Для выполнения действия insert требуются следующие параметры:

• key
• value или fromAttribute
• action: insert

update

Действие update обновляет атрибут в элементе телеметрии, где уже существует key.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "newValue",
        "action": "update"
      }
    ]
  }
]

Для выполнения действия update требуются следующие параметры:

• key
• value или fromAttribute
• action: update

delete

Действие delete удаляет атрибут из элемента телеметрии.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "delete"
      }
    ]
  }
]

Для выполнения действия delete требуются следующие параметры:

• key
• action: delete

hash

Действие hash хэширует (SHA1) существующее значение атрибута.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "hash"
      }
    ]
  }
]

Для выполнения действия hash требуются следующие параметры:

• key
• action: hash

extract

Действие extract с помощью правила регулярного выражения извлекает значения из входного ключа в целевые ключи, указанные правилом. Если целевой ключ уже существует, действие extract переопределяет его. Это действие работает как параметр toAttributes, где существующий атрибут является источником.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "pattern": "<regular pattern with named matchers>",
        "action": "extract"
      }
    ]
  }
]

Для выполнения действия extract требуются следующие параметры:

• key
• pattern
• action: extract

mask

Значения атрибутов mask маскируются с помощью правила регулярного выражения, указанного в pattern и replace.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attributeName",
        "pattern": "<regular expression pattern>",
        "replace": "<replacement value>",
        "action": "mask"
      }
    ]
  }
]

Для выполнения действия mask требуются следующие параметры:

• key
• pattern
• replace
• action: mask

pattern может содержать именованную группу, расположенную между ?< и >:. Пример: (?<userGroupName>[a-zA-Z.:\/]+)\d+? Группа — (?<userGroupName>[a-zA-Z.:\/]+), а userGroupName — это название группы. pattern затем может содержать ту же именованную группу, расположенную между ${ и }, за которой следует маска. Пример маски : **: ${userGroupName}**.

См. Примеры обработчика телеметрии для примеров маскирования.

Критерии включения и исключения

Обработчики атрибутов поддерживают необязательные критерии include и exclude. Обработчик атрибутов применяется только к телеметрии, которая соответствует его include критериям (если она доступна) и не соответствует его exclude критериям (если оно доступно).

Чтобы настроить этот параметр, для include или exclude (или для обоих) укажите хотя бы один matchType и либо spanNames, либо attributes. Конфигурация include или exclude допускает наличие более чем одного указанного условия. Все указанные условия должны оцениваться как истина, чтобы обеспечить совпадение.

• Обязательные поля:

  • matchType определяет, как интерпретируются элементы в spanNames массивах и attributes массивах. Возможные значения: regexp и strict. Сопоставление регулярных выражений выполняется для всего значения атрибута, поэтому, если нужно сопоставить значение, содержащее abc в любом месте, необходимо использовать шаблон .*abc.*.

• Необязательные поля:

  • spanNames должно соответствовать хотя бы одному из элементов.
  • attributes указывает список атрибутов для соответствия. Для обеспечения соответствия требуется точное совпадение всех этих атрибутов.

Пример использования

"processors": [
  {
    "type": "attribute",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "redact_trace",
          "value": "false"
        }
      ]
    },
    "actions": [
      {
        "key": "credit_card",
        "action": "delete"
      },
      {
        "key": "duplicate_key",
        "action": "delete"
      }
    ]
  }
]

Дополнительные сведения см. в статье с примерами обработчиков данных телеметрии.

Процессор диапазонов

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

Назовите диапазон

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

Параметр separator является необязательным. Этот параметр представляет собой строку, и вы можете использовать разделенные значения.

"processors": [
  {
    "type": "span",
    "name": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
] 

Извлечение атрибуты из имени диапазона

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

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

Извлеченные имена атрибутов заменяют значения в имени диапазона. Каждое правило в списке является строкой шаблона регулярного выражения (regex).

Вот как извлеченные имена атрибутов заменяют значения:

1. Имя диапазона проверяется на соответствие регулярному выражению.
2. Все именованные подвыражения регулярного выражения извлекаются как атрибуты, если регулярное выражение соответствует.
3. Извлеченные атрибуты добавляются в диапазон.
4. Каждое имя части выражения становится именем атрибута.
5. Часть подвыражения, которая совпала, становится значением атрибута.
6. Имя извлеченного атрибута заменяет соответствующую часть в имени диапазона. Если атрибуты уже существуют в диапазоне, они будут перезаписаны.

Этот процесс повторяется для всех правил в том порядке, в котором они указаны. Каждое последующее правило работает с именем диапазона, которое является выходным результатом предыдущего правила.

"processors": [
  {
    "type": "span",
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Общие атрибуты диапазона

В этом разделе перечислены некоторые общие атрибуты диапазона, используемые обработчиками данных телеметрии.

Диапазоны HTTP

Диапазоны подключений к базе данных Java

В следующей таблице описываются атрибуты, которые можно использовать в диапазонах подключения к базе данных Java (JDBC):

Критерии включения и исключения

Обработчики диапазонов поддерживают необязательные критерии include и exclude. Обработчик диапазона применяется только к телеметрии, которая соответствует его include критериям (если она доступна) и не соответствует его exclude критериям (если оно доступно).

Чтобы настроить этот параметр, укажите для include или exclude (или для обоих) по крайней мере один matchType и либо spanNames, либо диапазон attributes. Конфигурация include или exclude допускает наличие более чем одного указанного условия. Все указанные условия должны оцениваться как истина, чтобы обеспечить совпадение.

• Обязательные поля:

  • matchType определяет, как интерпретируются элементы в spanNames массивах и attributes массивах. Возможные значения: regexp и strict. Сопоставление регулярных выражений выполняется для всего значения атрибута, поэтому, если нужно сопоставить значение, содержащее abc в любом месте, необходимо использовать шаблон .*abc.*.

• Необязательные поля:

  • spanNames должно соответствовать хотя бы одному из элементов.
  • attributes указывает список атрибутов для соответствия. Для обеспечения соответствия требуется точное совпадение всех этих атрибутов.

Пример использования

"processors": [
  {
    "type": "span",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "attributeValue1"
        }
      ]
    },
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Дополнительные сведения см. в статье с примерами обработчиков данных телеметрии.

Обработчик журналов

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

Обновление текста сообщения журнала

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

Параметр separator является необязательным. Этот параметр является строкой. Его можно указать для разделения значений.

"processors": [
  {
    "type": "log",
    "body": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
] 

Извлечение атрибутов из текста сообщения журнала

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

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

Извлеченные имена атрибутов заменяют значения в тексте сообщения журнала. Каждое правило в списке является строкой шаблона регулярного выражения (regex).

Вот как извлеченные имена атрибутов заменяют значения:

1. Текст сообщения журнала проверяется по регулярному выражению.
2. Все именованные подвыражения регулярного выражения извлекаются как атрибуты, если регулярное выражение соответствует.
3. Извлеченные атрибуты добавляются в журнал.
4. Каждое имя части выражения становится именем атрибута.
5. Часть подвыражения, которая совпала, становится значением атрибута.
6. Имя извлеченного атрибута заменяет соответствующую часть в имени журнала. Если атрибуты уже существуют в журнале, они будут перезаписаны.

Этот процесс повторяется для всех правил в том порядке, в котором они указаны. Каждое последующее правило работает с именем журнала, которое является выходным результатом предыдущего правила.

"processors": [
  {
    "type": "log",
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Критерии включения и исключения

Обработчики журналов поддерживают необязательные критерии include и exclude. Обработчик журналов применяется только к телеметрии, которая соответствует его include критериям (если она доступна) и не соответствует его exclude критериям (если оно доступно).

Чтобы настроить этот параметр, в разделе include или exclude (или в обоих) укажите matchType и attributes. Конфигурация include или exclude допускает наличие более чем одного указанного условия. Все указанные условия должны оцениваться как истина, чтобы обеспечить совпадение.

• Обязательное поле:
  • matchType управляет интерпретацией элементов в массивах attributes. Возможные значения: regexp и strict. Сопоставление регулярных выражений выполняется для всего значения атрибута, поэтому, если нужно сопоставить значение, содержащее abc в любом месте, необходимо использовать шаблон .*abc.*.
  • attributes указывает список атрибутов для соответствия. Для обеспечения соответствия требуется точное совпадение всех этих атрибутов.

Пример использования

"processors": [
  {
    "type": "log",
    "include": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "value1"
        }
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute2",
          "value": "value2"
        }
      ]
    },
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Дополнительные сведения см. в статье с примерами обработчиков данных телеметрии.

Фильтр метрик

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

Фильтры метрик поддерживают только критерии exclude. Метрики, соответствующие условиям, exclude не экспортируются.

Чтобы настроить этот параметр, в разделе exclude укажите matchType одно или несколько значений metricNames.

• Обязательное поле:
  • matchType управляет способом сопоставления элементов в metricNames. Возможные значения: regexp и strict. Сопоставление регулярных выражений выполняется для всего значения атрибута, поэтому, если нужно сопоставить значение, содержащее abc в любом месте, необходимо использовать шаблон .*abc.*.
  • metricNames должно соответствовать хотя бы одному из элементов.

Пример использования

В следующем примере показано, как исключить метрики с именами metricA и metricB:

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "strict",
      "metricNames": [
        "metricA",
        "metricB"
      ]
    }
  }
]

В следующем примере показано, как отключить все метрики, включая метрики производительности по умолчанию, такие как ЦП и память.

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "regexp",
      "metricNames": [
        ".*"
      ]
    }
  }
]

Метрики по умолчанию, захваченные агентом Java

Дальнейшие шаги

• Чтобы просмотреть часто задаваемые вопросы (часто задаваемые вопросы) см. раздел "Часто задаваемые вопросы о обработчиках телеметрии"