Rastreo de aplicaciones .NET Core
Requisitos de compatibilidad
Tiempos de ejecución .NET Core compatibles
El rastreador de .NET es compatible con la instrumentación en .NET Core 2.1, .NET Core 3.1, .NET 5, .NET 6, .NET 7 y .NET 8.
Para ver una lista completa de las compatibilidades de la arquitectura de la biblioteca y del procesador de Datadog .NET Core (incluyendo las versiones heredadas y de mantenimiento), consulta los requisitos de compatibilidad.
Para instalar y empezar a utilizar
Nota: La instrumentación automática de Datadog se basa en la API de generación de perfiles CLR de .NET. Esta API sólo permite un suscriptor (por ejemplo, Datadog APM). Para garantizar la máxima visibilidad, ejecuta sólo una solución APM en tu entorno de aplicación.
Para instrumentar aplicaciones recortadas, consulta el paquete NuGet
Datadog.Trace.Trimming de tu proyecto. La compatibilidad con aplicaciones recortadas está en fase Beta.
Instalación
Antes de empezar, asegúrate de haber instalado y configurado el Agent.
- Instala el rastreador.
- Activa el rastreador para tu servicio.
- Visualiza tus datos en directo.
Instalación del rastreador
Después de instalar y configurar tu Datadog Agent, el siguiente paso es añadir la biblioteca de rastreo directamente en la aplicación para instrumentarla. Consulta más bibliografía con información sobre la compatibilidad.
Puedes instalar el rastreador de .NET de Datadog en toda la máquina para que se instrumenten todos los servicios de la máquina, o puedes instalarlo aplicación por aplicación para que los desarrolladores gestionen la instrumentación a través de las dependencias de la aplicación. Para ver más instrucciones sobre la instalación en toda la máquina, haz clic en la pestaña de Windows o Linux. Para ver más instrucciones sobre la instalación aplicación por aplicación, haz clic en la pestaña de NuGet.
Para instalar el rastreador .NET en toda la máquina:
Descarga el instalador MSI del rastreador .NET. Selecciona el instalador MSI que corresponda a la arquitectura del sistema operativo (x64 ó x86).
Ejecuta el instalador MSI del rastreador .NET con privilegios administrativos.
También puedes aplicar un script para la configuración de MSI ejecutando lo siguiente en PowerShell: Start-Process -Wait msiexec -ArgumentList '/qn /i datadog-apm.msi'
Para instalar el rastreador .NET en toda la máquina:
Descarga el paquete del rastreador .NET más reciente que sea compatible con tu sistema operativo y tu arquitectura.
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 && /opt/datadog/createLogPath.sh- CentOS o Fedora
sudo rpm -Uvh datadog-dotnet-apm<TRACER_VERSION>-1.x86_64.rpm && /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 && sh /opt/datadog/createLogPath.sh- Otras distribuciones
sudo tar -C /opt/datadog -xzf datadog-dotnet-apm-<TRACER_VERSION>.tar.gz && /opt/datadog/createLogPath.sh
Contenedores cincelados
Para instalar el rastreador .NET en imágenes cinceladas o distroless Docker (sin shell), utiliza los siguientes comandos de archivos Docker:
- Utiliza
ADD para colocar los archivos del rastreador en el contenedor. - Utiliza
COPY --chown=$APP_UID con una carpeta vacía como origen para crear la ruta de los logs.
Por ejemplo, en tu archivo Docker:
ADD datadog-dotnet-apm-<TRACER_VERSION>.tar.gz /opt/datadog/
COPY --chown=$APP_UID --from=<OTHER_STAGE> /empty/ /var/log/datadog/dotnet/
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 rastreador .NET aplicación por aplicación:
- Añade el paquete NuGet
Datadog.Trace.Bundle a tu aplicación.
Activación del rastreador para tu servicio
Para activar el rastreador .NET para tu servicio, configura las variables de entorno necesarias y reinicia la aplicación.
Para obtener más información sobre los diferentes métodos de configurar variables de entorno, consulta la Proceso de configuración de variables de entorno.
El instalador MSI del rastreador .NET añade todas las variables de entorno necesarias. No necesitas configurar ninguna variable de entorno.
Note: You must set the
.NET CLR version for the application pool to
No Managed Code as recommended by
Microsoft.
Para instrumentar aplicaciones alojadas en IIS automáticamente, ejecuta los siguientes comandos como administrador para detener e reiniciar IIS completamente:
net stop /y was
net start w3svc
# Also, start any other services that were stopped when WAS was shut down.
Note: Always use the commands above to completely stop and restart IIS to enable the tracer. Avoid using the IIS Manager GUI application or iisreset.exe.
Servicios que no se encuentran en IIS
Cuando inicias v2.14.0, no necesitas configurar CORECLR_PROFILER, si ya has instalado el rastreador utilizando el MSI.
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}
En el caso de aplicaciones y servicios de Windows independientes, debes reiniciar la aplicación manualmente.
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
En el caso de aplicaciones independientes, reinicia la aplicación manualmente como lo harías normalmente.
Sigue las instrucciones Readme (Léeme) del paquete, también disponibles en el repositorio dd-trace-dotnet.
En el repositorio, también hay ejemplos de Docker disponibles.
Visualización en directo de tus datos
Después de activar el rastreador .NET para tu servicio:
Reinicia tu servicio.
Crea la carga de la aplicación.
En Datadog, ve a APM > APM Traces (APM* > **Trazas APM).
Configuración
Si es necesario, configura la biblioteca de rastreo para que envíe datos de telemetría sobre el rendimiento de la aplicación, según sea necesario, incluida la configuración del etiquetado unificado de servicios. Para ver más detalles, consulta la configuración de bibliotecas.
Instrumentación personalizada
Tu configuración de la instrumentación personalizada depende de tu instrumentación automática e incluye pasos adicionales que dependen del método:
Nota: Si estás utilizando la instrumentación automática y la personalizada, debes mantener sincronizadas las versiones del paquete (por ejemplo: MSI y NuGet).
Para utilizar la instrumentación personalizada en tu aplicación .NET:
- Añade el paquete NuGet
Datadog.Trace a tu aplicación. - En tu código de aplicación, accede al rastreador global a través de la propiedad de
Datadog.Trace.Tracer.Instance para crear nuevos tramos (spans).
Nota: Si estás utilizando la instrumentación automática y la personalizada, debes mantener sincronizadas las versiones del paquete (por ejemplo: MSI y NuGet).
Para utilizar la instrumentación personalizada en tu aplicación .NET:
- Añade el paquete NuGet
Datadog.Trace a tu aplicación. - En tu código de aplicación, accede al rastreador global a través de la propiedad de
Datadog.Trace.Tracer.Instance para crear nuevos tramos.
Para utilizar la instrumentación personalizada en tu aplicación .NET:
- En tu código de aplicación, accede al rastreador global a través de la propiedad de
Datadog.Trace.Tracer.Instance para crear nuevos tramos.
Para obtener más información sobre cómo añadir tramos y etiquetas (tags) para la instrumentación personalizada, consulta la documentación para la instrumentación personalizada de .NET.
Configuración de variables de entorno para procesos
Para adjuntar la instrumentación automática a tu servicio, debes configurar las variables de entorno obligatorias antes de iniciar la aplicación. Consulta la sección Activar el rastreador para tu servicio para identificar las variables de entorno que debes configurar, dependiendo del método que has utilizado para instalar el rastreador .NET y sigue los siguientes ejemplos para configurar las variables de entorno correctamente, según el entorno de tu servicio instrumentado.
Windows
Servicios de Windows
Cuando inicias v2.14.0, no necesitas configurar CORECLR_PROFILER, si ya has instalado el rastreador utilizando el MSI.
En el Editor de registro, crea un valor de cadena múltiples llamado Environment en la clave HKLM\System\CurrentControlSet\Services\<SERVICE NAME> y configura los datos de valor como:
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
[string[]] $v = @("CORECLR_ENABLE_PROFILING=1", "CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}")
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<SERVICE NAME> -Name Environment -Value $v
IIS
Una vez instalado el MSI, no es necesaria ninguna configuración adicional para instrumentar tus sitios de IIS automáticamente. Sigue los siguientes pasos para configurar variables de entorno adicionales, heredadas por todos los sitios de IIS:
- Abre el Editor de registro, busca el valor de cadenas múltiples llamado
Environment en la clave HKLM\System\CurrentControlSet\Services\WAS y añade las variables de entorno, una por cada línea. Por ejemplo, para añadir la inyección de logs y métricas de tiempos de ejecución, añade las siguientes líneas a los datos de valor:DD_LOGS_INJECTION=true
DD_RUNTIME_METRICS_ENABLED=true
- Ejecuta los siguientes comandos para reiniciar los IIS:
net stop /y was
net start w3svc
# Also, start any other services that were stopped when WAS was shut down.
Aplicaciones de consola
Para instrumentar una aplicación de consola automáticamente, antes de iniciar tu aplicación configura las variables de entorno desde un archivo de lote:
rem Configura variables de entorno
SET CORECLR_ENABLE_PROFILING=1
rem Unless v2.14.0+ and you installed the tracer with the MSI
SET CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
rem Set additional Datadog environment variables
SET DD_LOGS_INJECTION=true
SET DD_RUNTIME_METRICS_ENABLED=true
rem Start application
dotnet.exe example.dll
Linux
Script de bash
Para configurar las variables de entorno obligatorias desde un archivo bash antes de iniciar tu aplicación:
# Configura variables de entorno
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
export CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
export DD_DOTNET_TRACER_HOME=/opt/datadog
# Configura variables de entorno de Datadog adicionales
export DD_LOGS_INJECTION=true
export DD_RUNTIME_METRICS_ENABLED=true
# Inicia tu aplicación
dotnet example.dll
Si utilizas Alpine Linux, configura la variable de entorno CORECLR_PROFILER_PATH en una ruta para distribuciones basadas en musl: linux-musl-x64/.
Contenedor Docker de Linux
Para configurar las variables de entorno obligatorias en un contenedor Docker de Linux:
# Configura variables de entorno
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
ENV CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
ENV DD_DOTNET_TRACER_HOME=/opt/datadog
# Configura variables de entorno de Datadog adicionales
ENV DD_LOGS_INJECTION=true
ENV DD_RUNTIME_METRICS_ENABLED=true
# Inicia tu aplicación
CMD ["dotnet", "example.dll"]
systemctl (por servicio)
Cuando utilizas systemctl para ejecutar aplicaciones de .NET como un servicio, puedes añadir las variables de entorno necesarias para que se carguen para un servicio específico.
Crea un archivo llamado environment.env que contenga:
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
# Set additional Datadog environment variables
DD_LOGS_INJECTION=true
DD_RUNTIME_METRICS_ENABLED=true
En el archivo de configuración del servicio, indica esto como un EnvironmentFile en el bloque de servicios:
[Service]
EnvironmentFile=/path/to/environment.env
ExecStart=<command used to start the application>
Reinicia el sevicio .NET para que la configuración de la variable de entorno se aplique.
systemctl (todos los servicios)
Nota: El tiempo de ejecución de .NET intenta cargar un generador de perfiles en cualquier proceso de .NET que se inicia con estas variables de entorno configuradas. Debes limitar la instrumentación sólo a aplicaciones que necesitan ser rastreadas. No debes configurar estas variables de entorno globalmente, ya que esto lleva que todos los procesos de .NET en el host carguen el generador de perfiles.
Cuando utilizas systemctl para ejecutar aplicaciones de .NET como un servicio, también puedes configurar variables de entorno para que se carguen para todos los servicios que ejecuta systemctl.
Ejecuta systemctl set-environment para configurar las variables de entorno obligatorias:
systemctl set-environment CORECLR_ENABLE_PROFILING=1
systemctl set-environment CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
systemctl set-environment CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
systemctl set-environment DD_DOTNET_TRACER_HOME=/opt/datadog
# Set additional Datadog environment variables
systemctl set-environment DD_LOGS_INJECTION=true
systemctl set-environment DD_RUNTIME_METRICS_ENABLED=true
Ejecuta systemctl show-environment para verificar que se hayan configurado las variables de entorno.
Reinicia el servicio de .NET para aplicar las variables de entorno.
Leer más
Más enlaces, artículos y documentación útiles:
