Habilitación de Azure Monitor OpenTelemetry Exporter para aplicaciones de .NET, Node.js y Python (versión preliminar)

OpenTelemetry Exporter de Azure Monitor es un componente que envía seguimientos (y, finalmente, toda la telemetría de la aplicación) a Azure Monitor Application Insights. Para obtener más información sobre conceptos de OpenTelemetry, consulte Introducción a OpenTelemetry o las preguntas más frecuentes sobre el estándar.

En este artículo se explica cómo habilitar y configurar la oferta de versión preliminar de Azure Monitor basada en OpenTelemetry. Cuando termine de leer las instrucciones de este artículo, podrá enviar seguimientos de OpenTelemetry a Azure Monitor Application Insights.

Importante

Azure Monitor OpenTelemetry Exporter para aplicaciones de .NET, Node.js y Python se encuentra actualmente en versión preliminar. Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

Limitaciones de la versión preliminar

Considere detenidamente si esta versión preliminar satisface sus necesidades. La versión habilita únicamente el seguimiento distribuido y excluye lo siguiente:

Si necesita una experiencia con todas las características, use el SDK de ASP.NET o ASP.NET Core existente de Application Insights hasta que la oferta basada en OpenTelemetry madure.

Introducción

Siga los pasos de esta sección para instrumentar la aplicación con OpenTelemetry.

Requisitos previos

Instalación de las bibliotecas cliente

Instale el paquete NuGet Azure.Monitor.OpenTelemetry.Exporter más reciente:

dotnet add package --prerelease Azure.Monitor.OpenTelemetry.Exporter 

Si recibe un error como "No hay ninguna versión disponible del paquete "Azure.Monitor.OpenTelemetry.Exporter", probablemente se deba a que falta el valor de los orígenes del paquete NuGet. Pruebe a especificar el origen con la opción -s:

# Install the latest package with the NuGet package source specified.
dotnet add package --prerelease Azure.Monitor.OpenTelemetry.Exporter -s https://api.nuget.org/v3/index.json

Habilitación de Azure Monitor Application Insights

En esta sección se proporcionan instrucciones para habilitar OpenTelemetry.

Incorporación de código de instrumentación de OpenTelemetry

En el siguiente código se muestra cómo habilitar OpenTelemetry en una aplicación de consola de C# configurando OpenTelemetry TracerProvider. Este código debe estar en el inicio de la aplicación. En el caso de ASP.NET Core, suele realizarse en el método ConfigureServices de la clase Startup de la aplicación. En el caso de las aplicaciones ASP.NET, suele realizarse en Global.asax.cs.

using System.Diagnostics;
using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Trace;

public class Program
{
    private static readonly ActivitySource MyActivitySource = new ActivitySource(
        "OTel.AzureMonitor.Demo");

    public static void Main()
    {
        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddSource("OTel.AzureMonitor.Demo")
            .AddAzureMonitorTraceExporter(o =>
            {
                o.ConnectionString = "<Your Connection String>";
            })
            .Build();

        using (var activity = MyActivitySource.StartActivity("TestActivity"))
        {
            activity?.SetTag("CustomTag1", "Value1");
            activity?.SetTag("CustomTag2", "Value2");
        }

        System.Console.WriteLine("Press Enter key to exit.");
        System.Console.ReadLine();
    }
}

Nota

Las clases Activity y ActivitySource del espacio de nombres System.Diagnostics representan respectivamente los conceptos de Span y Tracer de OpenTelemetry. Para crear ActivitySource directamente, use su constructor en lugar de TracerProvider. Cada clase ActivitySource debe estar conectada explícitamente a TracerProvider mediante AddSource(). El motivo es que algunas partes de la API de seguimiento de OpenTelemetry se incorporan directamente al runtime de .NET. Para más información, vea Introducción a la API de seguimiento de .NET OpenTelemetry.

Sugerencia

Agregue bibliotecas de instrumentación para recopilar automáticamente datos de telemetría en marcos y bibliotecas populares.

Establecimiento de la cadena de conexión de Application Insights

Reemplace el marcador de posición <Your Connection String> del código anterior por la cadena de conexión de su recurso de Application Insights.

Captura de pantalla de la cadena de conexión de Application Insights

Confirmación de que los datos fluyen

Ejecute la aplicación y abra la pestaña Recurso de Application Insights en Azure Portal. Los datos pueden tardar unos minutos en aparecer en el portal.

Nota

Si no puede ejecutar la aplicación o no obtiene datos según lo esperado, consulte Solución de problemas.

Captura de pantalla de la pestaña

Importante

Si tiene dos o más servicios que emiten datos de telemetría al mismo recurso de Application Insights, es obligatorio establecer nombres de rol en la nube para representarlos correctamente en el mapa de aplicación.

Como parte del uso de la instrumentación de Application Insights, se recopilan y envían datos de diagnóstico a Microsoft. Estos datos ayudan a ejecutar y mejorar Application Insights. Tiene la opción de deshabilitar la recopilación de datos no esenciales. Para obtener más información, consulte Statsbeat en Azure Application Insights.

Establecimiento del nombre y la instancia de rol en la nube

Puede establecer el nombre y la instancia de rol en la nube mediante los atributos de Recurso. Este paso actualiza los valores predeterminados del nombre y la instancia de rol en la nube a algo que tenga sentido para su equipo. Estos valores aparecerán en el mapa de aplicación como el nombre debajo de un nodo. El nombre de rol en la nube usa los atributos service.namespace y service.name, aunque recurre a service.name si no se establece service.namespace. Instancia de rol en la nube usa el valor del atributo service.instance.id.

// Setting role name and role instance
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);
// Done setting role name and role instance

// Set ResourceBuilder on the provider.
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .SetResourceBuilder(resourceBuilder)
        .AddSource("OTel.AzureMonitor.Demo")
        .AddAzureMonitorTraceExporter(o =>
        {
            o.ConnectionString = "<Your Connection String>";
        })
        .Build();

Para obtener información sobre los atributos estándar de recursos, consulte Convenciones semánticas de recursos.

muestreo

En estos momentos se admite muestreo en OpenTelemetry, pero no así en Azure Monitor OpenTelemetry Exporter.

Advertencia

Al habilitar el muestreo en OpenTelemetry, las métricas estándar y basadas en registros se vuelven extremadamente imprecisas, lo que afecta negativamente a todas las experiencias de Application Insights. Además, la habilitación del muestreo junto con los SDK de Application Insights existentes da lugar a seguimientos rotos.

Bibliotecas de instrumentación

Las siguientes bibliotecas están validadas para funcionar con la versión preliminar.

Advertencia

Las bibliotecas de instrumentación se basan en especificaciones experimentales de OpenTelemetry. El compromiso de soporte técnico de la versión preliminar de Microsoft es garantizar que las siguientes bibliotecas emitan datos a Azure Monitor Application Insights, aunque es posible que los cambios importantes o la asignación experimental bloqueen algunos elementos de datos.

HTTP

Base de datos

Nota

La oferta de la versión preliminar solo incluye instrumentaciones que controlan solicitudes HTTP y de base de datos. Consulte Convenciones semánticas de OpenTelemetry para obtener más información.

Modificación de la telemetría

En esta sección se explica cómo modificar la telemetría.

Incorporación de atributos de intervalo

Puede agregar atributos de intervalo mediante cualquiera de los dos métodos siguientes:

Estos atributos pueden incluir agregar una propiedad personalizada a sus datos de telemetría. También puede usar atributos para establecer campos opcionales en el esquema de Application Insights, como la IP de cliente.

Sugerencia

La ventaja de usar las opciones proporcionadas por las bibliotecas de instrumentación, cuando están disponibles, es que se dispone de todo el contexto. En consecuencia, los usuarios pueden optar por agregar o filtrar más atributos. Por ejemplo, la opción de enriquecimiento de la biblioteca de instrumentación HttpClient proporciona a los usuarios acceso al propio httpRequestMessage. Pueden seleccionar lo que deseen de él y almacenarlo como atributo.

Adición de una propiedad personalizada

Los atributos que se agregan a intervalos se exportan como propiedades personalizadas. Rellenan el campo customDimensions de las solicitudes o las tablas de dependencias de Application Insights.

  1. Muchas bibliotecas de instrumentación proporcionan una opción de enriquecimiento. Para obtener instrucciones, consulte el archivo Léame de cada biblioteca de instrumentación:

  2. Use un procesador personalizado:

Sugerencia

Agregue el procesador que se muestra a continuación antes de Azure Monitor Exporter.

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .AddSource("OTel.AzureMonitor.Demo")
        .AddProcessor(new ActivityEnrichingProcessor())
        .AddAzureMonitorTraceExporter(o =>
        {
                o.ConnectionString = "<Your Connection String>"
        })
        .Build();

