Configuración de OpenTelemetry de Azure Monitor

Artigo
12/27/2023

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 de Application Insights define la ubicación de destino para enviar datos de telemetría, lo que garantiza que alcanza el recurso adecuado para la supervisión y el análisis.

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

Agregue UseAzureMonitor() al inicio de la aplicación, en la clase program.cs.

// 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 => {
    options.ConnectionString = "<Your Connection String>";
});

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

// Start the ASP.NET Core web application.    
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:

Código
Variable de entorno
Archivo de configuración

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

Agregue Azure Monitor Exporter a cada señal de OpenTelemetry en el inicio de la aplicación.

// Create a new OpenTelemetry tracer provider.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddAzureMonitorTraceExporter(options =>
{
    options.ConnectionString = "<Your Connection String>";
});

// Create a new OpenTelemetry meter provider.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter(options =>
    {
        options.ConnectionString = "<Your Connection String>";
    });

// Create a new logger factory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter(options =>
        {
            options.ConnectionString = "<Your Connection String>";
        });
    });
});

Establezca una variable de entorno.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Nota:

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

Código
Variable de entorno

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

Establezca una variable de entorno.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Use un objeto de configuración.

// Import the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions class from the @azure/monitor-opentelemetry package.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");

// Create a new AzureMonitorOpenTelemetryOptions object.
const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString: "<your connection string>"
  }
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

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

Establezca una variable de entorno.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Mediante la función configure_azure_monitor.

# Import the `configure_azure_monitor()` function from the `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor

# Configure OpenTelemetry to use Azure Monitor with the specified connection string.
# Replace `<your-connection-string>` with the connection string of your Azure Monitor Application Insights resource.
configure_azure_monitor(
    connection_string="<your-connection-string>",
)

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 OpenTelemetry tracer provider to add the resource attributes to all traces.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
    builder.ConfigureResource(resourceBuilder => 
        resourceBuilder.AddAttributes(resourceAttributes)));

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

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

// 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 resource builder.
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

// Create a new OpenTelemetry tracer provider and set the resource builder.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    // Set ResourceBuilder on the TracerProvider.
    .SetResourceBuilder(resourceBuilder)
    .AddAzureMonitorTraceExporter();

// Create a new OpenTelemetry meter provider and set the resource builder.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    // Set ResourceBuilder on the MeterProvider.
    .SetResourceBuilder(resourceBuilder)
    .AddAzureMonitorMetricExporter();

// Create a new logger factory and add the OpenTelemetry logger provider with the resource builder.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        // Set ResourceBuilder on the Logging config.
        options.SetResourceBuilder(resourceBuilder);
        options.AddAzureMonitorLogExporter();
    });
});

// Import the useAzureMonitor function, the AzureMonitorOpenTelemetryOptions class, the Resource class, and the SemanticResourceAttributes class from the @azure/monitor-opentelemetry, @opentelemetry/resources, and @opentelemetry/semantic-conventions packages, respectively.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");
const { Resource } = require("@opentelemetry/resources");
const { SemanticResourceAttributes } = require("@opentelemetry/semantic-conventions");

// Create a new Resource object with the following custom resource attributes:
//
// * service_name: my-service
// * service_namespace: my-namespace
// * service_instance_id: my-instance
const customResource = new Resource({
  [SemanticResourceAttributes.SERVICE_NAME]: "my-service",
  [SemanticResourceAttributes.SERVICE_NAMESPACE]: "my-namespace",
  [SemanticResourceAttributes.SERVICE_INSTANCE_ID]: "my-instance",
});

// Create a new AzureMonitorOpenTelemetryOptions object and set the resource property to the customResource object.
const options: AzureMonitorOpenTelemetryOptions = {
  resource: customResource
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

Establezca los atributos de los recursos usando las variables de entorno OTEL_RESOURCE_ATTRIBUTES y/o OTEL_SERVICE_NAME. OTEL_RESOURCE_ATTRIBUTES toma series de pares clave-valor separados por comas. Por ejemplo, para establecer el Nombre del rol en la nube en my-namespace.my-helloworld-service y establecer la Instancia de rol en la nube en my-instance, puede establecer OTEL_RESOURCE_ATTRIBUTES y OTEL_SERVICE_NAME como tal:

export OTEL_RESOURCE_ATTRIBUTES="service.namespace=my-namespace,service.instance.id=my-instance"
export OTEL_SERVICE_NAME="my-helloworld-service"

Si no establece el atributo de recurso service.namespace, puede establecer de manera alternativa el Nombre del rol en la nube solo con la variable de entorno OTEL_SERVICE_NAME o el atributo de recurso service.name. Por ejemplo, para establecer el Nombre del rol en la nube en my-helloworld-service y establecer la Instancia de rol en la nube en my-instance, puede establecer OTEL_RESOURCE_ATTRIBUTES y OTEL_SERVICE_NAME como tal:

export OTEL_RESOURCE_ATTRIBUTES="service.instance.id=my-instance"
export OTEL_SERVICE_NAME="my-helloworld-service"

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 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(o =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    o.SamplingRatio = 0.1F;
});

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

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

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 OpenTelemetry tracer provider.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(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;
    });

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.

// Import the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions class from the @azure/monitor-opentelemetry package.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");

// Create a new AzureMonitorOpenTelemetryOptions object and set the samplingRatio property to 0.1.
const options: AzureMonitorOpenTelemetryOptions = {
  samplingRatio: 0.1
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

La función configure_azure_monitor() usa automáticamente ApplicationInsightsSampler para la compatibilidad con los SDK de Application Insights y para muestrear la telemetría. La variable de entorno OTEL_TRACES_SAMPLER_ARG puede usarse para especificar la frecuencia de muestreo, con un rango válido de 0 a 1, donde 0 es 0 % y 1 es 100 %. Por ejemplo, un valor de 0,1 significa que se envía aproximadamente el 10 % de los seguimientos.

export OTEL_TRACES_SAMPLER_ARG=0.1

Sugerencia

Cuando use un muestreo de tasa fija/porcentaje, si no está seguro de dónde establecer la frecuencia de muestreo, comience en un 5 % (es decir, una relación de muestreo de 0,05) y ajústela en función de la precisión de las operaciones mostradas en las hojas 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.

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.

Instale el paquete Azure.Identity más reciente:
```
dotnet add package Azure.Identity
```

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();

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.

Instale el paquete Azure.Identity más reciente:
```
dotnet add package Azure.Identity
```

Proporcione la clase de credencial deseada:

// Create a DefaultAzureCredential.
var credential = new DefaultAzureCredential();

// Create a new OpenTelemetry tracer provider and set the credential.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(options =>
    {
        options.Credential = credential;
    });

// Create a new OpenTelemetry meter provider and set the credential.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter(options =>
    {
        options.Credential = credential;
    });

// Create a new logger factory and add the OpenTelemetry logger provider with the credential.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter(options =>
        {
            options.Credential = credential;
        });
    });
});

Se admiten las clases de credenciales proporcionadas por Azure Identity.

// Import the useAzureMonitor function, the AzureMonitorOpenTelemetryOptions class, and the ManagedIdentityCredential class from the @azure/monitor-opentelemetry and @azure/identity packages, respectively.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");
const { ManagedIdentityCredential } = require("@azure/identity");

// Create a new ManagedIdentityCredential object.
const credential = new ManagedIdentityCredential();

// Create a new AzureMonitorOpenTelemetryOptions object and set the credential property to the credential object.
const options: AzureMonitorOpenTelemetryOptions = {
    azureMonitorExporterOptions: {
        credential: credential
    }
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

# Import the `ManagedIdentityCredential` class from the `azure.identity` package.
from azure.identity import ManagedIdentityCredential
# Import the `configure_azure_monitor()` function from the `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor

# Configure OpenTelemetry to use Azure Monitor with a managed identity credential.
# This will allow OpenTelemetry to authenticate to Azure Monitor without requiring you to provide a connection string.
configure_azure_monitor(
    credential=ManagedIdentityCredential(),
)

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.

De manera predeterminada, AzureMonitorExporter 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 AzureMonitorExporterOptions.StorageDirectory.

// Create a new OpenTelemetry tracer provider and set the storage directory.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(options =>
    {
        // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
        // This is the directory where the OpenTelemetry SDK will store any trace data that cannot be sent to Azure Monitor immediately.
        options.StorageDirectory = "C:\\SomeDirectory";
    });

