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 Node.js siguiendo la documentación de la Instrumentación manual de OpenTelemetry Node.js. 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. Añadir el módulo dd-trace a tu paquete .json:

   npm install dd-trace
   

3. Inicializar el módulo dd-trace en tu aplicación:

   const tracer = require('dd-trace').init({
     // ...
   })
   

4. Visitar TracerProvider en tracer:

   const { TracerProvider } = tracer
   

5. Crear y registrar un TracerProvider:

   const provider = new TracerProvider()
   provider.register()
   

6. Importar la API de OpenTelemetry y crear una instancia de rastreador OpenTelemetry:

   const ot = require('@opentelemetry/api')
   const otelTracer = ot.trace.getTracer(
     'my-service'
   )
   

7. 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 instrumentación de la integración y la instrumentación automática de OpenTelemetry.

Añadir etiquetas al tramo

Añade atributos personalizados a tus tramos para proporcionar un contexto adicional:

function processData(i, param1, param2) {
  return otelTracer.startActiveSpan(`processData:${i}`, (span) => {
    const result = someOperation(param1, param2);

    // Add an attribute to the span
    span.setAttribute('app.processedData', result.toString());
    span.end();
    return result;
    });
}

Creación de tramos

Para crear un nuevo tramo y cerrarlo correctamente, utiliza el método startActiveSpan:

function performTask(iterations, param1, param2) {
  // Create a span. A span must be closed.
  return otelTracer.startActiveSpan('performTask', (span) => {
    const results = [];
    for (let i = 0; i < iterations; i++) {
      results.push(processData(i, param1, param2));
    }
    // Be sure to end the span!
    span.end();
    return results;
  });
}

Añadir eventos de tramo

Puedes añadir eventos de tramos utilizando la API addEvent. Este método requiere un parámetro 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.

• Nombre [obligatorio]: una cadena que representa el nombre del evento.
• 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: string, Boolean o number.
    • 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.
• Marca de tiempo [opcional]: una marca de tiempo UNIX que representa la hora en que se produjo un evento. Se espera un objeto TimeInput.

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

span.addEvent('Event With No Attributes')
span.addEvent('Event With Some Attributes', {"int_val": 1, "string_val": "two", "int_array": [3, 4], "string_array": ["5", "6"], "bool_array": [true, false]})

Lee la especificación de OpenTelemetry para obtener más información.

Registro de excepciones

Para registrar excepciones, utiliza la API recordException. Este método requiere un parámetro exception y acepta opcionalmente un parámetro UNIX timestamp. Crea un nuevo evento de tramo que incluya atributos de excepción estandarizados y lo asocia al tramo correspondiente.

Los siguientes ejemplos muestran diferentes formas de registrar excepciones:

span.recordException(new TestError())

Lee la especificación de OpenTelemetry para obtener más información.

Filtrado de solicitudes

En algunos casos, puede que desees excluir instrumentar ciertas solicitudes, como el tráfico de check de estado o tráfico Synthetic. Puedes utilizar las opciones blocklist o allowlist del complemento http para ignorar estas solicitudes.

Para excluir solicitudes a nivel de aplicación, añade lo siguiente después de inicializar el rastreador:

// en la parte superior del punto de entrada justo después de tracer.init()
tracer.use('http', {
  blocklist: ['/health', '/ping']
})

También puedes dividir la configuración entre el cliente y el servidor si es necesario:

tracer.use('http', {
  server: {
    blocklist: ['/ping']
  }
})

Además, puedes excluir trazas basándote en su nombre de recurso para evitar que el Agent las envíe a Datadog. Para obtener más información sobre la seguridad y el ajuste de las configuraciones del Agent, consulta las secciones Seguridad o Ignorar recursos no deseados.

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