Настройка Azure Monitor Application Insights для Java

В этой статье показано, как настроить Azure Monitor Application Insights для Java. Дополнительные сведения см. в статье "Начало работы с OpenTelemetry".

Настройка агента Java

Источник конфигурации JSON

Пользовательские размеры

Если вы хотите добавить пользовательские измерения ко всем вашим данным телеметрии:

{
  "customDimensions": {
    "mytag": "my value",
    "anothertag": "${ANOTHER_VALUE}"
  }
}

Вы можете использовать ${...} для считывания значения из указанной переменной среды при запуске.

Унаследованные атрибуты (предварительная версия)

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

{
  "preview": {
    "inheritedAttributes": [
      {
        "key": "mycustomer",
        "type": "string"
      }
    ]
  }
}

А затем в начале каждого запроса вызов:

Span.current().setAttribute("mycustomer", "xyz");

См. также Добавление настраиваемого свойства в Span.

Настройте переопределения выборки

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

• Установите процент выборки на 0 или небольшое значение для шумных проверок состояния.
• Для шумных вызовов зависимостей задайте процент выборки равным 0 или небольшому значению.
• Задайте процент выборки 100 для важного типа запроса. Например, можно использовать /login , даже если выборка по умолчанию настроена на что-то меньшее.

Применение выборки отменяет терминологию

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

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

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

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

• Атрибуты

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

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

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

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10,
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 0
      },
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 100
      }
    ]
  }
}

Как работает переопределение выборки

telemetryType (telemetryKind в Application Insights 3.4.0) должен быть одним из request, dependency( trace log) или exception.

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

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

Используется только первое совпавшее переопределение выборки. Если ни одно переопределение параметров выборки не будет соответствовать:

• Если это первый диапазон трассировки, используется конфигурация выборки верхнего уровня.
• Если это не первый диапазон трассировки, то используется родительское решение выборки.

Атрибуты диапазона, доступные для выборки

Атрибуты диапазона OpenTelemetry автоматически собираются и основаны на семантических соглашениях OpenTelemetry.

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

Варианты использования переопределения выборки

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

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
        {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/health-check",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "db.system",
            "value": "redis",
            "matchType": "strict"
          },
          {
            "key": "db.statement",
            "value": "GET my-noisy-key",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10
  },
  "sampling": {
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/login",
            "matchType": "strict"
          }
        ],
        "percentage": 100
      }
    ]
  }
}

dependencies
| where timestamp > ago(30d)
| where name == 'SQL: DB Query'
| summarize count() by name, operation_Name, data
| sort by count_ desc

SQL: DB Query    POST /Order             DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    36712549
SQL: DB Query    POST /Receipt           DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    2220248
SQL: DB Query    POST /CheckOutForm      DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    554074
SQL: DB Query    GET /ClientInfo         DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    37064

{
  "attributes": {
    "data": {
      "thread.name": "DefaultDatabaseBroadcastTransport: MessageReader thread",
      "thread.id": 96,
      "db.connection_string": "apache:",
      "db.statement": "DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;",
      "db.system": "other_sql",
      "applicationinsights.internal.item_count": 1
    }s
  }
}

{
  "connectionString": "...",
  "preview": {
    "sampling": {
      "overrides": [
        {
          "telemetryType": "dependency",
          "attributes": [
            {
              "key": "db.statement",
              "value": "DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;",
              "matchType": "strict"
            }
          ],
          "percentage": 0
        }
      ]
    }
  }
}

dependencies
| where timestamp > ago(30d)
| where data contains 'DECLARE @MyVar'
| summarize max(timestamp) by data
| sort by max_timestamp desc

DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    11/13/2023 8:52:41 PM 

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;

public class MdcClass {

  private static final Logger logger = LoggerFactory.getLogger(MdcClass.class);

  void method() {
    MDC.put("key", "value");
    try {
      logger.info(...); // Application log to remove
    } finally {
      MDC.remove("key"); // In a finally block in case an exception happens with logger.info
    }
  }
}

