Instrumentación sin código para .NET

Usa la instrumentación automática de OpenTelemetry .NET para enviar trazas y métricas desde aplicaciones y servicios .NET a backends de observabilidad sin tener que modificar su código fuente.

Para aprender a instrumentar el código de su servicio o aplicación, lee el Manual de instrumentación.

Compatibilidad

La instrumentación automática de OpenTelemetry .NET debería funcionar con todos los sistemas operativos y versiones oficialmente compatibles de .NET).

La versión mínima compatible de .NET Framework es 4.6.2.

Las arquitecturas de procesador compatibles son:

• x86
• AMD64 (x86-64)
• ARM64 (Experimental)

Pruebas de integración continua (CI) en los siguientes sistemas operativos:

• Alpine x64
• Alpine ARM64
• Debian x64
• Debian ARM64
• CentOS Stream 9 x64
• macOS Ventura 13 x64
• Microsoft Windows Server 2022 x64
• Microsoft Windows Server 2025 x64
• Ubuntu 22.04 LTS x64
• Ubuntu 22.04 LTS ARM64

Configuración

Para instrumentar una aplicación .NET automáticamente, descargue y ejecute el script de instalación para su sistema operativo.

Linux y macOS

Descarga y ejecuta el script .sh:

# Descargar el script de bash
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O

# Instalar archivos principales
sh ./otel-dotnet-auto-install.sh

# Habilitar la ejecución del script de instrumentación
chmod +x $HOME/.otel-dotnet-auto/instrument.sh

# Configurar la instrumentación para la sesión de shell actual
. $HOME/.otel-dotnet-auto/instrument.sh

# Ejecute su aplicación con instrumentación
OTEL_SERVICE_NAME=myapp OTEL_RESOURCE_ATTRIBUTES=deployment.environment=staging,service.version=1.0.0 ./MyNetApp

brew install coreutils

Windows (PowerShell)

En Windows, usa el módulo PowerShell como administrador.

# PowerShell 5.1 es requerido
#Requires -PSEdition Desktop

# Descargar el módulo
$module_url = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path -UseBasicParsing

# Importar el módulo para utilizar sus funciones
Import-Module $download_path

# Instalar archivos principales (online vs offline)
Install-OpenTelemetryCore
Install-OpenTelemetryCore -LocalPath "C:\Path\To\OpenTelemetry.zip"

# Configurar la instrumentación para la sesión actual de PowerShell
Register-OpenTelemetryForCurrentSession -OTelServiceName "MyServiceDisplayName"

# Ejecute su aplicación con instrumentación
.\MyNetApp.exe

# Puede obtener información sobre su uso ejecutando los siguientes comandos

# Listar todos los comandos disponibles
Get-Command -Module OpenTelemetry.DotNet.Auto

# Obtener información de uso del comando
Get-Help Install-OpenTelemetryCore -Detailed

Instrumentar un servicio de Windows que ejecuta una aplicación .NET

Usa el módulo de PowerShell OpenTelemetry.DotNet.Auto.psm1 para configurar la instrumentación automática de un servicio de Windows:

# Importar el módulo
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Instalar archivos principales
Install-OpenTelemetryCore

# Configurar la instrumentación del servicio de Windows
Register-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName" -OTelServiceName "MyServiceDisplayName"

Configuración para el servicio de Windows

Para las aplicaciones .NET Framework puedes configurar las configuraciones más comunes de OTEL_ (como OTEL_RESOURCE_ATTRIBUTES) via appSettings en App.config.

La alternativa es establecer variables de entorno para el servicio de Windows en el Registro de Windows.

La clave de registro de un servicio de Windows determinado (llamado $svcName) se encuentra en:

HKLM\SYSTEM\CurrentControlSet\Services\$svcName

Las variables de entorno se definen en un REG_MULTI_SZ (valor de registro multilínea) llamado Environment en el siguiente formato:

Var1=Value1
Var2=Value2

Instrumentar una aplicación ASP.NET desarollada en IIS

