Перенос с пакетов 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.5.jar

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

Шаг 3. Настройка connection string для 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 с помощью переопределения имени роли Cloud (превью) и/или переопределения строк подключения (превью).

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

В пакете 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 для JavaScript.

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

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

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

Расширенные метрики поддерживаются в пакете SDK для Application Insights 2.X; однако поддержка этих метрик заканчивается как в версии 3.X пакета SDK Application Insights, так и в дистрибутиве Azure Monitor OpenTelemetry.

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

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

В этом примере показывается процесс создания и применения обработчика телеметрии, который добавляет пользовательское свойство в 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 из вашего кода.

Проверьте инструкции импорта, начинающиеся с 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. Знакомство с openTelemetry Python API/SDK

В следующей документации приведены предварительные знания о Python API-интерфейсах и пакетах SDK OpenTelemetry.

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

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

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

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

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

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

Мониторинг на основе OpenTelemetry для Python поддерживает Python 3.7 и более поздних версий. OpenTelemetry не поддерживает Python 2.7, 3.4, 3.5 или 3.6.

Python 2.7, 3.4, 3.5 и 3.6 достигли конца срока службы. Для состояния версии перейдите в раздел Python поддержка версий.

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

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

Configurations

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

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

Согласованность с Azure Functions

Для предоставления возможностей распределенной трассировки для приложений 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. Если вы также хотите использовать других экспортеров, их можно использовать с дистрибутивом, как показано в этом примере.

TelemetryProcessors

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

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

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

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

Скоро.

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

Скоро.

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

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

Support

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