Activación de .NET Profiler

El generador de perfiles se incluye en las bibliotecas de rastreo de Datadog. Si ya estás utilizando APM para recopilar trazas (traces) para tu aplicación, puedes omitir la instalación de biblioteca e ir directamente a habilitar el generador de perfiles.

Requisitos

Para obtener un resumen de las versiones mínimas y recomendadas del tiempo de ejecución y del rastreador en todos los lenguajes, consulta Versiones de lenguaje y rastreadores compatibles.

Sistemas operativos compatibles con .NET Framework
Windows 10
Windows Server a partir de la versión 2012
Sistemas operativos compatibles con .NET Core y .NET 5+
Linux con glibc 2.17+ (por ejemplo, CentOS 7+) y basado en musl (Alpine)
Windows 10
Windows Server a partir de la versión 2012
Serverless
Azure App Server Windows y Linux: aplicaciones web solamente, las aplicaciones de función no son compatibles

Tiempos de ejecución .NET compatibles (aplicaciones de 64 bits) .NET Framework 4.6.1 o posterior
.NET Core 2.1, 3.1
.NET 5
.NET 6
.NET 7
.NET 8

Nota: Para los contenedores, se requiere al menos un núcleo. Consulta la documentación para Solucionar problemas para obtener más detalles.
Lenguajes compatibles
cualquier lenguaje dirigido al tiempo de ejecución de .NET, como C#, F# y Visual Basic.

Las siguientes funciones de generación de perfiles están disponibles en las siguientes versiones mínimas de la biblioteca dd-trace-dotnet:

FunciónVersión requerida de dd-trace-dotnetVersiones de tiempo de ejecución de .NET necesarias
Perfiles de tiempo real2.7.0+Todas las versiones de tiempo de ejecución compatibles.
Perfiles de CPU2.15.0+Todas las versiones de tiempo de ejecución compatibles.
Perfiles de excepciones2.31.0+Todas las versiones de tiempo de ejecución compatibles.
Perfiles de asignaciónFase beta, 2.18.0+.NET 6+
Perfil de contención de bloqueo2.49.0+.NET Framework de fase beta (requiere Datadog Agent 7.51+) y .NET 5+
Perfiles de heap en directoFase beta, 2.22.0+.NET 7+
Hotspots de código2.7.0+Todas las versiones de tiempo de ejecución compatibles.
Perfiles de endpoint2.15.0+Todas las versiones de tiempo de ejecución compatibles.
Cronología2.30.0+Todas las versiones de tiempo de ejecución compatibles (excepto .NET 5+, necesario para los detalles de la recopilación de elementos no usados).

Instalación

Asegúrate de que Datadog Agent v6+ está instalado y en funcionamiento. Datadog recomienda utilizar Datadog Agent v7+. El generador de perfiles se entrega junto con la biblioteca de rastreo (a partir de v2.8.0), por lo que si ya estás utilizando APM para recopilar trazas para tu aplicación, puedes omitir la instalación de la biblioteca e ir directamente a Activación del generador de perfiles.

En caso contrario, instala el generador de perfiles siguiendo los pasos que se indican a continuación, en función de tu sistema operativo.

Nota: La instrumentación automática de Datadog se basa en la API de perfiles de .NET CLR. Dado que esta API solo permite un suscriptor, ejecuta solo una solución de APM en tu entorno de aplicación.

