Instrumentación personalizada de .NET utilizando la API de Datadog
Si aún no has leído las instrucciones para la instrumentación y la instalación automáticas, empieza por las instrucciones de instalación de
.NET/.NET Core o
.NET Framework.
En esta página se detallan casos de uso frecuentes para añadir y personalizar la observabilidad con Datadog APM . Para consultar una lista de los tiempos de ejecución compatibles, consulta Requisitos de compatibilidad de .NET Framework o Requisitos de compatibilidad de .NET Core.
Hay varias formas de conseguir más que la instrumentación automática por defecto:
Puedes combinar estas soluciones entre sí para conseguir la instrumentación específica que desees. Sin embargo, primero debes instalar la instrumentación automática.
Instrumentar métodos a través de configuración
Mediante la variable de entorno DD_TRACE_METHODS
, puedes obtener visibilidad de los marcos no compatibles sin cambiar el código de la aplicación. Para obtener más detalles sobre el formato de entrada de DD_TRACE_METHODS
, consulta las Instrucciones de configuración de .NET Framework o las Instrucciones de configuración de .NET Core. Por ejemplo, para instrumentar un método llamado SaveSession
definido en el tipo Store.Managers.SessionManager
, configura:
DD_TRACE_METHODS=Store.Managers.SessionManager[SaveSession]
El tramo resultante tiene un atributo operationName
con el valor trace.annotation
y un atributo resourceName
con el valor SaveSession
.
Si deseas personalizar los atributos de tramo y tienes la capacidad de modificar el código fuente, puedes, en cambio, instrumentar métodos a través de atributos.
Instrumentar métodos a través de atributos
Añade [Trace]
a los métodos de Datadog para rastrearlos cuando se ejecuten con la instrumentación automática. Si la instrumentación automática no está activada, este atributo no tiene ningún efecto en tu aplicación.
Los atributos [Trace]
tienen por defecto el nombre de la operación trace.annotation
y el nombre del recurso del método rastreado. Puedes configurar el nombre de la operación y el nombre del recurso como argumentos con nombre del atributo [Trace]
para reflejar mejor lo que se está instrumentando. El nombre de la operación y el nombre del recurso son los únicos argumentos posibles que se pueden configurar para el atributo [Trace]
. Por ejemplo:
a través de Datadog.Trace.Annotations;
namespace Store.Managers
{
public class SessionManager
{
[Trace(OperationName = "database.persist", ResourceName = "SessionManager.SaveSession")]
public static void SaveSession()
{
// la implementación de tu método aquí
}
}
}
Instrumentación personalizada con código
Nota: Esta función requiere añadir el paquete NuGet de
Datadog.Trace
a tu aplicación. Proporciona una API para acceder directamente al rastreador y al tramo activo.
Nota: Cuando utilices el paquete NuGet de Datadog.Trace
y la instrumentación automática, es importante que mantengas las versiones sincronizadas.
Configuración de Datadog en código
Hay varias maneras de configurar tu aplicación: a través de variables de entorno, un archivo web.config
o un archivo datadog.json
, como se describe en nuestra documentación. El paquete NuGet de Datadog.Trace
también te permite configurar ajustes en código.
Para sustituir los ajustes de la configuración, crea una instancia de TracerSettings
y pásala al método estático Tracer.Configure()
:
a través de Datadog.Trace;
// Crear un objeto de configuración a través de las
// variables de entorno y fuentes de configuración
var settings existentes = TracerSettings.FromDefaultSources();
// Sustituir un valor
settings.GlobalTags.Add("SomeKey", "SomeValue");
// Sustituir la configuración del rastreador
Tracer.Configure(settings);
Al llamar a Tracer.Configure()
se sustituye la configuración de todas las trazas (traces) siguientes, para la instrumentación personalizada y para la instrumentación automática.
Debes hacer la sustitución de la configuración una vez, lo antes posible en tu aplicación.
Crear trazas/tramos personalizados
Además de la instrumentación automática, el atributo [Trace]
y las configuraciones de DD_TRACE_METHODS
, puedes personalizar tu observabilidad creando mediante programación tramos alrededor de cualquier bloque de código.
Para crear y activar un tramo personalizado, utiliza Tracer.Instance.StartActive()
. Si ya hay una traza activa (cuando se crea mediante la instrumentación automática, por ejemplo), el tramo forma parte de la traza actual. Si no hay ninguna traza actual, se inicia una nueva.
Advertencia: Asegúrate de desechar el ámbito devuelto desde StartActive
. Al desechar el ámbito, se cierra el tramo y se asegura de que la traza se descargue en Datadog una vez que se hayan cerrado todos sus tramos.
a través de Datadog.Trace;
// Iniciar un nuevo tramo
a través del (ámbito de variable = Tracer.Instance.StartActive("custom-operation"))
{
// Hacer algo
}
Añade etiquetas de tramos personalizadas a tus tramos para personalizar tu capacidad de observación en Datadog. Las etiquetas de tramos se aplican a tus trazas entrantes, lo que te permite correlacionar el comportamiento observado con información al nivel del código como el nivel del comercio, el importe del pago o el ID de usuario.
Crear manualmente un nuevo tramo
Los tramos creados manualmente se integran automáticamente con los tramos de otros mecanismos de rastreo. En otras palabras, si ya se ha iniciado una traza, el tramo manual tiene al autor de la llamada como tramo primario. Del mismo modo, cualquier método rastreado al que se llame desde el bloque de código ajustado tiene al tramo manual como primario.
a través de (var parentScope =
Tracer.Instance.StartActive("manual.sortorders"))
{
parentScope.Span.ResourceName = "<RESOURCE NAME>";
a través de (var childScope =
Tracer.Instance.StartActive("manual.sortorders.child"))
{
// Anidar a través de sentencias alrededor del código para rastrear
childScope.Span.ResourceName = "<RESOURCE NAME>";
SortOrders();
}
}
Añadir etiquetas de tramos personalizadas
Añade etiquetas personalizadas a tus tramos correspondientes a cualquier valor dinámico dentro de tu código de aplicación como customer.id
.
a través de Datadog.Trace;
clase pública ShoppingCartController : Controller
{
privado IShoppingCartRepository _shoppingCartRepository;
[HttpGet]
público IActionResult Index(int customerId)
{
// Accede al ámbito activo a través del rastreador global
// Nota: Esto se puede anular si no hay ningún tramo activo
ámbito de variable = Tracer.Instance.ActiveScope;
si el (´ámbito!= nulo)
{
// Añade una etiqueta al tramo para el uso en la interfaz de usuario web de Datadog
scope.Span.SetTag("customer.id", customerId.ToString());
}
carrito de variable = _shoppingCartRepository.Get(customerId);
devolver View(cart);
}
}
Configurar errores en un tramo
Para marcar los errores que se producen en tu código, utiliza el método Span.SetException(Exception)
. El método marca el tramo como un error y añade metadatos de tramo relacionados) para proporcionar información sobre la excepción.
prueba
{
// haz el trabajo que puede lanzar una excepción
}
catch(Exception e)
{
span.SetException(e);
}
De esta manera se colocan las siguientes etiquetas en el tramo:
"error.msg":exception.Message
"error.stack":exception.ToString()
"error.type":exception.GetType().ToString()
Puedes configurar la propagación del contexto para trazas distribuidas a través de la inserción y extracción de cabeceras. Lee Propagación del contexto de trazas para obtener información.
Añadir etiquetas globalmente a todos tramos
Utiliza la variable de entorno DD_TAGS
para configurar las etiquetas en todos los tramos generados para una aplicación. Esto puede ser útil para agrupar las estadísticas de tus aplicaciones, centros de datos o regiones en la interfaz de usuario de Datadog. Por ejemplo:
DD_TAGS=datacenter:njc,key2:value2
Filtrado de recursos
Puedes excluir trazas en función del nombre del recurso para eliminar el tráfico de Synthetics como comprobaciones de estado. Para obtener más información sobre seguridad y configuraciones adicionales, consulta Configurar el Datadog Agent o Tracer para la Seguridad de los datos.
Lectura adicional
Additional helpful documentation, links, and articles: