Overview

There are a few reasons to manually instrument your applications with the OpenTelemetry API:

• You are not using Datadog supported library instrumentation.
• You want to extend the ddtrace library’s functionality.
• You need finer control over instrumenting your applications.

The ddtrace library provides several techniques to help you achieve these goals. The following sections demonstrate how to use the OpenTelemetry API for custom instrumentation to use with Datadog.

Configuración

Para configurar OpenTelemetry para utilizar el proveedor de traza de Datadog:

1. Añade la instrumentación manual de OpenTelemetry deseada a tu código .NET siguiendo la documentación de la Instrumentación manual de OpenTelemetry .NET. Nota: Cuando esas instrucciones indiquen que tu código debe llamar al SDK de OpenTelemetry, llama a la biblioteca de rastreo de Datadog en su lugar.

2. Instala la biblioteca de rastreo Datadog .NET y activa el rastreador para tu servicio .NET Framework o tu servicio .NET Core (y .NET v5 o posterior). Vista previa: también puedes hacerlo con la instrumentación APM de un solo paso.

3. Establece la variable de entorno DD_TRACE_OTEL_ENABLED en true.

4. Ejecuta tu aplicación.

Datadog combina estos tramos de OpenTelemetry con otros tramos de Datadog APM en una traza única de tu aplicación. También es compatible con la biblioteca de instrumentación de OpenTelemetry.

Creación de tramos personalizados

Para crear tramos manualmente que inicien una nueva traza independiente:

using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

// Start a new span
using (Activity? activity = Telemetry.ActivitySource.StartActivity("<RESOURCE NAME>"))
            {
  activity?.SetTag("operation.name", "custom-operation");
               // Do something
            }

Creación de tramos (spans)

Para crear tramos personalizados dentro de un contexto de traza existente:

using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

using (Activity? parentScope = Telemetry.ActivitySource.StartActivity("<RESOURCE NAME>"))
{
   parentScope?.SetTag("operation.name", "manual.sortorders");
   using (Activity? childScope = Telemetry.ActivitySource.StartActivity("<RESOURCE NAME>"))
   {
       // Nest using statements around the code to trace
       childScope?.SetTag("operation.name", "manual.sortorders.child");
       SortOrders();
   }
}

Añadir etiquetas (tags) al tramo

Añade etiquetas personalizadas a tus tramos para proporcionar un contexto adicional:

using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

public class ShoppingCartController : Controller
{
    private IShoppingCartRepository _shoppingCartRepository;

    [HttpGet]
    public IActionResult Index(int customerId)
    {
      Activity? activity =
      Telemetry.ActivitySource.StartActivity("<RESOURCE NAME>")

        // Añadir una etiqueta al tramo para su uso en la interfaz de usuario web de Datadog
        activity?.SetTag("customer.id", customerId.ToString());

        var cart = _shoppingCartRepository.Get(customerId);

        return View(cart);
    }
}

Errores de ajuste en tramos

Establece la información de error en un tramo cuando se produce un error durante su ejecución.

try
{
    // do work that can throw an exception
}
catch(Exception e)
{
    activity?.SetTag("error", 1);
    activity?.SetTag("error.message", exception.Message);
    activity?.SetTag("error.stack", exception.ToString());
    activity?.SetTag("error.type", exception.GetType().ToString());
}

Añadir eventos de tramo

Puedes añadir eventos de tramos utilizando la API AddEvent. Este método requiere un ActivityEvent creado con un parámetro de name y acepta opcionalmente los parámetros attributes y timestamp. El método crea un nuevo evento de tramo con las propiedades especificadas y lo asocia al tramo correspondiente.

• Name (Nombre) [obligatorio]: una cadena que representa el nombre del evento.
• Marca de tiempo [opcional]: una marca de tiempo UNIX que representa la hora en que se produjo un evento. Se espera un objeto DateTimeOffset.
• Atributos [opcional]: cero o más pares clave-valor con las siguientes propiedades:
  • La clave debe ser una cadena no vacía.
  • El valor puede ser:
    • Un tipo primitivo: cadena, booleano o número.
    • Una matriz homogénea de valores de tipo primitivo (por ejemplo, una matriz de cadenas).
  • Las matrices anidadas y las matrices que contienen elementos de distintos tipos de datos no están permitidas.

Los siguientes ejemplos muestran distintas formas de añadir eventos a un tramo:

var eventTags = new ActivityTagsCollection
{
    { "int_val", 1 },
    { "string_val", "two" },
    { "int_array", new int[] { 3, 4 } },
    { "string_array", new string[] { "5", "6" } },
    { "bool_array", new bool[] { true, false } }
};

activity.AddEvent(new ActivityEvent("Event With No Attributes"));
activity.AddEvent(new ActivityEvent("Event With Some Attributes", DateTimeOffset.Now, eventTags));

Para obtener más información, consulta la especificación de OpenTelemetry.

Propagación del contexto con extracción e inserción de cabeceras

Puedes configurar la propagación de contexto para trazas distribuidas al inyectar y extraer encabezados. Consulta Propagación de contexto de traza para obtener información.

Referencias adicionales

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

Explora tus servicios, recursos y trazasDOCUMENTACIÓN Interoperabilidad de la API de OpenTelemetry e instrumentación de trazas de DatadogDOCUMENTACIÓN