Puedes instalar Datadog .NET Profiler en toda la máquina para que todos los servicios de la máquina puedan ser instrumentados, o puedes instalarlo por aplicación para permitir a los desarrolladores gestionar la instrumentación a través de las dependencias de la aplicación. Para ver las instrucciones de instalación en toda la máquina, haz clic en la pestaña Windows o Linux. Para ver las instrucciones de instalación por aplicación, haz clic en la pestaña NuGet.

    Para instalar .NET Profiler en toda la máquina:

    1. Descarga el paquete del rastreador .NET más reciente que sea compatible con tu sistema operativo y tu arquitectura.

    2. Ejecuta uno de los siguientes comandos para instalar el paquete y crear el directorio de logs /var/log/datadog/dotnet del rastreador .NET con los permisos apropiados:

      Debian o Ubuntu
      sudo dpkg -i ./datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb && sudo /opt/datadog/createLogPath.sh
      CentOS 7+ o Fedora
      sudo rpm -Uvh datadog-dotnet-apm<TRACER_VERSION>-1.x86_64.rpm && sudo /opt/datadog/createLogPath.sh
      Alpine u otras distribuciones basadas en musl
      sudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-musl.tar.gz && sudo sh /opt/datadog/createLogPath.sh
      Otras distribuciones
      sudo tar -C /opt/datadog -xzf datadog-dotnet-apm-<TRACER_VERSION>.tar.gz && sudo /opt/datadog/createLogPath.sh

    Para instalar .NET Profiler en toda la máquina:

    1. Instala o actualiza a la última versión, utilizando el instalador MSI de .NET Monitoring. Continuous Profiler admite Windows de 64 bits, por lo que necesitas el archivo como datadog-dotnet-apm-<VERSION>-x64.msi.

    2. Ejecuta el instalador con privilegios de administrador.

    Nota: Esta instalación no instrumenta aplicaciones que se ejecutan en IIS. En el caso de aplicaciones que se ejecutan en IIS, sigue el proceso de Windows para la instalación en toda la máquina.

    Para instalar el .NET Profiler por aplicación:

    1. Añade el paquete NuGet Datadog.Trace.Bundle a tu aplicación.
    Nota: Solo se admiten aplicaciones web. Las funciones no son compatibles.

    Para instalar el .NET Profiler por aplicación web:

    1. Instala la extensión APM de Azure App Service Datadog para Windows o utiliza la configuración de Linux para tu aplicación web.

    Habilitación del generador de perfiles

    Nota: Datadog no recomienda habilitar el generador de perfiles a nivel de máquina o para todas las aplicaciones IIS. Si lo has habilitado a nivel de máquina, consulta la documentación para solucionar problemas para obtener información sobre cómo reducir la sobrecarga asociada a la habilitación del generador de perfiles para todas las aplicaciones del sistema.

      1. Configura las siguientes variables de entorno, obligatorias para la instrumentación automática, a fin de adjuntarlas a tu aplicación:

        CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
DD_DOTNET_TRACER_HOME=/opt/datadog
LD_PRELOAD=/opt/datadog/continuousprofiler/Datadog.Linux.ApiWrapper.x64.so
DD_PROFILING_ENABLED=1
DD_ENV=production
DD_VERSION=1.2.3

      2. En el caso de aplicaciones independientes, reinicia la aplicación manualmente como lo harías normalmente.

      3. Uno o dos minutos después de iniciar tu aplicación, tus perfiles aparecerán en la página Datadog APM > Generador de perfiles.

      1. Con la instrumentación de un solo paso, establece las siguientes variables de entorno requeridas para que la instrumentación automática se adjunte a tu aplicación:

        LD_PRELOAD=/opt/datadog/apm/library/dotnet/continuousprofiler/Datadog.Linux.ApiWrapper.x64.so
DD_PROFILING_ENABLED=1
DD_ENV=production
DD_VERSION=1.2.3

      2. En el caso de aplicaciones independientes, reinicia la aplicación manualmente como lo harías normalmente.

      3. Uno o dos minutos después de iniciar tu aplicación, tus perfiles aparecerán en la página Datadog APM > Generador de perfiles.

      1. Establece las variables de entorno necesarias en configurar y activar el generador de perfiles. Para habilitar el generador de perfiles para aplicaciones IIS, es necesario establecer la variable de entorno DD_PROFILING_ENABLED en el registro bajo los nodos HKLM\System\CurrentControlSet\Services\WAS y HKLM\System\CurrentControlSet\Services\W3SVC.

        A partir de la versión 2.14.0, no es necesario configurar CORECLR_PROFILER o COR_PROFILER si has instalado el rastreador mediante el MSI.

        Con el editor de registro:

        En el editor de registro, modifica el valor de cadena múltiple llamado Environment en los nodos HKLM\System\CurrentControlSet\Services\WAS y HKLM\System\CurrentControlSet\Services\W3SVC y establece los datos de valor como sigue:

        Para .NET Core y .NET 5+:

        CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
DD_PROFILING_ENABLED=1
DD_ENV=production
DD_VERSION=1.2.3
        Uso del Editor de registro para crear variables de entorno para una aplicación .NET Core en IIS

        Para .NET Framework:

        COR_ENABLE_PROFILING=1
COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
DD_PROFILING_ENABLED=1
DD_ENV=production
DD_VERSION=1.2.3
        Uso del Editor de registro para crear variables de entorno para una aplicación .NET Framework en IIS

        Nota: Las variables de entorno se aplican para todas las aplicaciones IIS. A partir de IIS 10, puedes establecer variables de entorno para cada aplicación IIS en el archivoC:\Windows\System32\inetsrv\config\applicationhost.config. Consulta la documentación de Microsoft para más detalles.

      2. Detiene e inicia completamente IIS ejecutando los siguientes comandos como administrador:

        net stop /y was
net start w3svc
        Note: Use stop and start commands. A reset or restart does not always work.

      3. Uno o dos minutos después de iniciar tu aplicación, tus perfiles aparecerán en la página Datadog APM > Generador de perfiles.

      1. Establece las variables de entorno necesarias para configurar y habilitar el generador de perfiles. Para habilitar el generador de perfiles para tu servicio, es necesario establecer la variable de entorno DD_PROFILING_ENABLED en la clave de Registro asociada al servicio. Si el generador de perfiles se ejecuta solo (el rastreador está desactivado), puedes añadir opcionalmente las variables de entorno DD_SERVICE, DD_ENV y DD_VERSION.

        A partir de la versión 2.14.0, no es necesario configurar CORECLR_PROFILER o COR_PROFILER si has instalado el rastreador mediante el MSI.

        Con el editor de registro:

        En el Editor de registro, crea un valor de cadena múltiple llamado Environment en la clave HKLM\System\CurrentControlSet\Services\MyService y configura los datos de valor como:

        Para .NET Core y .NET 5+:

        CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
DD_PROFILING_ENABLED=1
DD_SERVICE=MyService
DD_ENV=production
DD_VERSION=1.2.3
        Uso del Editor de registro para crear variables de entorno para un servicio de Windows

        Para .NET Framework:

        COR_ENABLE_PROFILING=1
COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
DD_PROFILING_ENABLED=1
DD_SERVICE=MyService
DD_ENV=production
DD_VERSION=1.2.3
        Uso del Editor de registro para crear variables de entorno para un servicio de Windows

        Con un script PowerShell:

        Para .NET Core y .NET 5+:

        [string[]] $v = @(
    "CORECLR_ENABLE_PROFILING=1",
    "CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}",
    "DD_PROFILING_ENABLED=1",
    "DD_SERVICE=MyService",
    "DD_ENV=production",
    "DD_VERSION=1.2.3"
)
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\MyService -Name Environment -Value $v

        Para .NET Framework:

        [string[]] $v = @(
    "COR_ENABLE_PROFILING=1",
    "COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}",
    "DD_PROFILING_ENABLED=1",
    "DD_SERVICE=MyService",
    "DD_ENV=production",
    "DD_VERSION=1.2.3"
)
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\MyService -Name Environment -Value $v

      2. Uno o dos minutos después de iniciar tu aplicación, tus perfiles aparecerán en la página Datadog APM > Generador de perfiles.

      A partir de la versión 2.14.0, no es necesario configurar CORECLR_PROFILER o COR_PROFILER si has instalado el rastreador mediante el MSI.

      1. Establece las variables de entorno necesarias para configurar y habilitar el generador de perfiles para una aplicación que no sea un servicio, como consola, ASP.NET (Core), Windows Forms o WPF. Para habilitar el generador de perfiles para aplicaciones independientes, es necesario establecer la variable de entorno DD_PROFILING_ENABLED. Si el generador de perfiles se ejecuta solo (el rastreador está desactivado), puedes establecer opcionalmente las variables de entorno DD_SERVICE, DD_ENV y DD_VERSION. El método recomendado consiste en crear un archivo por lotes que las establezca e inicie la aplicación, y ejecutar la aplicación utilizando el archivo por lotes.

        Para .NET Core y .NET 5+:

        SET CORECLR_ENABLE_PROFILING=1
