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. Instalar paquetes de la API de OpenTelemetry.

composer require open-telemetry/sdk

2. Añade la instrumentación manual de OpenTelemetry que desees a tu código PHP siguiendo la documentación de instrumentación manual de OpenTelemetry PHP.

3. Instala la biblioteca de rastreo de Datadog PHP.

4. Configura DD_TRACE_OTEL_ENABLED en true.

Datadog combina estos tramos (spans) de OpenTelemetry con otros tramos de Datadog APM en una única traza de tu aplicación.

Añadir etiquetas (tags) de tramo

Puedes añadir atributos en el momento exacto en que inicias el tramo:

$span = $tracer->spanBuilder('mySpan')
    ->setAttribute('key', 'value')
    ->startSpan();

O mientras el tramo esté activo:

$activeSpan = OpenTelemetry\API\Trace\Span::getCurrent();

$activeSpan->setAttribute('key', 'value');

Configuración de errores en un tramo

La información de la excepción se captura y se adjunta al tramo si hay uno activo cuando se produce la excepción.

// Crear un tramo
$span = $tracer->spanBuilder('mySpan')->startSpan();

throw new \Exception('Oops!');

// 'mySpan' se marcará con un error y tendrá 
// la traza del stack tecnológico y el mensaje de excepción adjuntos como etiquetas

También se puede marcar manualmente una traza como errónea:

use OpenTelemetry\API\Trace\Span;
use OpenTelemetry\Context\Context;

// Solo se puede hacer después de los pasos de configuración, tales como la inicialización del rastreador.

try {
    throw new \Exception('Oops!');
} catch (\Exception $e) {
    $rootSpan = Span::fromContext(Context::getRoot());
    $rootSpan->recordException($e);
}

Añadir tramos

Para añadir un tramo:

// Obtener un rastreador o usar uno existente
$tracerProvider = \OpenTelemetry\API\Globals::tracerProvider();
$tracer = $tracerProvider->getTracer('datadog')

// Crear un tramo
$span = $tracer->spanBuilder('mySpan')->startSpan();

// ... hacer algo

// Cerrar el tramo
$span->end();

Añadir eventos de tramos

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: 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.
• Marca de tiempo [opcional]: Una marca de tiempo UNIX que representa la hora en que se produjo un evento. Se espera en nanoseconds.

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]
    ]
);

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

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 \Exception("Error Message"));
$span->recordException(new \Exception("Error Message"), [ "status" => "failed" ]);

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

Acceso a tramos activos

Para acceder al tramo activo en ese momento:

$span = OpenTelemetry\API\Trace\Span::getCurrent();

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