Agregue ActivityEnrichingProcessor.cs al proyecto con el siguiente código:

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Trace;

public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

Establecimiento de la IP de usuario

Para rellenar el campo client_IP de solicitudes, establezca el atributo http.client_ip en el intervalo. Application Insights usa la dirección IP para generar atributos de ubicación del usuario y luego la descarta de manera predeterminada.

Use el ejemplo de incorporación de propiedad personalizada, pero reemplace las siguientes líneas de código en ActivityEnrichingProcessor.cs:

// only applicable in case of activity.Kind == Server
activity.SetTag("http.client_ip", "<IP Address>");

Telemetría de filtro

Use los siguientes métodos para filtrar los datos de telemetría antes de que salgan de la aplicación.

  1. Muchas bibliotecas de instrumentación proporcionan una opción de filtrado. Para obtener instrucciones, consulte el archivo Léame de cada biblioteca de instrumentación:

  2. Use un procesador personalizado:

    using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddSource("OTel.AzureMonitor.Demo")
            .AddProcessor(new ActivityFilteringProcessor())
            .AddAzureMonitorTraceExporter(o =>
            {
                    o.ConnectionString = "<Your Connection String>"
            })
            .Build();
    

    Agregue ActivityFilteringProcessor.cs al proyecto con el siguiente código:

    using System.Diagnostics;
    using OpenTelemetry;
    using OpenTelemetry.Trace;
    
    public class ActivityFilteringProcessor : BaseProcessor<Activity>
    {
        public override void OnStart(Activity activity)
        {
            // prevents all exporters from exporting internal activities
            if (activity.Kind == ActivityKind.Internal)
            {
                activity.IsAllDataRequested = false;
            }
        }
    }
    
  3. Si un determinado origen no se agrega de manera explícita mediante AddSource("ActivitySourceName"), no se exportará ninguna de las actividades creadas con ese origen.

Habilitación del exportador de OTLP

Es posible que quiera habilitar el exportador de OpenTelemetry Protocol (OTLP) junto con Azure Monitor Exporter para enviar los datos de telemetría a dos ubicaciones.

Nota

El exportador de OTLP solo se muestra por comodidad. Oficialmente, no proporcionamos soporte técnico con relación al exportador de OTLP ni componentes o experiencias de terceros de nivel inferior. Se recomienda abrir una incidencia con OpenTelemetry-Collector en caso de problemas de OpenTelemetry que no sean del ámbito del Soporte técnico de Azure.

  1. Instale el paquete OpenTelemetry.Exporter.OpenTelemetryProtocol junto con Azure.Monitor.OpenTelemetry.Exporter en el proyecto.

  2. Agregue el siguiente fragmento de código. En este ejemplo se da por hecho que tiene un recopilador de OpenTelemetry con un receptor de OTLP en ejecución. Para obtener más información, consulte el ejemplo en GitHub.

    // Sends data to Application Insights as well as OTLP
    using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddSource("OTel.AzureMonitor.Demo")
            .AddAzureMonitorTraceExporter(o =>
            {
                o.ConnectionString = "<Your Connection String>"
            })
            .AddOtlpExporter()
            .Build();
    

Solución de problemas

En esta sección se proporciona ayuda para solucionar problemas.

Activación del registro de diagnóstico

Azure Monitor Exporter usa EventSource para sus propios registros internos. Los registros del exportador están disponibles para cualquier elemento EventListener si se opta por el origen de nombre "OpenTelemetry-AzureMonitor-Exporter". En Solución de problemas de OpenTelemetry puede consultar los pasos para solucionar distintos problemas.

Problemas conocidos

Los problemas conocidos de Azure Monitor OpenTelemetry Exporter incluyen:

  • Falta el nombre de la operación en los datos de telemetría de dependencias, lo que afecta negativamente a la experiencia de la pestaña "Errores y rendimiento".
  • Falta el modelo de dispositivo en los datos de telemetría de solicitudes y dependencias, lo que afecta negativamente al análisis de cohortes de dispositivos.
  • El nombre del servidor de base de datos queda fuera del nombre de dependencia, lo que provoca que se agreguen incorrectamente tablas con el mismo nombre en diferentes servidores.

Soporte técnico

Para obtener soporte técnico:

En caso de problemas de OpenTelemetry, póngase en contacto con la comunidad de .NET de OpenTelemetry directamente.

Comentarios de OpenTelemetry

Para proporcionar comentarios:

Pasos siguientes