Usa el módulo de PowerShell OpenTelemetry.DotNet.Auto.psm1 para configurar la instrumentación automática para IIS:

# Importar el módulo
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Instalar archivos principales
Install-OpenTelemetryCore

# Configurar la instrumentación de IIS
Register-OpenTelemetryForIIS

Configuración para aplicaciones ASP.NET

Para las aplicaciones ASP.NET, puede configurar las configuraciones OTEL_ más comunes (como OTEL_SERVICE_NAME) a través de appSettings en Web.config.

Si no se configura explícitamente un nombre de servicio, se generará uno para usted. Si la aplicación está alojada en IIS en el Framework de .NET, se usará SiteName\VirtualDirectoryPath, por ejemplo: MySite\MyApp.

Para las aplicaciones ASP.NET Core, puede usar los elementos <environmentVariable> dentro del bloque <aspNetCore> del archivo Web.config para establecer la configuración mediante variables de entorno.

Configuración avanzada

Puede agregar las <environmentVariables> en applicationHost.config para establecer variables de entorno para grupos de aplicaciones determinados.

Considere establecer variables de entorno comunes para todas las aplicaciones implementadas en IIS configurando las variables de entorno para los servicios de Windows W3SVC y WAS.

Paquete NuGet

Puede instrumentar aplicaciones self-contained mediante los paquetes NuGet. Consulte Paquetes NuGet para obtener más información.

Instrumentar un contenedor

Para ver un ejemplo de instrumentación de contenedores Docker, consulte el ejemplo en GitHub.

También puedes usar el Operador OpenTelemetry para Kubernetes.

Configurando el agente

Para ver la todas las opciones de configuración, consulte Configuración y ajustes.

Correlación de registro a traza

El SDK de OpenTelemetry .NET correlaciona automáticamente los registros con los datos de traza. Cuando se emiten registros en el contexto de una traza activo, los campos de contexto de traza filed TraceId, SpanId y TraceState son completados automáticamente.

Los siguientes son registros producidos por la aplicación de consola de muestra:

"logRecords": [
    {
        "timeUnixNano": "1679392614538226700",
        "severityNumber": 9,
        "severityText": "Information",
        "body": {
            "stringValue": "Success! Today is: {Date:MMMM dd, yyyy}"
        },
        "flags": 1,
        "traceId": "21df288eada1ce4ace6c40f39a6d7ce1",
        "spanId": "a80119e5a05fed5a"
    }
]

Para obtener más información, consulte:

• SDK de OpenTelemetry .NET
• Especificación de OpenTelemetry

Especificación de OpenTelemetry

La instrumentación automática de OpenTelemetry .NET admite una amplia variedad de librerías. Para obtener una lista completa, consulte Instrumentaciones.

Solución de problemas

Para ver la telemetría de su aplicación directamente en la salida estándar, agregue console al siguiente valor de la variable de entorno antes de iniciar su aplicación:

• OTEL_TRACES_EXPORTER
• OTEL_METRICS_EXPORTER
• OTEL_LOGS_EXPORTER

Para conocer los pasos generales de resolución de problemas y soluciones a problemas específicos, consulte Solución de problemas.

Próximos pasos

Una vez configurada la instrumentación automática para su aplicación o servicio, es posible que desee enviar trazas y métricas personalizados o agregar instrumentación manual para recopilar datos de telemetría personalizados.

Desinstalar

Linux y macOS

En Linux y macOS, los pasos de instalación solo afectan a la sesión de shell actual, por lo que no se requiere una desinstalación explícita.

Windows (PowerShell)

En Windows, usa el módulo PowerShell como administrador.

# PowerShell 5.1 es requerido
# Requiere PSEdition Desktop

# Importar el módulo previamente instalado
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Si IIS ya estaba registrado, puedes cancelar el registro con
Unregister-OpenTelemetryForIIS

# Si los servicios de Windows se registraron previamente, cancele su registro
Unregister-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName"

# Por último, desinstale la instrumentación OpenTelemetry
Uninstall-OpenTelemetryCore