Перенос с пакетов SDK Classic API Application Insights на Azure Monitor OpenTelemetry

Используйте пакет средств разработки программного обеспечения Application Insights .NET (SDK) 3.x, чтобы обновить пакет SDK Application Insights .NET с версии 2.x до реализации на основе OpenTelemetry (OTel). Пакет SDK для 3.x сохраняет большинство интерфейсов TelemetryClient и TelemetryConfiguration API и использует Azure Monitor OpenTelemetry Exporter для отправки телеметрии в Application Insights.

Большинство классических Track* вызовов продолжают функционировать после обновления, но они направляются через внутренний слой привязки, который выдает сигналы OpenTelemetry.

Если вы создаете новое приложение или уже используете дистрибутив OpenTelemetry Azure Monitor, используйте вместо этого Azure Monitor OpenTelemetry Distro. Не используйте SDK Application Insights .NET 3.x и дистрибутив Azure Monitor OpenTelemetry в одном приложении.

Обзор пакета SDK 3.x для Application Insights .NET

Пакет SDK 3.x для Application Insights .NET предоставляет следующие пакеты NuGet:

• Microsoft.ApplicationInsights для TelemetryClient и TelemetryConfiguration
• Microsoft.ApplicationInsights.AspNetCore для основных веб-приложений ASP.NET (активные страницы сервера .NET)
• Microsoft.ApplicationInsights.WorkerService для рабочих служб и консольных приложений
• Microsoft.ApplicationInsights.Web для ASP.NET-приложений на .NET Framework
• Microsoft.ApplicationInsights.NLogTarget для интеграции NLog (бета-версия)

Примеры кода и подробные рекомендации по миграции см. в документации по репозиторию:

• ApplicationInsights-dotnet README
• Основные понятия пакета SDK
• Руководство по миграции: Application Insights 2.x на 3.x

Обновление до версии 3.x

Шаг 1. Удаление ссылок на несовместимые пакеты

Удалите эти пакеты, так как они несовместимы с пакетом SDK 3.x:

• Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel
• Microsoft.ApplicationInsights.DependencyCollector
• Microsoft.ApplicationInsights.EventCounterCollector
• Microsoft.ApplicationInsights.PerfCounterCollector
• Microsoft.ApplicationInsights.WindowsServer
• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.ApplicationInsights.Log4NetAppender
• Microsoft.ApplicationInsights.TraceListener
• Microsoft.ApplicationInsights.DiagnosticSourceListener
• Microsoft.ApplicationInsights.EtwCollector
• Microsoft.ApplicationInsights.EventSourceListener

Пакет SDK 3.x не публикует версии 3.x этих пакетов. Вместо этого используйте поддерживаемые пакеты 3.x, перечисленные в обзоре Application Insights .NET SDK 3.x. В следующих разделах описаны предполагаемые замены для этих пакетов. В некоторых случаях функциональные возможности встроены в поддерживаемые пакеты 3.x или заменяются API OpenTelemetry.

Шаг 2. Обновление версий пакетов до 3.x

Обновите все оставшиеся поддерживаемые пакеты Application Insights до последней версии 3.x.

Шаг 3. Обновление кода и конфигурации для критических изменений

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

• Критические изменения: Application Insights 2.x на 3.x
• Руководство по миграции: Application Insights 2.x на 3.x

Замена удаленных точек расширяемости

2.x SDK для .NET для Application Insights предоставляет специфические для Application Insights типы расширяемости, такие как модули телеметрии, инициализаторы, процессоры и каналы. Пакет SDK для Application Insights .NET 3.x вместо этого использует расширяемость OpenTelemetry.

Подробные рекомендации по замене точек расширяемости 2.x, включая пограничные варианты, см. в руководстве по миграции.

Настройка выборки

Пакет SDK .NET Application Insights 3.x поддерживает два режима выборки для трассировок (запросов и зависимостей):

• Установите SamplingRatio (от 0,0 до 1,0) для выборки на основе процентов.
• Установите TracesPerSecond для выборки с ограничением скорости (по умолчанию: пять трассировок в секунду).

Пакет SDK 3.x применяет те же параметры выборки к запросам и зависимостям. Пакет SDK 3.x не поддерживает отдельные параметры выборки для запросов и зависимостей.

При включении запроса или зависимости в выборку SDK 3.x по умолчанию применяет решение о выборке родительской трассировки к связанным журналам. Чтобы отключить это поведение, установите значение EnableTraceBasedLogsSamplerfalse.

Можно задать SamplingRatio, TracesPerSecondа также EnableTraceBasedLogsSampler в TelemetryConfiguration, appsettings.jsonили applicationinsights.config.

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