// Create a new OpenTelemetry meter provider and set the storage directory.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter(options =>
    {
        // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
        // This is the directory where the OpenTelemetry SDK will store any metric data that cannot be sent to Azure Monitor immediately.
        options.StorageDirectory = "C:\\SomeDirectory";
    });

// Create a new logger factory and add the OpenTelemetry logger provider with the storage directory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter(options =>
        {
            // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
            // This is the directory where the OpenTelemetry SDK will store any log data that cannot be sent to Azure Monitor immediately.
            options.StorageDirectory = "C:\\SomeDirectory";
        });
    });
});

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

De manera predeterminada, AzureMonitorExporter usa una de las siguientes ubicaciones para el almacenamiento sin conexión.

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

Para invalidar el directorio predeterminado, debe establecer storageDirectory.

Por ejemplo:

// Import the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions class from the @azure/monitor-opentelemetry package.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");

// Create a new AzureMonitorOpenTelemetryOptions object and set the azureMonitorExporterOptions property to an object with the following properties:
//
// * connectionString: The connection string for your Azure Monitor Application Insights resource.
// * storageDirectory: The directory where the Azure Monitor OpenTelemetry exporter will store telemetry data when it is offline.
// * disableOfflineStorage: A boolean value that specifies whether to disable offline storage.
const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString: "<Your Connection String>",
    storageDirectory: "C:\\SomeDirectory",
    disableOfflineStorage: false
  }
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

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

De manera predeterminada, los exportadores de Azure Monitor usan la siguiente ruta de acceso:

<tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>

Para invalidar el directorio predeterminado, debe establecer storage_directory en el directorio que desee.

Por ejemplo:

...
# Configure OpenTelemetry to use Azure Monitor with the specified connection string and storage directory.
# Replace `your-connection-string` with the connection string to your Azure Monitor Application Insights resource.
# Replace `C:\\SomeDirectory` with the directory where you want to store the telemetry data before it is sent to Azure Monitor.
configure_azure_monitor(
    connection_string="your-connection-string",
    storage_directory="C:\\SomeDirectory",
)
...

Para deshabilitar esta característica, debe establecer disable_offline_storage en True. Su valor predeterminado es False.

Por ejemplo:

...
# Configure OpenTelemetry to use Azure Monitor with the specified connection string and disable offline storage.
# Replace `your-connection-string` with the connection string to your Azure Monitor Application Insights resource.
configure_azure_monitor(
    connection_string="your-connection-string",
    disable_offline_storage=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.

Instale el paquete OpenTelemetry.Exporter.OpenTelemetryProtocol en el proyecto.
```
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
```

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();

Instale el paquete OpenTelemetry.Exporter.OpenTelemetryProtocol en el proyecto.
```
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
```

// Create a new OpenTelemetry tracer provider and add the Azure Monitor trace exporter and the OTLP trace exporter.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter()
    .AddOtlpExporter();

// Create a new OpenTelemetry meter provider and add the Azure Monitor metric exporter and the OTLP metric exporter.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter()
    .AddOtlpExporter();

Instale OpenTelemetry Collector Trace Exporter y otros paquetes de OpenTelemetry en el proyecto.

    npm install @opentelemetry/api
    npm install @opentelemetry/exporter-trace-otlp-http
    npm install @opentelemetry/sdk-trace-base
    npm install @opentelemetry/sdk-trace-node

// Import the useAzureMonitor function, the AzureMonitorOpenTelemetryOptions class, the trace module, the ProxyTracerProvider class, the BatchSpanProcessor class, the NodeTracerProvider class, and the OTLPTraceExporter class from the @azure/monitor-opentelemetry, @opentelemetry/api, @opentelemetry/sdk-trace-base, @opentelemetry/sdk-trace-node, and @opentelemetry/exporter-trace-otlp-http packages, respectively.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

// Create a new OTLPTraceExporter object.
const otlpExporter = new OTLPTraceExporter();

// Enable Azure Monitor integration.
const options: AzureMonitorOpenTelemetryOptions = {
    // Add the SpanEnrichingProcessor
    spanProcessors: [new BatchSpanProcessor(otlpExporter)] 
}
useAzureMonitor(options);

Instale el paquete opentelemetry-exporter-otlp.

# Import the `configure_azure_monitor()`, `trace`, `OTLPSpanExporter`, and `BatchSpanProcessor` classes from the appropriate packages.    
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Configure OpenTelemetry to use Azure Monitor with the specified connection string.
# Replace `<your-connection-string>` with the connection string to your Azure Monitor Application Insights resource.
configure_azure_monitor(
    connection_string="<your-connection-string>",
)

# Get the tracer for the current module.
tracer = trace.get_tracer(__name__) 

# Create an OTLP span exporter that sends spans to the specified endpoint.
# Replace `http://localhost:4317` with the endpoint of your OTLP collector.
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4317")

# Create a batch span processor that uses the OTLP span exporter.
span_processor = BatchSpanProcessor(otlp_exporter)

# Add the batch span processor to the tracer provider.
trace.get_tracer_provider().add_span_processor(span_processor)

# Start a new span with the name "test".
with tracer.start_as_current_span("test"):
    print("Hello world!")

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.

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.

Preguntas más frecuentes

Esta sección proporciona respuestas a preguntas comunes.

¿Qué es OpenTelemetry?

Es un nuevo estándar de código abierto dirigido a la observabilidad. Obtenga más información en OpenTelemetry.

¿Por qué Microsoft Azure Monitor invierte en OpenTelemetry?

Microsoft se encuentra entre los mayores colaboradores de OpenTelemetry.

Las principales propuestas de valor de OpenTelemetry son que es independiente del proveedor y que proporciona API y SDK coherentes entre lenguajes.

Con el tiempo, creemos que OpenTelemetry permitirá a los clientes de Azure Monitor observar las aplicaciones escritas en lenguajes más allá de los lenguajes admitidos. También expande los tipos de datos que puede recopilar a través de un amplio conjunto de bibliotecas de instrumentación. Además, los SDK de OpenTelemetry tienden a ser más eficaces a escala que sus predecesores, los SDK de Application Insights.

Por último, OpenTelemetry se alinea con la estrategia de Microsoft para adoptar el código abierto.

¿Cuál es el estado de OpenTelemetry?

Ver el Estado de OpenTelemetry.

¿Qué es la "Distribución de OpenTelemetry de Azure Monitor"?

Puede considerarlo como un contenedor fino que agrupa todos los componentes de OpenTelemetry para una experiencia de primera clase en Azure. Este contenedor también se denomina una distribución en OpenTelemetry.

¿Por qué debería usar la "Distribución de OpenTelemetry de Azure Monitor"?

El uso de la Distribución de OpenTelemetry de Azure Monitor tiene varias ventajas sobre la OpenTelemetry nativa de la comunidad:

Reduce el esfuerzo de habilitación
Compatible con Microsoft
Incorpora características específicas de Azure como:
- Muestreo compatible con SDK clásicos de Application Insights
- Autenticación de Microsoft Entra
- Almacenamiento sin conexión y reintentos automáticos
- Statsbeat
- Métricas estándar de Application Insights
- Detección de metadatos de recursos para rellenar automáticamente el Nombre del rol en la nube y la Instancia de rol en la nube en varios entornos de Azure
- Live Metrics

Siguiendo el espíritu de OpenTelemetry, diseñamos la distribución para que sea abierta y ampliable. Por ejemplo, puede agregar:

Un exportador de OpenTelemetry Protocol (OTLP) y enviar a un segundo destino simultáneamente
Otras bibliotecas de instrumentación no incluidas en la distribución

Dado que la distribución proporciona una distribución de OpenTelemetry, la distribución admite cualquier cosa compatible con OpenTelemetry. Por ejemplo, puede agregar más procesadores de telemetría, exportadores o bibliotecas de instrumentación, si OpenTelemetry los admite.

Nota:

La distribución establece el tomador de muestras en una toma personalizada de frecuencia fija para Application Insights. Puede cambiar esto a otro tomador de muestras, pero si lo hace, puede deshabilitar algunas de las funcionalidades incluidas de la distribución. Para más información sobre el tomador de muestras admitido, consulte la sección Habilitar muestreo de Configuración de OpenTelemetry de Azure Monitor.

En el caso de los lenguajes sin un exportador de OpenTelemetry independiente compatible, la distribución de OpenTelemetry de Azure Monitor es la única manera admitida actualmente para usar OpenTelemetry con Azure Monitor. En el caso de los idiomas con un exportador de OpenTelemetry independiente compatible, tiene la opción de usar la distribución de OpenTelemetry de Azure Monitor o el exportador de OpenTelemetry independiente adecuado en función del escenario de telemetría. Para más información, consulte ¿Cuándo debo usar el exportador de OpenTelemetry de Azure Monitor?.

¿Cómo puedo probar la Distribución de OpenTelemetry de Azure Monitor?

Consulte nuestros documentos de habilitación para .NET, Java, JavaScript (Node.js) y Python.

¿Debería usar OpenTelemetry o el SDK de Application Insights?

Se recomienda usar la distribución de OpenTelemetry, a menos que necesite una característica que solo esté disponible con soporte técnico formal en el SDK de Application Insights.

Adoptar OpenTelemetry ahora evita tener que migrar más adelante.

¿Cuándo debo usar el exportador OpenTelemetry de Azure Monitor?

Para ASP.NET Core, Java, Node.js y Python, se recomienda usar la distribución de OpenTelemetry de Azure Monitor. Es una línea de código para empezar.

Para todos los demás escenarios de .NET, como el ASP.NET clásico, las aplicaciones de consola, etc., se recomienda usar el exportador de OpenTelemetry de Azure Monitor de .NET: Azure.Monitor.OpenTelemetry.Exporter.

Para escenarios de telemetría de Python más complejos que requieren configuración avanzada, se recomienda usar el Exportador de OpenTelemetry de Azure Monitor de Python.

¿Cuál es el estado actual de las características de la Distribución de OpenTelemetry de Azure Monitor?

En el gráfico siguiente, se desglosa la compatibilidad de características de OpenTelemetry para cada lenguaje.

Característica	.NET	Node.js	Python	Java
Seguimiento distribuido	✅	✅	✅	✅
Métricas personalizadas	✅	✅	✅	✅
Métricas estándar (precisión afectada actualmente por el muestreo)	✅	✅	✅	✅
Muestreo de frecuencia fija	✅	✅	✅	✅
Almacenamiento sin conexión y reintentos automáticos	✅	✅	✅	✅
Informes de excepciones	✅	✅	✅	✅
Recopilación de registros	✅	⚠️	✅	✅
Eventos personalizados	⚠️	⚠️	⚠️	✅
Autenticación de Microsoft Entra	✅	✅	✅	✅
Live metrics	❌	❌	❌	✅
Detección del contexto de recursos para VM/VMSS y App Service	✅	❌	✅	✅
Detección del contexto de recursos para AKS y Functions	❌	❌	❌	✅
Filtrado de intervalos de pruebas de disponibilidad	❌	❌	❌	✅
Relleno automático del id. de usuario y el id. de usuario autenticado y la dirección IP del usuario	❌	❌	❌	✅
Invalidar o establecer manualmente el nombre de la operación, el id. de usuario o el id. de usuario autenticado	❌	❌	❌	✅
muestreo adaptable	❌	❌	❌	✅
Generador de perfiles	❌	❌	❌	⚠️
Depurador de instantáneas	❌	❌	❌	❌

Clave

✅ Esta característica está disponible para todos los clientes con soporte técnico formal.
⚠ Esta característica está disponible como versión preliminar pública. Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.
❌ Esta característica no está disponible o no es aplicable.

¿Se puede usar OpenTelemetry para exploradores web?

Sí, pero no se recomienda y Azure no lo admite. OpenTelemetry para Javascript está muy optimizado para Node.js. En su lugar, se recomienda usar el SDK de JavaScript para Application Insights.

¿Cuándo podemos esperar que el SDK de OpenTelemetry esté disponible para su uso en navegadores web?

El SDK web de OpenTelemetry no tiene una escala de tiempo de disponibilidad determinada. Es probable que falten varios años para que exista un SDK para navegadores que sea una alternativa viable al SDK de JavaScript Application Insights.

¿Puedo probar hoy OpenTelemetry en un explorador web?

El espacio aislado web de OpenTelemetry es una bifurcación diseñada para que OpenTelemetry funcione en un explorador. Todavía no es posible enviar telemetría a Application Insights. El SDK no define eventos de cliente generales.

¿Ejecuta Application Insights junto con agentes de la competencia como AppDynamics, DataDog y NewRelic compatibles?

No. Esta práctica no es algo que tengamos previsto probar o admitir, aunque nuestras distribuciones le permiten exportar a un punto de conexión OTLP junto con Azure Monitor simultáneamente.

¿Se pueden usar las características en vista previa (GB) en entornos de producción?

Esta opción no se recomienda. Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

¿Cuál es la diferencia entre la instrumentación manual y la automática?

Consulte la Introducción a OpenTelemetry.

¿Puedo usar OpenTelemetry-Collector?

Algunos clientes usan OpenTelemetry Collector como alternativa con agente, aunque Microsoft todavía no admite oficialmente un enfoque basado en agente para la supervisión de aplicaciones. Mientras tanto, la comunidad de código abierto contribuyó con un exportador de Azure Monitor de OpenTelemetry Collector que algunos clientes usan para enviar datos a Application Insights de Azure Monitor. Microsoft no admite esto.

¿Cuál es la diferencia entre OpenCensus y OpenTelemetry?

OpenCensus es el precursor de OpenTelemetry. Microsoft ayudó a juntar OpenTracing y OpenCensus para crear OpenTelemetry, un único estándar de observabilidad para el mundo. El SDK de Python recomendado para producción actual para Azure Monitor se basa en OpenCensus. Microsoft se ha comprometido a hacer que Azure Monitor se base en OpenTelemetry.

Solución de problemas

¿No funciona? Consulte la página de solución de problemas de ASP.NET Core.

Soporte técnico

Seleccione una pestaña para el idioma que prefiera para detectar las opciones de soporte técnico.

En caso de problemas de Soporte técnico de Azure, abra una incidencia de Soporte técnico de Azure.
En caso de problemas de OpenTelemetry, póngase en contacto con la comunidad de .NET de OpenTelemetry directamente.
Para obtener una lista de problemas abiertos relacionados con el exportador de Azure Monitor, consulte la página de problemas de GitHub.

Comentarios de OpenTelemetry

Para proporcionar comentarios:

Rellene la encuesta de comentarios de los clientes de la comunidad de OpenTelemetry.
Únase a la comunidad de usuarios pioneros de OpenTelemetry y cuente su experiencia a Microsoft.
Interactúe con otros usuarios de Azure Monitor en Microsoft Tech Community.
Realice una solicitud de característica en el foro de comentarios de Azure.

Configuración de OpenTelemetry de Azure Monitor

Cadena de conexión

Establecimiento del nombre y la instancia de rol en la nube

Habilitación del muestreo

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

Almacenamiento sin conexión y reintentos automáticos

Habilitación del exportador de OTLP

Configuración de OpenTelemetry

Preguntas más frecuentes

¿Qué es OpenTelemetry?

¿Por qué Microsoft Azure Monitor invierte en OpenTelemetry?

¿Cuál es el estado de OpenTelemetry?

¿Qué es la "Distribución de OpenTelemetry de Azure Monitor"?

¿Por qué debería usar la "Distribución de OpenTelemetry de Azure Monitor"?

¿Cómo puedo probar la Distribución de OpenTelemetry de Azure Monitor?

¿Debería usar OpenTelemetry o el SDK de Application Insights?

¿Cuándo debo usar el exportador OpenTelemetry de Azure Monitor?

¿Cuál es el estado actual de las características de la Distribución de OpenTelemetry de Azure Monitor?

¿Se puede usar OpenTelemetry para exploradores web?

¿Cuándo podemos esperar que el SDK de OpenTelemetry esté disponible para su uso en navegadores web?

¿Puedo probar hoy OpenTelemetry en un explorador web?

¿Ejecuta Application Insights junto con agentes de la competencia como AppDynamics, DataDog y NewRelic compatibles?

¿Se pueden usar las características en vista previa (GB) en entornos de producción?

¿Cuál es la diferencia entre la instrumentación manual y la automática?

¿Puedo usar OpenTelemetry-Collector?

¿Cuál es la diferencia entre OpenCensus y OpenTelemetry?

Solución de problemas

Soporte técnico

Comentarios de OpenTelemetry

Recursos adicionais