{
  "sampling": {
    "overrides": [
      {
        "telemetryType": "trace",
        "percentage": 0,
        "attributes": [
          {
            "key": "key",
            "value": "value",
            "matchType": "strict"
          }
        ]
      }
    ]
  }
}

<dependency>
  <groupId>io.opentelemetry.instrumentation</groupId>
  <artifactId>opentelemetry-instrumentation-annotations</artifactId>
</dependency>

package org.springframework.samples.petclinic.vet;

@Controller
class VetController {

  private final VetRepository vetRepository;

  public VetController(VetRepository vetRepository) {
    this.vetRepository = vetRepository;
  }

  @GetMapping("/vets.html")
  public String showVetList(@RequestParam(defaultValue = "1") int page, Model model) {
    Vets vets = new Vets();
    Page<Vet> paginated = findPaginated(page);
    vets.getVetList().addAll(paginated.toList());
    return addPaginationModel(page, paginated, model);
  }

  @WithSpan
  private Page<Vet> findPaginated(int page) {
    int pageSize = 5;
    Pageable pageable = PageRequest.of(page - 1, pageSize);
    return vetRepository.findAll(pageable); // Execution of SQL requests
  }
}

"sampling": {
  "overrides": [
    {
      "telemetryType": "dependency",
      "attributes": [
        {
          "key": "code.function",
          "value": "findPaginated",
          "matchType": "strict"
        }
      ],
      "percentage": 0
    }
  ]
}

"sampling": {
  "overrides": [
    {
      "telemetryType": "dependency",
      "attributes": [
        {
          "key": "code.namespace",
          "value": "org.springframework.samples.petclinic.vet.VetController",
          "matchType": "strict"
        }
      ],
      "percentage": 0
    }
  ]
}

Выборка имеет преимущество перед устранением неполадок

См. специальную статью об устранении неполадок.

Часто задаваемые вопросы о переопределении выборки

Чтобы просмотреть часто задаваемые вопросы (FAQ), см. раздел "Часто задаваемые вопросы о переопределениях выборки Sampling overrides FAQ".

Настройка коллекции телеметрии

В этом разделе:

• Настройка метрик JMX
• Автоматическое ведение журнала
• Автосбор метрик Micrometer (включая метрики Spring Boot Actuator)
• Автоматический сбор зависимостей InProc (предварительная версия)
• Загрузчик пакета SDK для браузера (предварительная версия)

Настройка метрик JMX

Как собирать дополнительные метрики JMX

Application Insights Java 3.x собирает некоторые метрики расширений управления Java (JMX) по умолчанию, но чаще всего этого недостаточно. В этом разделе подробно описывается параметр конфигурации JMX.

Коллекция метрик JMX можно настроить, добавив "jmxMetrics" раздел в файл applicationinsights.json . Введите имя для метрики, так как она будет отображаться на портале Azure в ресурсе Application Insights. Имя и атрибут объекта необходимы для каждой из метрик, которые нужно собрать. В именах объектов можно использовать подстановочные знаки в стиле glob, такие как *.

Как узнать, какие метрики доступны для настройки

Свойства, такие как имена объектов и атрибуты, отличаются для различных библиотек, платформ и серверов приложений и часто не хорошо документированы.

Чтобы просмотреть доступные метрики JMX для конкретной среды, задайте уровень DEBUG самостоятельной диагностики в applicationinsights.json файле конфигурации, например:

{
  "selfDiagnostics": {
    "level": "DEBUG"
  }
}

Доступные метрики JMX с именами объектов и именами атрибутов отображаются в файле журнала Application Insights.

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

Вы также можете использовать средство command line для проверки доступных метрик JMX.

Пример конфигурации JMX

Зная, какие метрики доступны, можно настроить агент для их сбора.

