Resolución de problemas de la instrumentación automática en .NET

Pasos generales

Si encuentras algún problema con OpenTelemetry .NET Automatic Instrumentation, hay varios pasos que pueden ayudarte a entenderlo.

Habilitar el registro detallado

Los registros de depuración detallados pueden ayudarte a solucionar problemas de instrumentación y puedes adjuntarlos a las incidencias de este proyecto para facilitar la investigación.

Para obtener los registros detallados de OpenTelemetry .NET Automatic Instrumentation, establece la variable de entorno OTEL_LOG_LEVEL en debug antes de que se inicie el proceso instrumentado.

De forma predeterminada, la librería escribe los archivos de registro en ubicaciones predefinidas. Si es necesario, cambia la ubicación predeterminada actualizando la variable de entorno OTEL_DOTNET_AUTO_LOG_DIRECTORY.

Después de obtener los registros, elimina la variable de entorno OTEL_LOG_LEVEL o cambia su valor a un nivel menos detallado para evitar una sobrecarga innecesaria.

Habilitar el seguimiento del host

El seguimiento del host puede utilizarse para recopilar la información necesaria para investigar problemas relacionados con diversos casos, como ensamblados que no se encuentran. Establece las siguientes variables de entorno:

COREHOST_TRACE=1
COREHOST_TRACEFILE=corehost_verbose_tracing.log

A continuación, reinicia la aplicación para recopilar los registros.

Problemas comunes

No se genera telemetría

No se genera telemetría. No hay registros en la ubicación de los registros internos de OpenTelemetry .NET Automatic Instrumentation.

Puede ocurrir que .NET Profiler no pueda conectarse y, por tanto, no se emitan registros.

La razón más común es que la aplicación instrumentada no tiene permisos para cargar los ensamblados de OpenTelemetry .NET Automatic Instrumentation.

No se pudo instalar el paquete ‘OpenTelemetry.AutoInstrumentation.Runtime.Native’

Al añadir los paquetes NuGet al proyecto, aparece un mensaje de error similar a este:

Could not install package 'OpenTelemetry.AutoInstrumentation.Runtime.Native 1.6.0'. You are trying to install this package into a project that targets '.NETFramework,Version=v4.7.2', but the package does not contain any assembly references or content files that are compatible with that framework. For more information, contact the package author.

Los paquetes NuGet no admiten proyectos csproj de estilo antiguo. Implementa la instrumentación automática en la máquina en lugar de utilizar paquetes NuGet o migra el proyecto al estilo SDK csproj.

Problemas de rendimiento

Si se produce un uso elevado de CPU, asegúrate de no haber habilitado la instrumentación automática de forma global mediante el establecimiento de las variables de entorno en el ámbito del sistema o del usuario.

Si el uso del ámbito del sistema o del usuario es intencionado, utiliza las variables de entorno OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES para excluir aplicaciones de la instrumentación automática.

La herramienta CLI dotnet se bloquea

Al ejecutar una aplicación, por ejemplo con dotnet run, aparecen mensajes de error similares al siguiente:

PS C:\Users\Administrator\Desktop\OTelConsole-NET6.0> dotnet run My.Simple.Console
Unhandled exception. System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation.
---> System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation.
---> System.TypeInitializationException: The type initializer for 'OpenTelemetry.AutoInstrumentation.Loader.Startup' threw an exception.
---> System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation.
---> System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Extensions.Configuration.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified.

Con la versión v0.6.0-beta.1 e inferiores, se producían problemas al instrumentar la herramienta CLI dotnet.

Por lo tanto, si utilizas una de estas versiones, te recomendamos ejecutar dotnet build antes de instrumentar la sesión de terminal o llamarlo en una sesión de terminal independiente.

Consulta #1744 para obtener más información.

Conflictos de versiones de ensamblados

Mensaje de error similar al siguiente:

Unhandled exception. System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified.

File name: 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'
   at Microsoft.AspNetCore.Builder.WebApplicationBuilder..ctor(WebApplicationOptions options, Action`1 configureDefaults)
   at Microsoft.AspNetCore.Builder.WebApplication.CreateBuilder(String[] args)
   at Program.<Main>$(String[] args) in /Blog.Core/Blog.Core.Api/Program.cs:line 26

Los paquetes NuGet de OpenTelemetry .NET y sus dependencias se implementan con OpenTelemetry .NET Automatic Instrumentation.

Para gestionar los conflictos entre versiones de dependencias, actualiza las referencias del proyecto de la aplicación instrumentada para que utilicen las mismas versiones que OpenTelemetry .NET Automatic Instrumentation.

Una forma sencilla de asegurarte de que no se produzcan estos conflictos es añadir el paquete OpenTelemetry.AutoInstrumentation a la aplicación. Para obtener instrucciones sobre cómo añadirlo a la aplicación, consulta Uso de los paquetes NuGet de OpenTelemetry.AutoInstrumentation.

Como alternativa, añade únicamente los paquetes en conflicto al proyecto. Las siguientes dependencias son utilizadas por OpenTelemetry .NET Automatic Instrumentation:

Busca sus versiones en las siguientes ubicaciones:

De forma predeterminada, las referencias a ensamblados de las aplicaciones de .NET Framework se redirigen durante el tiempo de ejecución a las versiones utilizadas por la instrumentación automática. Este comportamiento se puede controlar mediante la configuración OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED.

Si la aplicación ya incluye redirecciones de versiones de ensamblado utilizados por la instrumentación automática, esta redirección automática puede fallar; consulta #2833. Comprueba si alguna redirección de ensamblado existente impide la redirección a las versiones enumeradas en netfx_assembly_redirection.h.

Para que funcione la redirección automática anterior, hay dos situaciones específicas que requieren que los ensamblados utilizados para instrumentar aplicaciones de .NET Framework —los que se encuentran en la carpeta netfx del directorio de instalación— también se instalen en la Global Assembly Cache (GAC):

  1. Instrumentación mediante técnicas de monkey patching de ensamblados cargados como independientes del dominio.
  2. Redirección de ensamblados para aplicaciones firmadas con nombre seguro (strong-named) si la aplicación también incluye versiones diferentes de algunos ensamblados que se distribuyen en la carpeta netfx.

Si tienes problemas en una de las situaciones anteriores, vuelve a ejecutar el comando Install-OpenTelemetryCore desde el módulo de instalación de PowerShell para asegurarte de que las instalaciones necesarias en la GAC estén actualizadas.

Para obtener más información sobre el uso de la GAC por parte de la instrumentación automática, consulta el comentario de pjanotti.

Consulta #2269 y #2296 para obtener más información.

No se encontró un ensamblado en AdditionalDeps

Síntomas

Aparece un mensaje de error similar al siguiente:

An assembly specified in the application dependencies manifest (OpenTelemetry.AutoInstrumentation.AdditionalDeps.deps.json) was not found

Esto podría estar relacionado con los siguientes problemas:

Otros problemas

Si encuentras un problema que no aparece en esta página, consulta los Pasos generales para recopilar información de diagnóstico adicional. Esto puede ayudar a facilitar su resolución.


Última modificación September 17, 2026: ES translate zero-code/zero-code/dotnet/troubleshooting.md (#11663) (34b5d040)