Чтобы проверить данные телеметрии во время обновления до пакета SDK 3.x, выполните следующие действия.

• Убедитесь, что перед запуском настроена полная строка подключения. Если вы проверяете данные телеметрии в тестах без реального ресурса, используйте фиктивную строку подключения.
• Сбор журналов самостоятельной диагностики Application Insights для выявления ошибок конфигурации и сбоев экспортера.
• Добавьте экспортер в консоль OpenTelemetry, чтобы убедиться, что трассировки, метрики и логи выдаются должным образом, прежде чем полагаться на прием Azure Monitor.
• Если вы ранее применяли модульное тестирование телеметрии с использованием имитаций ITelemetryChannel, перейдите на проверку, совместимую с OpenTelemetry, например с помощью экспортеров в оперативной памяти или других тестовых экспортеров в непроизводственных средах.
• Убедитесь, что параметры выборки работают должным образом, проверяя решения о трассировке в отношениях родитель-потомок.
• Проверьте атрибуты ресурсов, такие как имя службы, имя роли, экземпляр роли и среда, чтобы обеспечить правильную атрибуцию в Application Insights.
• Если вы перенесли пользовательское обогащение, убедитесь, что свойства отображаются там, где вы этого ожидаете. Сопоставления на основе ресурсов могут отличаться от поведения версий 2.x.

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

• Устранение неполадок в .NET SDK для Application Insights
• Устранение неполадок отсутствующей телеметрии приложения в Azure Monitor Application Insights
• Устранение проблем с большим объемом данных в Application Insights

При обновлении до 3.x изменения кода обычно не требуются. Зависимости пакета SDK 3.x — это версии API без выполнения операций зависимостей пакета SDK 2.x. Однако при использовании с агентом Java версии 3.x, он предоставляет реализацию. В результате ваше пользовательское инструментирование коррелируется с новым автоматизированным инструментированием, предоставляемым агентом Java версии 3.x.

Шаг 1. Обновление зависимостей

Шаг 2. Добавление агента Java 3.x

Добавьте агент Java 3.x в аргументы командной строки Java Virtual Machine (JVM), например:

-javaagent:path/to/applicationinsights-agent-3.7.9.jar

Если вы используете агент Application Insights 2.x Java, просто замените существующий -javaagent:... предыдущим примером.

Шаг 3. Настройка строка подключения для Application Insights

См. статью "Настройка Azure Monitor OpenTelemetry".

Другие примечания

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

Инициализаторы телеметрии

Инициализаторы телеметрии из SDK 2.x не работают при использовании агента 3.x. Многие варианты использования, которые ранее требовали записи TelemetryInitializer, теперь можно решить в Application Insights Java 3.x путем настройки пользовательских измерений или использования унаследованных атрибутов.

TelemetryProcessors

Процессоры телеметрии из пакета SDK версии 2.x не выполняются при использовании агента версии 3.x. Многие сценарии использования, которые ранее требовали записи , теперь можно решить в Application Insights Java 3.x, настроив переопределения выборки .

Несколько приложений в одном JVM

Этот вариант использования можно поддерживать в Application Insights Java 3.x с помощью переопределения имен ролей облака (предварительная версия) и переопределения строк подключения (предварительная версия).

Имена операций

В пакете SDK application Insights Java 2.x имена операций иногда включают полный путь. Рассмотрим пример.

Имена операций в Application Insights Java 3.x обычно предоставляют лучшее агрегированное представление на портале Application Insights U/X. Рассмотрим пример.

Однако для некоторых приложений можно по-прежнему предпочесть агрегированное представление в U/X, указанное предыдущими именами операций. В этом случае используйте функцию обработчиков телеметрии (предварительная версия) в 3.x для репликации предыдущего поведения.

Следующий фрагмент кода настраивает три процессора телеметрии, которые объединяются для репликации предыдущего поведения. Процессоры телеметрии выполняют следующие действия (в порядке):

1. Первый обработчик телеметрии — это обработчик атрибутов (имеет тип attribute), который означает, что он применяется ко всем данным телеметрии, которые имеют атрибуты (в настоящее время requests и dependencies, но в ближайшее время также traces).

   Он соответствует любой телеметрии, которая имеет атрибуты с именем http.request.method и url.path.

   Затем он извлекает url.path атрибут в новый атрибут с именем tempName.

2. Второй обработчик телеметрии — это процессор диапазона (имеет тип span), то есть он применяется к requests и dependencies.

   Он соответствует любому диапазону, у которого есть атрибут с именем tempPath.

   Затем он обновляет имя диапазона из атрибута tempPath.

