Compartir vía

Configuración de OpenTelemetry de Azure Monitor

  • Artículo

En este artículo se tratan las opciones de configuración de la distribución de OpenTelemetry de Azure Monitor.

Cadena de conexión

Una cadena de conexión en Application Insights define la ubicación de destino para enviar datos de telemetría.

Use una de las tres maneras siguientes para configurar la cadena de conexión:

  • Agregue UseAzureMonitor() al archivo de program.cs :

    var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
    options.ConnectionString = "<Your Connection String>";
});

var app = builder.Build();

app.Run();

  • Establezca una variable de entorno.

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

  • Agregue la siguiente sección al archivo de configuración appsettings.json.

    {
  "AzureMonitor": {
      "ConnectionString": "<Your Connection String>"
  }
}

Nota:

Si estableciera la cadena de conexión en más de un lugar, se adherirá a la siguiente precendencia:

  1. Código
  2. Variable de entorno
  3. Archivo de configuración

Establecimiento del nombre y la instancia de rol en la nube

Para idiomas admitidos, la distribución OpenTelemetry de Azure Monitor detecta automáticamente el contexto de recursos y proporciona valores predeterminados para el Nombre de rol en la nube y las propiedades de instancia de rol en la nube del componente. Sin embargo, es posible que desee reemplazar los valores predeterminados por algo que tenga sentido para el equipo. El valor del nombre del rol en la nube aparece en el mapa de aplicaciones como el nombre debajo de un nodo.

Puede establecer el nombre y la instancia de rol en la nube mediante los atributos de Recurso. 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. Para obtener información sobre los atributos estándar de recursos, consulte Convenciones semánticas de OpenTelemetry.

// Setting role name and role instance

// Create a dictionary of resource attributes.
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry()
    .UseAzureMonitor()
    // Configure the ResourceBuilder to add the custom resource attributes to all signals.
    // Custom resource attributes should be added AFTER AzureMonitor to override the default ResourceDetectors.
    .ConfigureResource(resourceBuilder => resourceBuilder.AddAttributes(_testResourceAttributes));

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Habilitación del muestreo

Es posible que quiera habilitar el muestreo para reducir el volumen de ingesta de datos, lo que reduce el coste. Azure Monitor proporciona un muestreo personalizado de frecuencia fija que rellena los eventos con una relación de muestreo, que Application Insights convierte en ItemCount. El muestreo de frecuencia fija garantiza experiencias y recuentos de eventos precisos. El muestreo está diseñado para conservar los seguimientos entre servicios y es interoperable con los kits de desarrollo de software (SDK) más antiguos de Application Insights. Para más información, consulte Más información sobre el muestreo.

Nota:

Las métricas y los registros no se ven afectados por el muestreo.

El muestreo espera una frecuencia de muestreo de entre 0 y 1 inclusive. Una tasa de 0,1 significa que se envía aproximadamente el 10 % de los seguimientos.

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    options.SamplingRatio = 0.1F;
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Sugerencia

Al usar el muestreo de frecuencia fija o porcentaje y no está seguro de qué establecer la frecuencia de muestreo como, comience en el 5 % (es decir, una relación de muestreo de 0,05) y ajuste la velocidad en función de la precisión de las operaciones que se muestran en los paneles de rendimiento y errores. Una tasa más alta suele dar como resultado una mayor precisión. Sin embargo, CUALQUIER muestreo afectará a la precisión, por lo que se recomienda alertar sobre las métricas de OpenTelemetry, que no se ven afectadas por el muestreo.

Live metrics

Métricas en directo proporciona un panel de análisis en tiempo real para concluir información sobre la actividad y el rendimiento de la aplicación.

Importante

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.

Esta característica está habilitada de forma predeterminada.

Los usuarios pueden deshabilitar Métricas en directo al configurar la distribución.

builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
	// Disable the Live Metrics feature.
    options.EnableLiveMetrics = false;
});

Habilitación de la autenticación de Microsoft Entra ID (anteriormente Azure AD)

Es posible que quiera habilitar la autenticación de Microsoft Entra para una conexión más segura a Azure, lo que impide que se ingieran datos de telemetría no autorizados en la suscripción.

