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 de .NET compatibles (aplicaciones de 64 bits) .NET Framework 4.6.1 o superior
.NET Core 2.1, 3.1
.NET 5
.NET 6
.NET 7
.NET 8
.NET 9
.NET 10

Nota: Para los contenedores, se necesita más de un núcleo. Lee la documentación de Solución de 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.
Consumo de CPU para la recopilación de elementos no usados3.19.0+.NET 5+
Perfiles de excepciones2.31.0+Todas las versiones de tiempo de ejecución compatibles.
Perfiles de asignación3.12.0+ / 3.28.0+.NET Framework (requiere Datadog Agent 7.51+ y 3.12.0+) / .NET 6+ (requiere 2.18.0+ pero Datadog recomienda .NET10 con 3.28+).
Perfil de contención de bloqueo2.49.0+.NET Framework (requiere Datadog Agent 7.51+) y .NET 5+
Perfiles de heap en directo3.28.0+.NET 7+ pero Datadog recomienda .NET 10+.
Traza para la Integración de perfiles2.30.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+ (y 3.19.0+ para solicitudes HTTP salientes de más de 50 ms en beta y eventos de inicio/fin de subproceso)Todas las versiones de tiempo de ejecución compatibles (excepto .NET 5+, necesaria para los detalles de la recopilación de elementos no usados, y .NET 7+, necesario para las solicitudes HTTP salientes).
Investigación de fugas de memoria3.33.0+.NET 6+ (en vista previa)
  • La creación de perfiles de asignaciones y retención de bloqueos para .NET Framework requiere que el Datadog Agent y las aplicaciones perfiladas se ejecuten en el mismo equipo.
  • Debido a una limitación de .NET Framework, el perfil de asignaciones no muestra el tamaño de las asignaciones. En su lugar, solo muestra el recuento.
  • Las asignaciones y la creación de perfiles en Live Heap están disponibles en .NET 10. Para otras versiones anteriores de .NET, la distribución estadística del muestreo de asignaciones podría no ser exacta, por lo que cabe esperar que los objetos más grandes se representen con mayor frecuencia.
  • Continuous Profiler no es compatible con AWS Lambda.
  • Continuous Profiler no es compatible con ARM64.
Nota: A diferencia de APM, Continuous Profiler no se activa por defecto cuando se instala el paquete de APM. Debes activarlo explícitamente para las aplicaciones que desees perfilar.

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.

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

Puedes instalar el generador de perfiles de Datadog .NET 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.

    1. Con la instrumentación de APM en un solo paso, no hay nada más que instalar. Ve a Activar el generador de perfiles para ver cómo activar el generador de perfiles para una aplicación.
    Nota: Si APM ya estaba instalado manualmente, debe desinstalarlo eliminando las siguientes variables de entorno:
    - CORECLR_ENABLE_PROFILING
    - CORECLR_PROFILER
    - CORECLR_PROFILER_PATH
    - El valor que apunta a Datadog. Linux.ApiWrapper.x64.so en LD_PRELOAD

    Por ejemplo, si está configurando estas variables de entorno en su dockerfile para un servicio, debería eliminarlas para evitar conflictos con Single step (UI) / paso (generic) Instrumentation. Si estas variables de entorno aún están configuradas, se utilizará de forma silenciosa la versión correspondiente instalada anteriormente en lugar de la instalada con Single step (UI) / paso (generic) Instrumentation.

    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 sirve para instrumentar las aplicaciones que se ejecutan en IIS (Internet Information Services). Para las aplicaciones que se ejecutan en IIS (Internet Information Services), sigue el proceso de instalación en toda la máquina de Windows.

    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.

    Activación del generador de perfiles

    Nota: Datadog no recomienda habilitar el generador de perfiles a nivel de máquina o para todas las aplicaciones de IIS (Internet Information Services). Si lo has habilitado en toda la máquina, lee la documentación de Solución de problemas para obtener más información sobre la reducción de la sobrecarga asociada con la activación del generador de perfiles para todas las aplicaciones de sistema.

      1. Con la instrumentación de APM en un solo paso, solo debe configurarse DD_PROFILING_ENABLED para activar el generador de perfiles para una aplicación.

        DD_PROFILING_ENABLED=1

# other optional environment variables
DD_ENV=production
DD_VERSION=1.2.3

        Estos son los valores admitidos para la variable de entorno DD_PROFILING_ENABLED:

        ValueDescripción
        1 o trueActivar el generador de perfiles.
        AutoActiva el generador de perfiles si y solo si (1) se ha creado una traza y (2) la aplicación dura más de 30 segundos.
        0 o falseDesactivar el generador de perfiles.
        Note: The Auto value is aimed to avoid short lived processes without any trace. This feature is in Preview.

      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

# other optional environment variables
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. Opcional: Configura la integración de código fuente para conectar tus datos de generación de perfiles con tus repositorios Git.

      4. Un par de minutos después de iniciar la aplicación, los perfiles aparecerán en la página Datadog APM > Generador de perfiles. Si no es así, consulta la guía Solución de problemas.

      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

# other optional environment variables
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

# other optional environment variables
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. Opcional: Configura la integración de código fuente para conectar tus datos de generación de perfiles con tus repositorios Git.

      4. Un par de minutos después de iniciar la aplicación, los perfiles aparecerán en la página Datadog APM > Generador de perfiles. Si no es así, consulta la guía Solución de problemas.

      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

# other optional environment variables
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

# other optional environment variables
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. Opcional: Configura la integración de código fuente para conectar tus datos de generación de perfiles con tus repositorios Git.

      3. Un par de minutos después de iniciar la aplicación, los perfiles aparecerán en la página Datadog APM > Generador de perfiles. Si no es así, consulta la guía Solución de problemas.

      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

REM other optional environment variables
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

REM other optional environment variables
SET DD_ENV=production
SET DD_VERSION=1.2.3

REM start the application here

      2. Opcional: Configura la integración de código fuente para conectar tus datos de generación de perfiles con tus repositorios Git.

      3. Un par de minutos después de iniciar la aplicación, los perfiles aparecerán en la página Datadog APM > Generador de perfiles. Si no es así, consulta la guía Solución de problemas.

      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

# other optional environment variables
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=1 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 creación de perfiles de excepción. Por defecto es false.
      DD_PROFILING_ALLOCATION_ENABLEDBooleanoSi se establece en true, activa la creación de perfiles de asignación (en Vista previa). Por defecto es false.
      DD_PROFILING_LOCK_ENABLEDBooleanoSi se establece en true, habilita la creación de perfiles de contención de bloqueo. Por defecto es false.
      DD_PROFILING_HEAP_ENABLEDBooleanoSi se establece en true, habilita el perfilado de heap en directo (en Vista Previa). 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.
      DD_PROFILING_HTTP_ENABLEDBooleanoSi se establece en true, activa la generación de perfiles de solicitudes HTTP salientes utilizada en la interfaz de usuario de Cronología. Por defecto es false.
      DD_PROFILING_HEAPSNAPSHOT_ENABLEDBooleanoSi se establece en true, permite la generación regular de un snapshot heap cuando se detecta un aumento en el consumo de memoria. Esto se utiliza en la Interfaz de usuario de fuga de memoria. Por defecto es false.
      Nota: Para las aplicaciones de IIS (Internet Information Services), debes configurar 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 de Windows Service más arriba. Las variables de entorno se aplican para todas las aplicaciones de IIS (Internet Information Services). A partir de IIS 10, puedes establecer las variables de entorno para cada aplicación de IIS (Internet Information Services) en el archivo C:\Windows\System32\inetsrv\config\applicationhost.config. Lee 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