3. Последний обработчик телеметрии — это обработчик атрибутов, тот же тип, что и первый обработчик телеметрии.

   Он соответствует любой телеметрии, у которой атрибут имеет имя tempPath.

   Затем он удаляет атрибут с именем tempPath. Атрибут отображается как настраиваемое измерение.

{
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "http.request.method" },
            { "key": "url.path" }
          ]
        },
        "actions": [
          {
            "key": "url.path",
            "pattern": "https?://[^/]+(?<tempPath>/[^?]*)",
            "action": "extract"
          }
        ]
      },
      {
        "type": "span",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "name": {
          "fromAttributes": [ "http.request.method", "tempPath" ],
          "separator": " "
        }
      },
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "actions": [
          { "key": "tempPath", "action": "delete" }
        ]
      }
    ]
  }
}

Выборка и отсутствующие журналы

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

Пример проекта

Этот проект пакета SDK Java 2.x переносится на новый проект, используя агента Java 3.x.

В этом руководстве представлено два варианта обновления пакета SDK Node.js 2.X для Application Insights до OpenTelemetry.

• Выполните чистую установку Node.js Azure Monitor OpenTelemetry Distro.

  • Удалите зависимости от классического API Application Insights.
  • Ознакомьтесь с API и терминами OpenTelemetry.
  • Позиционируйте себя, чтобы использовать все, что OpenTelemetry предлагает сейчас и в будущем.

• Обновление до Node.js пакета SDK 3.X.

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

Очистка установки

1. Получите необходимые знания о интерфейсе программирования приложений JavaScript OpenTelemetry (API) и пакете средств разработки программного обеспечения (SDK).

   • Ознакомьтесь с документацией по OpenTelemetry JavaScript.
   • Просмотрите настройки Azure Monitor OpenTelemetry.
   • Оцените добавление, изменение и фильтрацию OpenTelemetry.

2. Удалите зависимость applicationinsights из вашего проекта.

   npm uninstall applicationinsights
   

3. Удалите реализацию ПАКЕТА SDK 2.X из кода.

   Удалите все средства мониторинга Application Insights из кода. Удалите все разделы, в которых клиент Application Insights инициализируется, изменяется или вызывается.

4. Включите Application Insights с помощью дистрибуции OpenTelemetry в Azure Monitor.

   Это важно

   Прежде чем импортировать что-либо другое, вызовите .useAzureMonitor Если сначала импортировать другие библиотеки, можно потерять телеметрию. Выполните getting started, чтобы подключиться к дистрибутиву OpenTelemetry Azure Monitor.

Изменения и ограничения Azure Monitor OpenTelemetry Distro

• API из пакета SDK 2.X Application Insights недоступны в дистрибутиве OpenTelemetry Azure Monitor. Хотя пакет SDK для Application Insights 3.X предоставляет неразрывный путь обновления для приема телеметрии (например, пользовательские события и метрики), большинство API-интерфейсов SDK 2.X не поддерживаются и требуют изменения кода в API на основе OpenTelemetry.
• Фильтрация зависимостей, журналов и исключений по имени операции еще не поддерживается.

Upgrade

1. Обновите зависимость для пакета applicationinsights.

   npm update applicationinsights
   

2. Перестройте приложение.

3. Протестируйте приложение.

   Чтобы избежать использования неподдерживаемых параметров конфигурации в пакете SDK для Application Insights 3.X, см. раздел "Неподдерживаемые свойства".

   Если SDK регистрирует предупреждения о неподдерживаемом использовании API после значительного обновления версии, и вам необходима соответствующая функциональность, продолжайте использовать SDK Application Insights версии 2.X.

Изменения и ограничения

Следующие изменения и ограничения применяются к обоим путям обновления.

поддержка версий Node.js

Пакет SDK Application Insights 3.x поддерживает версию Node.js, если Azure SDK для JavaScript и OpenTelemetry поддерживают версию Node.js. Сведения о текущей поддержке среды выполнения OpenTelemetry см. в разделе "Поддерживаемые среды выполнения OpenTelemetry".

Если вы используете старую версию Node.js, например Node 8, решения OpenTelemetry могут выполняться, но это может привести к непредвиденному поведению или несовместимым изменениям. Пакет SDK Application Insights использует Azure SDK для JavaScript, а Azure SDK для политики поддержки JavaScript не гарантирует поддержку Node.js версий, которые достигли конца жизни. Дополнительные сведения см. в политике поддержки Azure SDK для JS.

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