"jmxMetrics": [
  {
    "name": "Demo - GC Thread Count",
    "objectName": "java.lang:type=GarbageCollector,name=PS MarkSweep",
    "attribute": "LastGcInfo.GcThreadCount"
  },
  {
    "name": "Demo - GC Collection Count",
    "objectName": "java.lang:type=GarbageCollector,name=PS MarkSweep",
    "attribute": "CollectionCount"
  },
  {
    "name": "Demo - Thread Count",
    "objectName": "java.lang:type=Threading",
    "attribute": "ThreadCount"
  }
]

"jmxMetrics": [
  {
    "name": "Demo - G1 Collection Count Young",
    "objectName": "java.lang:name=G1 Young Generation,type=GarbageCollector",
    "attribute": "CollectionCount"
  },
  {
    "name": "Demo - G1 Collection Count Old",
    "objectName": "java.lang:name=G1 Old Generation,type=GarbageCollector",
    "attribute": "CollectionCount"
  },
  {
    "name": "Demo - Thread Count",
    "objectName": "java.lang:type=Threading",
    "attribute": "ThreadCount"
  }
]

Если вы хотите собрать другие метрики расширений управления Java (JMX):

{
  "jmxMetrics": [
    {
      "name": "JVM uptime (millis)",
      "objectName": "java.lang:type=Runtime",
      "attribute": "Uptime"
    },
    {
      "name": "MetaSpace Used",
      "objectName": "java.lang:type=MemoryPool,name=Metaspace",
      "attribute": "Usage.used"
    }
  ]
}

В предыдущем примере конфигурации:

• name — это имя метрики, назначенное этой метрикой JMX (может быть любым).
• objectName — это имяJMX MBean объекта, который требуется собрать. Символ подстановочного знака (*) поддерживается.
• attribute — это имя атрибута внутри JMX MBean, которое вы хотите собрать.

Поддерживаются числовые и логические значения метрик JMX. Логические метрики JMX сопоставляются со значением 0 для false и 1 для true.

Где найти метрики JMX в Application Insights

Метрики JMX, собранные во время работы приложения, можно просмотреть, перейдя к ресурсу Application Insights на портале Azure. В области метрик выберите раскрывающийся список, как показано для просмотра метрик.

Ведение журнала автоколлектов

Log4j, Logback, JBoss Log и java.util.log автоматически используются. Ведение журнала с помощью этих платформ ведения журнала выполняется автоматически.

Ведение журнала осуществляется только в случае, если:

• Соответствует заданному уровню для платформы ведения журнала.
• Также соответствует настроенному уровню для Application Insights.

Например, если платформа ведения журнала настроена для записи WARN (и вы настроили ее, как описано выше) из пакета com.example, а Application Insights настроена для захвата INFO (и вы настроили, как описано), Application Insights записывает только WARN (и более серьезные) из пакета com.example.

Уровень по умолчанию, настроенный для Application Insights, — INFO. Если вы хотите изменить этот уровень:

{
  "instrumentation": {
    "logging": {
      "level": "WARN"
    }
  }
}

Вы также можете задать уровень с помощью переменной APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVELсреды. Затем он имеет приоритет над уровнем, указанным в конфигурации JSON.

Эти допустимые level значения можно использовать для указания в applicationinsights.json файле. В таблице показано, как они соответствуют уровням ведения журнала в разных платформах ведения журнала.

union traces, (exceptions | extend message = outerMessage)
| project timestamp, message, itemType

Маркеры журналов (предварительная версия)

Начиная с 3.4.2, вы можете записать маркеры журнала для Logback и Log4j 2:

{
  "preview": {
    "captureLogbackMarker": true,
    "captureLog4jMarker": true
  }
}

Другие атрибуты журнала для Logback (предварительная версия)

Начиная с 3.4.3, вы можете записать FileName, ClassName, MethodName и LineNumber для Logback.

{
  "preview": {
    "captureLogbackCodeAttributes": true
  }
}

Уровень логирования в качестве настраиваемого измерения

Начиная с Java агента версии 3.3.0, LoggingLevel по умолчанию не фиксируется в пользовательском измерении Traces, так как эти данные уже записаны в поле SeverityLevel.