Se admiten las clases de credenciales proporcionadas por Azure Identity.

  • Se recomienda DefaultAzureCredential para el desarrollo local.
  • Se recomienda ManagedIdentityCredential para identidades administradas asignadas por el sistema y asignadas por el usuario.
    • En el caso de las asignadas por el sistema, use el constructor predeterminado sin parámetros.
    • En el caso de los asignados por el usuario, proporcione el valor del Id. de cliente al constructor.
  • Se recomienda ClientSecretCredential para las entidades de servicio.
    • Proporcione el identificador de inquilino, el identificador de cliente y el secreto de cliente al constructor.

  1. Instale el paquete Azure.Identity más reciente:

    dotnet add package Azure.Identity

  2. Proporcione la clase de credencial deseada:

    // Create a new ASP.NET Core web application builder.    
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
    // Set the Azure Monitor credential to the DefaultAzureCredential.
    // This credential will use the Azure identity of the current user or
    // the service principal that the application is running as to authenticate
    // to Azure Monitor.
    options.Credential = new DefaultAzureCredential();
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Almacenamiento sin conexión y reintentos automáticos

Para mejorar la confiabilidad y la resistencia, las ofertas basadas en OpenTelemetry de Azure Monitor escriben en un almacenamiento sin conexión o local de manera predeterminada cuando una aplicación pierde su conexión con Application Insights. Guarda la telemetría de la aplicación en el disco e intenta enviarla periódicamente durante un máximo de 48 horas. En las aplicaciones de alta carga, la telemetría se anula ocasionalmente por dos razones. En primer lugar, cuando se supera el tiempo permitido y, en segundo lugar, cuando se excede el tamaño máximo del archivo o el SDK no tiene la oportunidad de borrarlo. Si es necesario elegir, el producto guarda los eventos más recientes sobre los antiguos. Más información

El paquete de la distribución incluye AzureMonitorExporter que, de manera predeterminada, usa una de las siguientes ubicaciones para el almacenamiento sin conexión (se muestra en orden de prioridad):

  • Windows
    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor
  • Distinta de Windows
    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor
    • /tmp/Microsoft/AzureMonitor

Para invalidar el directorio predeterminado, debe establecer AzureMonitorOptions.StorageDirectory.

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
    // This is the directory where the OpenTelemetry SDK will store any telemetry data that cannot be sent to Azure Monitor immediately.
    options.StorageDirectory = "C:\\SomeDirectory";
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Para deshabilitar esta característica, debe establecer AzureMonitorOptions.DisableOfflineStorage = true.

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.

  1. Instale el paquete OpenTelemetry.Exporter.OpenTelemetryProtocol en el proyecto.

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  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.

    // Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Add the OpenTelemetry OTLP exporter to the application.
// This exporter will send telemetry data to an OTLP receiver, such as Prometheus
builder.Services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter());
builder.Services.AddOpenTelemetry().WithMetrics(builder => builder.AddOtlpExporter());

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Configuración de OpenTelemetry

Se puede acceder a las siguientes configuraciones de OpenTelemetry a través de variables de entorno al usar las distribuciones de OpenTelemetry de Azure Monitor.

Variable de entorno Descripción
APPLICATIONINSIGHTS_CONNECTION_STRING Establezca esto en la cadena de conexión del recurso de Application Insights.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Establézcalo en true para no participar en la recopilación de métricas internas.
OTEL_RESOURCE_ATTRIBUTES Pares clave-valor que se usarán como atributos de recursos. Para obtener más información sobre los atributos de recursos, consulte la especificación del SDK de recursos.
OTEL_SERVICE_NAME Establece el valor del atributo de recurso service.name. Si service.name también se proporciona en OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME tendrá prioridad.

Tachar cadenas de consulta URL

Para tachar las cadenas de consulta URL, desactive la recopilación de cadenas de consulta. Recomendamos esta configuración si llama al almacenamiento de Azure usando un token de SAS.

Al usar el paquete de distribución Azure.Monitor.OpenTelemetry.AspNetCore, tanto ASP.NET Core como HttpClient. se incluyen las bibliotecas de instrumentación. Nuestro paquete de distribución establece la acción de tachar cadenas de consulta como desactivada de forma predeterminada.

Para cambiar este comportamiento, debe establecer una variable de entorno en "true" o "false".

  • Instrumentación de ASP.NET Core: la acción de tachar cadenas de consulta de OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION está deshabilitada de manera predeterminada. Para habilitarla, establezca esta variable de entorno en "falso".
  • Instrumentación de cliente Http: la acción de tachar cadenas de consulta de OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION está deshabilitada de manera predeterminada. Para habilitarla, establezca esta variable de entorno en "falso".