Пакет SDK Application Insights версии 2.X предлагает параметры конфигурации, которые недоступны в дистрибутиве OpenTelemetry Azure Monitor или в обновлении основной версии до пакета SDK Application Insights 3.X. Сведения об этих изменениях, а также о параметрах, которые SDK по-прежнему поддерживает, см. в документации по настройке SDK.

Расширенные метрики

Пакет SDK Для Application Insights 2.X поддерживает расширенные метрики. Однако поддержка этих метрик прекращается как в версии 3.X SDK ApplicationInsights, так и в Azure Monitor OpenTelemetry Distro.

Обработчики данных телеметрии

Хотя Azure Monitor OpenTelemetry Distro и SDK Application Insights 3.X не поддерживают процессоры телеметрии, они позволяют передавать обработчики интервалов и записей журнала. Дополнительные сведения см. в проекте Azure Monitor OpenTelemetry Distro.

В этом примере показывается процесс создания и применения обработчика телеметрии, который добавляет пользовательское свойство в Application Insights SDK версии 2.X.

const applicationInsights = require("applicationinsights");
applicationInsights.setup("YOUR_CONNECTION_STRING");
applicationInsights.defaultClient.addTelemetryProcessor(addCustomProperty);
applicationInsights.start();

function addCustomProperty(envelope: EnvelopeTelemetry) {
    const data = envelope.data.baseData;
    if (data?.properties) {
        data.properties.customProperty = "Custom Property Value";
    }
    return true;
}

В этом примере показано, как изменить реализацию дистрибутива OpenTelemetry Azure Monitor для передачи spanProcessor в конфигурацию дистрибутива.

import { Context, Span} from "@opentelemetry/api";
import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

class SpanEnrichingProcessor implements SpanProcessor {
    forceFlush(): Promise<void> {
        return Promise.resolve();
    }
    onStart(span: Span, parentContext: Context): void {
        return;
    }
    onEnd(span: ReadableSpan): void {
        span.attributes["custom-attribute"] = "custom-value";
    }
    shutdown(): Promise<void> {
        return Promise.resolve();
    }
}

const options = {
    azureMonitorExporterOptions: {
        connectionString: "YOUR_CONNECTION_STRING"
    },
    spanProcessors: [new SpanEnrichingProcessor()],
};
useAzureMonitor(options);

Выполните следующие действия, чтобы перенести приложения Python в Azure Monitor OpenTelemetry Distro.

Шаг 1. Удаление библиотек OpenCensus

Удалите все библиотеки, связанные с OpenCensus, включая все пакеты PyPI, начинающиеся с opencensus-*.

pip freeze | grep opencensus | xargs pip uninstall -y

Шаг 2. Удаление OpenCensus из кода

Удалите все экземпляры SDK OpenCensus и экспортера для Azure Monitor OpenCensus из вашего кода.

Проверьте операторы import, начинающиеся с opencensus, чтобы найти все интеграции, экспортеры и экземпляры API/SDK OpenCensus, которые необходимо удалить.

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

from opencensus.ext.azure import metrics_exporter
from opencensus.stats import aggregation as aggregation_module
from opencensus.stats import measure as measure_module

from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

from opencensus.ext.azure.log_exporter import AzureLogHandler

Шаг 3. Ознакомьтесь с api и пакетами SDK для OpenTelemetry Python

В следующей документации приведены необходимые знания о api и пакетах SDK для OpenTelemetry Python:

• Документация по OpenTelemetry Python
• Документация по дистрибутиву Azure Monitor по конфигурации и телеметрии

Шаг 4: Настройка дистрибутива OpenTelemetry для Azure Monitor

Следуйте статье о начале работы, чтобы подключиться к дистрибутиву OpenTelemetry Azure Monitor.

Изменения и ограничения

При миграции с OpenCensus на OpenTelemetry могут возникать следующие изменения и ограничения.

Python версии до версии 3.10

Для дистрибутива Azure Monitor OpenTelemetry для Python требуется Python 3.10 или более поздняя версия. Предварительные требования и поддерживаемые версии см. в клиентской библиотеке Azure Monitor Opentelemetry Distro для Python.

Чтобы узнать о статусе версий Python и датах прекращения поддержки, см. поддержка версий Python.

Если вы остаетесь на Python 2.7, 3.4, 3.5 или 3.6, решения OpenTelemetry могут выполняться, но могут вызывать непредвиденное поведение или изменения, нарушающие совместимость, которые корпорация Майкрософт не поддерживает.

Для OpenCensus последняя выпущенная версия opencensus-ext-azure выполняется в этих Python версиях. Проект не публикует новые выпуски.

Configurations