SET CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
SET DD_PROFILING_ENABLED=1
SET DD_SERVICE=MyService
SET DD_ENV=production
SET DD_VERSION=1.2.3

REM start the application here

        Para .NET Framework:

        SET COR_ENABLE_PROFILING=1
SET COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
SET DD_PROFILING_ENABLED=1
SET DD_SERVICE=MyService
SET DD_ENV=production
SET DD_VERSION=1.2.3

REM start the application here

      2. Uno o dos minutos después de iniciar tu aplicación, tus perfiles aparecerán en la página Datadog APM > Generador de perfiles.

      1. Establece las siguientes variables de entorno necesarias para que la generación de perfiles se adjunte a tu aplicación:

        CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
CORECLR_PROFILER_PATH=<System-dependent path>
DD_PROFILING_ENABLED=1
LD_PRELOAD=<System-dependent path>
DD_SERVICE=MyService
DD_ENV=production
DD_VERSION=1.2.3
DD_DOTNET_TRACER_HOME=<APP_DIRECTORY>/datadog

        El valor para el parámetro <APP_DIRECTORY> es la ruta al directorio que contiene los archivos .dll de la aplicación. El valor de la variable de entorno CORECLR_PROFILER_PATH varía en función del sistema en el que se ejecute la aplicación:

        Sistema operativo y arquitectura de procesoValor CORECLR_PROFILER_PATHValor LD_PRELOAD
        Alpine Linux x64<APP_DIRECTORY>/datadog/linux-musl-x64/Datadog.Trace.ClrProfiler.Native.so<APP_DIRECTORY>/datadog/linux-musl-x64/Datadog.Linux.ApiWrapper.x64.so
        Linux x64<APP_DIRECTORY>/datadog/linux-x64/Datadog.Trace.ClrProfiler.Native.so<APP_DIRECTORY>/datadog/linux-x64/Datadog.Linux.ApiWrapper.x64.so
        Linux ARM64<APP_DIRECTORY>/datadog/linux-arm64/Datadog.Trace.ClrProfiler.Native.so<APP_DIRECTORY>/datadog/linux-arm64/Datadog.Linux.ApiWrapper.x64.so
        Windows x64<APP_DIRECTORY>\datadog\win-x64\Datadog.Trace.ClrProfiler.Native.dllN/A
        Windows x86<APP_DIRECTORY>\datadog\win-x86\Datadog.Trace.ClrProfiler.Native.dllN/A

      2. Para las imágenes de Docker que se ejecutan en Linux, configura la imagen para ejecutar el script createLogPath.sh:

        RUN /<APP_DIRECTORY>/datadog/createLogPath.sh

        Los ejemplos de Docker están disponibles en el repositorio dd-trace-dotnet.

      3. Para aplicaciones independientes, reinicia manualmente la aplicación.

      1. Sigue estas directrices de instalación (Windows o Linux) para configurar DD_PROFILING_ENABLED:true y habilitar el generador de perfiles.

      Configuración

      Puede configurar el generador de perfiles utilizando las siguientes variables de entorno. Ten en cuenta que la mayoría de estos ajustes también se aplican a la configuración del rastreador. Reinicia la aplicación después de cambiar cualquiera de estos ajustes.

      Variable de entornoTipoDescripción
      DD_ENVCadenaEl nombre de entorno, por ejemplo, production. Si no se establece, será unspecified-environment
      DD_SERVICECadenaEl nombre de servicio, por ejemplo, web-backend. Si no se especifica, .NET Profiler intenta determinar el nombre de servicio automáticamente a partir del nombre de la aplicación (ensamblado de entrada de proceso o nombre de proceso).
      DD_VERSIONCadenaLa versión de tu servicio. Si no se establece, será unspecified-version
      DD_TAGSCadenaLas etiquetas para aplicar a un perfil cargado. Debe ser un lista de <key>:<value> separados por comas como: layer:api,team:intake.
      DD_AGENT_HOSTCadenaEstablece el host al que se envían los perfiles (el host que ejecuta el Agent). Puede ser un nombre de host o una dirección IP. Se ignora si DD_TRACE_AGENT_URL está configurado. Por defecto es localhost.
      DD_TRACE_AGENT_PORTCadenaEstablece el puerto al que se envían los perfiles (el puerto en el que el Agent escucha conexiones). Se ignora si DD_TRACE_AGENT_URL está configurado. Por defecto es8126.
      DD_TRACE_AGENT_URLCadenaEstablece el endpoint de la URL donde se envían los perfiles. Sustituye a DD_AGENT_HOST y DD_TRACE_AGENT_PORT si están definidos. Por defecto es http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>.
      DD_TRACE_DEBUGBooleanoActiva o desactiva el registro de depuración (podría ayudar en caso de investigación para solucionar problemas). Los valores válidos son: true o false. Por defecto es false.
      DD_PROFILING_LOG_DIRCadenaEstablece el directorio para logs de .NET Profiler. Por defecto es %ProgramData%\Datadog .NET Tracer\logs\. (Antes de v2.24, el directorio por defecto era %ProgramData%\Datadog-APM\logs\)
      DD_PROFILING_ENABLEDBooleanoSi se establece en true, activa el .NET Profiler. Por defecto es false.
      DD_PROFILING_WALLTIME_ENABLEDBooleanoSi se establece en false, desactiva la generación de perfiles de tiempo real. Por defecto es true.
      DD_PROFILING_CPU_ENABLEDBooleanoSi se establece en false, desactiva la generación de perfiles de CPU. Por defecto es true.
      DD_PROFILING_EXCEPTION_ENABLEDBooleanoSi se establece en true, activa la generación de perfiles de excepciones (fase beta). Por defecto es false.
      DD_PROFILING_ALLOCATION_ENABLEDBooleanoSi se establece en true, activa el perfil de asignaciones (fase beta). Por defecto es false.
      DD_PROFILING_LOCK_ENABLEDBooleanoSi se establece en true, habilita el perfil de contención de bloqueo (fase beta). Por defecto es false.
      DD_PROFILING_HEAP_ENABLEDBooleanoSi se establece en true, habilita el perfil de heap en directo (fase beta). Por defecto es false.
      DD_PROFILING_GC_ENABLEDBooleanoSi se establece en false, se desactiva el perfil de recopilación de elementos no usados utilizado en la interfaz de usuario de Cronología. Por defecto es true.
      Note: Para las aplicaciones IIS, debes establecer las variables de entorno en el registro (en nodos HKLM\System\CurrentControlSet\Services\WAS y HKLM\System\CurrentControlSet\Services\W3SVC) como se muestra en la pestaña Windows Service anterior. Las variables de entorno se aplican a todas las aplicaciones de IIS. Desde IIS 10, puedes establecer variables de entorno para cada aplicación IIS en el archivo C:\Windows\System32\inetsrv\config\applicationhost.config. Consulta la documentación de Microsoft para obtener más detalles.

      Referencias adicionales

      La guía Empezando con el generador de perfiles toma un ejemplo de servicio con un problema de rendimiento y te muestra cómo utilizar Continuous Profiler para comprender y solucionar el problema.

      Más enlaces, artículos y documentación útiles:

      Empezando con el generador de perfilesDOCUMENTACIÓN more more Más información sobre las visualizaciones de perfiles disponiblesDOCUMENTACIÓN more more Solucionar los problemas que surjan al utilizar el generador de perfilesDOCUMENTACIÓN more more Optimiza el rendimiento de tu apliación .NET con el Datadog Continuous ProfilerBLOG more more
      PREVIEWING: safchain/fix-custom-agent