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

Статья
09/13/2024

Примечание.

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

Агент 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 доступна только в версии 3.0.2 и более поздних версиях.

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

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

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

key
pattern
action: extract

`mask`

Примечание.

Эта mask функция доступна только в версии 3.2.5 и более поздних версиях.

Значения 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 критериям (если оно доступно).

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

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

Примечание.

Если указаны оба критерия, exclude и include, свойства include проверяются перед проверкой свойств exclude.

Примечание.

Если для конфигурации include или exclude не указан spanNames, критерии сопоставления применяются к spans и logs.

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

"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).

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

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

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

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

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

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

Диапазоны HTTP

Атрибут	Тип	Описание
`http.request.method` (используется `http.method`)	строка	Метод HTTP-запроса.
`url.full` (диапазон клиента) или `url.path` (диапазон сервера) (используется `http.url`)	строка	Полный URL-адрес HTTP-запроса в форме `scheme://host[:port]/path?query[#fragment]`. Фрагмент обычно не передается по протоколу HTTP. Но если фрагмент известен, его следует включить.
`http.response.status_code` (используется `http.status_code`)	number	Код состояния HTTP-ответа.
`network.protocol.version` (используется `http.flavor`)	строка	Тип протокола HTTP.
`user_agent.original` (используется `http.user_agent`)	строка	Значение заголовка HTTP User-Agent, отправленного клиентом.

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

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

Атрибут	Тип	Описание:
`db.system`	строка	Идентификатор используемого продукта из системы управления базами данных (СУБД). См . семантические соглашения для операций с базами данных.
`db.connection_string`	строка	Строка подключения, используемая для подключения к базе данных. Рекомендуется удалить внедренные учетные данные.
`db.user`	строка	Имя пользователя для доступа к базе данных.
`db.name`	строка	Строка, используемая для сообщения имени базы данных, к которой осуществляется доступ. Для команд, которые переключают базу данных, в этой строке следует указать целевую базу данных, даже если команда завершается с ошибкой.
`db.statement`	строка	Выполняемая инструкция базы данных.

Критерии include и exclude

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

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

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

Примечание.

Если указаны оба критерия, exclude и include, свойства include проверяются перед проверкой свойств exclude.

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

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

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

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

Примечание.

Обработчики журналов доступны начиная с версии 3.1.1.

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

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

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

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

Примечание.

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

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

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

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

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

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

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

Текст сообщения журнала проверяется по регулярному выражению.
Все именованные вложенные выражения регулярного выражения извлекаются как атрибуты, если regex соответствует.
Извлеченные атрибуты добавляются в журнал.
Каждое имя части выражения становится именем атрибута.
Соответствующая часть выражения становится значением атрибута.
Имя извлеченного атрибута заменяет соответствующую часть в имени журнала. Если атрибуты уже существуют в журнале, они будут перезаписаны.

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

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

Критерии include и exclude

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

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

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

Примечание.

Если указаны оба критерия, exclude и include, свойства include проверяются перед проверкой свойств exclude.

Примечание.

Обработчики журналов не поддерживают spanNames.

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

"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"
        ]
      }
    }
  }
]

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

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

Примечание.

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

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

Фильтры метрик поддерживают только критерии 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

Имя метрики	Тип метрики	Description	Доступно для фильтрации
`Current Thread Count`	пользовательские метрики	См. ThreadMXBean.getThreadCount().	yes
`Loaded Class Count`	пользовательские метрики	См. ClassLoadingMXBean.getLoadedClassCount().	yes
`GC Total Count`	пользовательские метрики	Сумма счетчиков во всех экземплярах GarbageCollectorMXBean (diff с момента последнего сообщения). См. GarbageCollectorMXBean.getCollectionCount().	yes
`GC Total Time`	пользовательские метрики	Сумма времени для всех экземпляров GarbageCollectorMXBean (diff с момента последнего сообщения). См. GarbageCollectorMXBean.getCollectionTime().	yes
`Heap Memory Used (MB)`	пользовательские метрики	См. MemoryMXBean.getHeapMemoryUsage().getUsed().	yes
`% Of Max Heap Memory Used`	пользовательские метрики	java.lang:type=Memory / максимальный объем памяти в байтах. См. MemoryUsage	yes
`\Processor(_Total)\% Processor Time`	метрики по умолчанию	Разница в счетчиках тика загрузки ЦП в системе (только пользователь и система), разделенная на количество логических процессоров за заданный интервал времени.	no
`\Process(??APP_WIN32_PROC??)\% Processor Time`	метрики по умолчанию	См. OperatingSystemMXBean.getProcessCpuTime() (изменение с момента последнего отчета, нормализовано по времени и количеству ЦП).	no
`\Process(??APP_WIN32_PROC??)\Private Bytes`	метрики по умолчанию	Сумма значений MemoryMXBean.getHeapMemoryUsage() и MemoryMXBean.getNonHeapMemoryUsage().	no
`\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec`	метрики по умолчанию	`/proc/[pid]/io` Объем данных в байтах, считанных и записанных процессом (разница с момента последнего отчета). См. proc(5).	no
`\Memory\Available Bytes`	метрики по умолчанию	См. OperatingSystemMXBean.getFreePhysicalMemorySize().	no

Часто задаваемые вопросы

Почему файлы журнала обработчика журналов не используются с помощью TelemetryClient.trackTrace()?

TelemetryClient.trackTrace() является частью моста классического пакета SDK Application Insights, а обработчики журналов работают только с новым инструментированием на основе OpenTelemetry.

Поделиться через

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

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

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

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

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

`insert`

`update`

`delete`

`hash`

`extract`

`mask`

Критерии include и exclude

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

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

Задание имени диапазону

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

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

Диапазоны HTTP

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

Критерии include и exclude

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

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

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

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

Критерии include и exclude

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

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

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

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

Часто задаваемые вопросы

Почему файлы журнала обработчика журналов не используются с помощью TelemetryClient.trackTrace()?

Обратная связь

Дополнительные ресурсы