При необходимости можно временно повторно включить предыдущее поведение:

{
  "preview": {
    "captureLoggingLevelAsCustomDimension": true
  }
}

Автоматически собранные метрики микрометра (включая метрики Spring Boot Actuator)

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

Если приложение использует Spring Boot Actuator, метрики, настроенные Spring Boot Actuator, также автоматически собираются.

Отправка пользовательских метрик с помощью Micrometer

1. Добавьте Micrometer в приложение, как показано в следующем примере.

   <dependency>
     <groupId>io.micrometer</groupId>
     <artifactId>micrometer-core</artifactId>
     <version>1.6.1</version>
   </dependency>
   

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

   static final Counter counter = Metrics.counter("test.counter");
   

3. Используйте счетчик для записи метрик с помощью следующей команды.

   counter.increment();
   

4. Метрики вносятся в таблицу customMetrics, где захватываются теги, фиксированные в столбце customDimensions. Вы также можете просмотреть метрики в обозревателе метрик в Log-based metrics пространстве имен метрик.

   Примечание.

   Application Insights Java заменяет все нефанумерные символы (за исключением дефисов) в имени метрики Micrometer символами подчеркивания. В результате предыдущая test.counter метрика будет отображаться как test_counter.

Отключение автозаполнения метрик

Чтобы отключить автоматический сбор метрик Micrometer и метрик Spring Boot Actuator, выполните приведенные ниже действия.

{
  "instrumentation": {
    "micrometer": {
      "enabled": false
    }
  }
}

Автоматическая сборка внутрипроцессных зависимостей (предварительная версия)

Если вы хотите записать зависимости контроллера InProc, используйте следующую конфигурацию:

{
  "preview": {
    "captureControllerSpans": true
  }
}

Загрузчик пакета SDK для браузера (предварительная версия)

Эта функция автоматически внедряет загрузчик SDK для браузера в HTML-страницы приложения, а также настраивает соответствующую строку подключения.

Например, когда приложение Java возвращает ответ, например:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Title</title>
  </head>
  <body>
  </body>
</html>

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

<!DOCTYPE html>
<html lang="en">
  <head>
    <script type="text/javascript">
    !function(v,y,T){var S=v.location,k="script"
    <!-- Removed for brevity -->
    connectionString: "YOUR_CONNECTION_STRING"
    <!-- Removed for brevity --> }});
    </script>
    <title>Title</title>
  </head>
  <body>
  </body>
</html>

Скрипт помогает собирать данные телеметрии на стороне клиента и отправлять их вместе с серверной телеметрией на портал Azure пользователя. Подробные сведения можно найти в ApplicationInsights-JS.

Если вы хотите включить эту функцию, добавьте следующий параметр конфигурации:

{
  "preview": {
    "browserSdkLoader": {
      "enabled": true
    }
  }
}

Настройка процессоров телеметрии (предварительная версия)

Обработчики телеметрии можно использовать для настройки правил, применяемых к запросам, зависимостям и телеметрии трассировки. Application Insights Java 3.x может обрабатывать данные телеметрии перед экспортом данных.

Варианты использования:

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

Если вы хотите удалить определенные (целые) интервалы для управления затратами на обработку данных, см. раздел "Настройка переопределения выборки".

Терминология процессоров телеметрии

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

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

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

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

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

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

Типы процессоров телеметрии

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

Начало работы с процессорами телеметрии

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

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

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

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

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

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

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

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

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

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

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

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