OpenCensus Python предоставляет параметры конфигурации, связанные с коллекцией и экспортом телеметрии. Вы можете достичь одинаковых конфигураций и многое другое с помощью api и пакета SDK OpenTelemetry Python. Python Distro для Azure Monitor OpenTelemetry — это универсальное решение для наиболее распространённых задач мониторинга ваших Python-приложений. Так как дистрибутив инкапсулирует API-интерфейсы OpenTelemetry и пакет SDK, некоторые конфигурации для более редких вариантов использования в настоящее время могут не поддерживаться. Вместо этого вы можете перейти на экспортёр Azure Monitor OpenTelemetry, который, используя API и SDK OpenTelemetry, сможет удовлетворить ваши потребности в мониторинге. Некоторые из этих конфигураций включают:

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

Согласованность с Функции Azure

Чтобы предоставить возможности распределенной трассировки для приложений Python, которые вызывают другие приложения Python в функции Azure, пакет opencensus-extension-azure-functions создает подключенный распределенный граф.

В настоящее время решения OpenTelemetry для Azure Monitor не поддерживают этот сценарий. В качестве обходного решения можно вручную распространить контекст трассировки в приложении функций Azure, как показано в следующем примере.

from opentelemetry.context import attach, detach
from opentelemetry.trace.propagation.tracecontext import \
  TraceContextTextMapPropagator

# Context parameter is provided for the body of the function
def main(req, context):
  functions_current_context = {
    "traceparent": context.trace_context.Traceparent,
    "tracestate": context.trace_context.Tracestate
  }
  parent_context = TraceContextTextMapPropagator().extract(
      carrier=functions_current_context
  )
  token = attach(parent_context)

  ...
  # Function logic
  ...
  detach(token)

Расширения и экспортёры

Пакет SDK OpenCensus предоставляет интеграции для сбора телеметрии и экспортеры для отправки телеметрии. В OpenTelemetry интеграции называются инструментациями. OpenTelemetry также использует термин экспортеров.

OpenTelemetry Python инструменты и экспортеры включают в себя набор OpenCensus и добавляют новые библиотеки. OpenTelemetry обеспечивает прямое обновление в охвате библиотеки и функциональных возможностях.

Дистрибутив OpenTelemetry Azure Monitor включает несколько популярных Python инструментовок. Используйте эти инструменты без добавления кода. Майкрософт поддерживает эти инструменты.

Что касается остальных инструментариев OpenTelemetry для Python, не включённых в этот список, вы всё равно можете вручную использовать их для инструментации. Однако стабильность и поведение не гарантированы или поддерживаются в этих случаях. Поэтому используйте их по своему усмотрению.

Если вы хотите предложить для включения в дистрибутив библиотеку инструментирования, созданную сообществом, опубликуйте идею или проголосуйте за неё в сообществе обратной связи. Для экспортеров дистрибутив Azure Monitor OpenTelemetry поставляется вместе с встроенным экспортером Azure Monitor OpenTelemetry. Если вы также хотите использовать других экспортеров, их можно использовать с дистрибутивом, как показано в этом примере.

Обработчики данных телеметрии

В мире OpenTelemetry нет процессоров телеметрии, но у него есть API и классы, которые можно использовать для репликации того же поведения.

Настройка имени облачной роли и экземпляра облачной роли

Чтобы задать имя облачной роли и экземпляр облачной роли для телеметрии, см. раздел Конфигурация OpenTelemetry. Функция OpenTelemetry Azure Monitor Distro автоматически извлекает значения из переменных среды и заполняет соответствующие поля.

Изменение диапазонов с помощью SpanProcessors

Скоро.

Изменение метрик с помощью представлений

Скоро.

Счетчики производительности

Экспортер OpenCensus Python Azure Monitor автоматически собирает системные и связанные с производительностью метрики, называемые счетчиками производительности. Эти метрики отображаются в performanceCounters экземпляре Application Insights. В OpenTelemetry вы больше не отправляете эти метрики явным образом в performanceCounters. Метрики, связанные с входящими и исходящими запросами, можно найти в стандартных метриках. Если вы хотите, чтобы OpenTelemetry автоматически собирал системные метрики, вы можете использовать экспериментальный инструментарий для системных метрик, разработанный сообществом OpenTelemetry Python. Этот пакет является экспериментальным и официально не поддерживается Microsoft.

Support

Чтобы ознакомиться с шагами по устранению неполадок, вариантами поддержки или предоставить обратную связь по OpenTelemetry, см. статью Устранение неполадок, поддержка и обратная связь по OpenTelemetry для Azure Monitor Application Insights.