Примеры обработчика телеметрии

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

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
    "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "attribute1",
            "value": "attributeValue1",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "newKey",
            "fromAttribute": "anotherKey",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "db.secret",
            "value": "redacted",
            "action": "update"
          },
          {
            "key": "boo",
            "fromAttribute": "foo",
            "action": "update" 
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "user.email",
            "action": "hash"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<httpProtocol>.*):\\/\\/(?<httpDomain>.*)\\/(?<httpPath>.*)(\\?|\\&)(?<httpQueryParams>.*)",
            "action": "extract"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "user\\/\\d+",
            "replace": "user\\/****",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<userGroupName>[a-zA-Z.:\/]+)\d+",
            "replace": "${userGroupName}**",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            {
              "key": "longAttributeKey",
              "value": 1234,
              "type": "long"
            },
            {
              "key": "booleanAttributeKey",
              "value": true,
              "type": "boolean"
            },
            {
              "key": "doubleArrayAttributeKey",
              "value": [1.0, 2.0, 3.0, 4.0],
              "type": "double-array"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyStrict",
            "value": "newAttributeValueStrict",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyStrict"
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "regexp",
          "attributes": [
            {
              "key": "longRegexpAttributeKey",
              "value": "4[0-9][0-9]",
              "type": "long"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyRegexp",
            "value": "newAttributeValueRegexp",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyRegexp"
      }
    ]
  }
}

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

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "fromAttributes": [
            "db.svc",
            "operation",
            "id"
          ],
          "separator": "::"
        }
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "toAttributes": {
            "rules": [
              "^/api/v1/document/(?<documentId>.*)/update$"
            ]
          }
        }
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "include": {
          "matchType": "regexp",
          "spanNames": [
            "^(.*?)/(.*?)$"
          ]
        },
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "donot/change"
          ]
        },
        "name": {
          "toAttributes": {
            "rules": [
              "(?<operation_website>.*?)$"
            ]
          }
        }
      }
    ]
  }
}

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

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "^Starting PetClinicApplication on WorkLaptop with PID (?<PIDVALUE>\\d+) .*"
            ]
          }
        }
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "userId (?<redactedUserId>[0-9a-zA-Z]+)"
            ]
          }
        }
      },
      {
        "type": "attribute",
        "actions": [
          {
            "key": "redactedUserId",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

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

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

Включение и исключение примеров диапазона

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

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ],
          "attributes": [
            {
              "key": "env",
              "value": "dev"
            },
            {
              "key": "test_request"
            }
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "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"
          }
        ]
      }
    ]
  }
}

Часто задаваемые вопросы о процессорах телеметрии

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

Переопределение или подавление поведения по умолчанию

В этом разделе:

• Переопределения строки подключения (предварительный просмотр)
• Переопределение имен ролей в облаке (предварительная версия)
• Настройка строка подключения во время выполнения
• Локально отключить считывание данных (предварительная версия)

Переопределения строк подключения (предварительный просмотр)

Эта функция предоставляется в предварительной версии, начиная с 3.4.0.

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

• Задайте одну строку подключения для одного префикса пути HTTP /myapp1.
• Задайте другую строку подключения для другого HTTP-префикса пути /myapp2/.

{
  "preview": {
    "connectionStringOverrides": [
      {
        "httpPathPrefix": "/myapp1",
        "connectionString": "..."
      },
      {
        "httpPathPrefix": "/myapp2",
        "connectionString": "..."
      }
    ]
  }
}

Переопределения названий облачных ролей (предварительный просмотр)

Эта функция предоставляется в предварительной версии начиная с 3.3.0.

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

• Задайте одно имя облачной роли для одного префикса пути HTTP /myapp1.
• Задайте другое имя облачной роли для другого префикса пути HTTP /myapp2/.

{
  "preview": {
    "roleNameOverrides": [
      {
        "httpPathPrefix": "/myapp1",
        "roleName": "Role A"
      },
      {
        "httpPathPrefix": "/myapp2",
        "roleName": "Role B"
      }
    ]
  }
}

Настройте строку подключения во время выполнения программы

Если вам нужна возможность настроить строка подключения во время выполнения, добавьте это свойство в конфигурацию json:

{
  "connectionStringConfiguredAtRuntime": true
}

Добавьте applicationinsights-core в свое приложение:

<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>applicationinsights-core</artifactId>
  <version>3.7.8</version>
</dependency>

Используйте статический configure(String) метод в классе com.microsoft.applicationinsights.connectionstring.ConnectionString.

Локально отключить выборку данных на этапе приема (предварительный просмотр)

По умолчанию, когда в агенте Java эффективный процент выборки составляет 100%, и на вашем ресурсе Application Insights настроена выборка данных, будет применен процент выборки данных.

Обратите внимание, что это поведение применяется как к выборке фиксированной частоты 100 %, так и к ограниченной частоте выборки, если скорость запроса не превышает предел скорости (эффективно захватывая 100 % во время непрерывного скользящего периода времени).

Начиная с версии 3.5.3 вы можете отключить это поведение (и сохранить 100% телеметрии в этих случаях, даже если в ресурсе Application Insights настроена выборка данных для сбора):

{
  "preview": {
    "sampling": {
      "ingestionSamplingEnabled": false
    }
  }
}

Защита данных телеметрии

Маскирование запросов

Литеральные значения в Java Database Connectivity (JDBC) и в запросах MongoDB маскируются по умолчанию, чтобы избежать случайного захвата конфиденциальных данных.

Начиная с 3.4.0, это поведение можно отключить. Например:

{
  "instrumentation": {
    "jdbc": {
      "masking": {
        "enabled": false
      }
    }
  }
}

{
  "instrumentation": {
    "mongo": {
      "masking": {
        "enabled": false
      }
    }
  }
}

Заголовки HTTP

Вы можете записывать заголовки запросов и ответов на сервере (входящий запрос) и на клиенте (зависимость) в телеметрии:

{
  "preview": {
    "captureHttpServerHeaders": {
      "requestHeaders": [
        "My-Header-A"
      ],
      "responseHeaders": [
        "My-Header-B"
      ]
    }
  }
}

{
  "preview": {
    "captureHttpClientHeaders": {
      "requestHeaders": [
        "My-Header-C"
      ],
      "responseHeaders": [
        "My-Header-D"
      ]
    }
  }
}

Настройка конфигурации среды выполнения и окружения

В этом разделе:

• Аутентификация
• Прокси-сервер HTTP
• Интервал метрик
• Пульс
• Восстановление после сбоев приема
• Самостоятельное диагностика
• Корреляция данных телеметрии

Проверка подлинности

Проверку подлинности можно использовать для настройки агента для создания учетных данных token, необходимых для проверки подлинности Microsoft Entra. Дополнительные сведения см. в статье Аутентификация Microsoft Entra в Application Insights.

Прокси-сервер HTTP

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

Чтобы обойти эту проблему, можно настроить Application Insights Java 3.x для использования прокси-сервера HTTP.

{
  "proxy": {
    "host": "myproxy",
    "port": 8080
  }
}

Вы также можете задать http-прокси с помощью переменной APPLICATIONINSIGHTS_PROXYсреды, которая принимает формат https://<host>:<port>. Затем он имеет приоритет над прокси-сервером, указанным в конфигурации JSON.

Вы можете указать пользователя и пароль для прокси-сервера с помощью переменной APPLICATIONINSIGHTS_PROXY среды: https://<user>:<password>@<host>:<port>

Application Insights Java 3.x также учитывает глобальные https.proxyHost и https.proxyPort системные свойства, если они заданы, и http.nonProxyHosts при необходимости.

Интервал в метриках

По умолчанию метрики фиксируются каждые 60 секунд. Этот интервал можно изменить:

{
  "metricIntervalSeconds": 300
}

Начиная с агента Java версии 3.4.9 (GA), можно также задать metricIntervalSeconds с помощью переменной среды APPLICATIONINSIGHTS_METRIC_INTERVAL_SECONDS. Затем он имеет приоритет над metricIntervalSeconds указанным в конфигурации JSON.

Этот параметр применяется к следующим метрикам:

• Счетчики производительности по умолчанию: например, ЦП и память.
• Пользовательские метрики по умолчанию: например, время сборки мусора.
• Настроенные метрики JMX: см. раздел метрики JMX.
• Метрики микрометра: см. раздел "Автоколлектированные метрики микрометра".

Пульс

По умолчанию Application Insights Java 3.x отправляет метрику пульса каждые 15 минут. Если для активации оповещений используется метрика пульса, можно увеличить частоту этого пульса:

{
  "heartbeat": {
    "intervalSeconds": 60
  }
}

Восстановление после сбоев приема

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

Ограничение по умолчанию для сохранения данных на диске составляет 50 МБ. Если у вас есть высокий объем данных телеметрии или если вам нужно восстановиться после более длительного сбоя сети или сбоев в службах передачи данных, можно увеличить это ограничение.

{
  "preview": {
    "diskPersistenceMaxSizeMb": 50
  }
}

Самодиагностика

"Самостоятельная диагностика" подразумевает внутреннее журналирование в Application Insights Java 3.x. Эта функция предназначена для выявления и диагностики проблем с Application Insights.

По умолчанию Application Insights Java 3.x ведет журналирование на уровне INFO как в файл applicationinsights.log, так и в консоль, соответствуя этой конфигурации:

{
  "selfDiagnostics": {
    "destination": "file+console",
    "level": "INFO",
    "file": {
      "path": "applicationinsights.log",
      "maxSizeMb": 5,
      "maxHistory": 1
    }
  }
}

В предыдущем примере конфигурации:

• level — может быть одно из: OFF, ERROR, WARN, INFO, DEBUG или TRACE.
• path — может быть абсолютный или относительный путь. Относительные пути разрешаются относительно каталога, где находится applicationinsights-agent-3.7.8.jar.

Начиная с версии 3.0.2 Java-агента, вы также можете настроить самодиагностику level с помощью переменной среды APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL. Затем он имеет приоритет над уровнем самодиагностики, указанным в конфигурации JSON.

Начиная с Java агента версии 3.0.3 можно также задать расположение файла самостоятельной диагностики с помощью переменной среды APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_FILE_PATH. Затем он имеет приоритет над путем к файлу самодиагностики, указанному в конфигурации JSON.

Корреляция данных телеметрии

Корреляция телеметрии включена по умолчанию, но ее можно отключить в конфигурации:

{
  "preview": {
    "disablePropagation": true
  }
}

Расширенные и предварительные версии функций

Настраиваемое инструментирование (предварительная версия)

Вы можете записать диапазоны для метода в приложении:

{
  "preview": {
    "customInstrumentation": [
      {
        "className": "my.package.MyClass",
        "methodName": "myMethod"
      }
    ]
  }
}

Предварительные инструментальные средства

Вы можете включить следующие инструменты предварительного просмотра:

{
  "preview": {
    "instrumentation": {
      "akka": {
        "enabled": true
      },
      "apacheCamel": {
        "enabled": true
      },
      "grizzly": {
        "enabled": true
      },
      "ktor": {
        "enabled": true
      },
      "play": {
        "enabled": true
      },
      "r2dbc": {
        "enabled": true
      },
      "springIntegration": {
        "enabled": true
      },
      "vertx": {
        "enabled": true
      }
    }
  }
}

Пример файла конфигурации

В этом примере показано, как выглядит файл конфигурации с несколькими компонентами. Настройте определенные параметры в зависимости от ваших потребностей.

{
  "connectionString": "...",
  "role": {
    "name": "my cloud role name"
  },
  "sampling": {
    "percentage": 100
  },
  "jmxMetrics": [
  ],
  "customDimensions": {
  },
  "instrumentation": {
    "logging": {
      "level": "INFO"
    },
    "micrometer": {
      "enabled": true
    }
  },
  "proxy": {
  },
  "preview": {
    "processors": [
    ]
  },
  "selfDiagnostics": {
    "destination": "file+console",
    "level": "INFO",
    "file": {
      "path": "applicationinsights.log",
      "maxSizeMb": 5,
      "maxHistory": 1
    }
  }
}