Instrumentación personalizada de Go con la API de OpenTelemetry
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.
Importaciones
Importa los siguientes paquetes para configurar el proveedor de traza de Datadog y los casos de uso que se muestran a continuación:
import (
"context"
"log"
"os"
"gopkg.in/DataDog/dd-trace-go.v1/ddtrace/ext"
ddotel "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/opentelemetry"
ddtracer "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
)
Configuración
Para configurar OpenTelemetry para utilizar el proveedor de traza de Datadog:
Añade la instrumentación manual de OpenTelemetry deseada a tu código Go siguiendo la documentación de la Instrumentación manual de OpenTelemetry Go. Importante: 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.
Instala el paquete de OpenTelemetry go.opentelemetry.io/otel
utilizando el comando:
go get go.opentelemetry.io/otel
Instala el paquete wrapper de Datadog OpenTelemetry gopkg.in/DataDog/dd-trace-go.v1/ddtrace/opentelemetry
utilizando el comando:
go get gopkg.in/DataDog/dd-trace-go.v1/ddtrace/opentelemetry
Importa paquetes en el código:
import (
"go.opentelemetry.io/otel"
ddotel "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/opentelemetry"
)
Crea un TracerProvider, proporcionando opcionalmente un conjunto de opciones, que son específicos de Datadog APM , y aplaza el método Shutdown, que detiene el rastreador:
provider := ddotel.NewTracerProvider()
defer provider.Shutdown()
Utiliza la instancia TracerProvider con la API de OpenTelemetry para establecer el TracerProvider global:
otel.SetTracerProvider(provider)
Ejecuta tu aplicación.
Datadog combina estos tramos de OpenTelemetry con otros tramos de Datadog APM tramos en una única traza de tu aplicación.
Añadir etiquetas al tramo
Añade etiquetas personalizadas a tus tramos para adjuntar metadatos y contexto adicionales a tus trazas.
// Solo se puede hacer después de los pasos de configuración, como inicializar el rastreador.
// Iniciar un tramo.
ctx, span := t.Start(ctx, "read.file")
// Establece un atributo, o una etiqueta de la terminología de Datadog, en un tramo.
span.SetAttributes(attribute.String(ext.ResourceName, "test.json"))
Añadir etiquetas globalmente a todos los tramos
Añade etiquetas a todos los tramos configurando el rastreador con la opción WithGlobalTag
:
// Aquí podemos aprovechar las opciones del rastreador de Datadog pasándolas a la función
// NewTracerProvider.
provider := ddotel.NewTracerProvider(
ddtracer.WithGlobalTag("datacenter", "us-1"),
ddtracer.WithGlobalTag("env", "dev"),
)
defer provider.Shutdown()
// Úsala con la API de OpenTelemetry para establecer el TracerProvider global.
otel.SetTracerProvider(provider)
// Inicia el rastreador con la API de OpenTelemetry.
t := otel.Tracer("")
Configuración de errores en un tramo
Para establecer un error en un tramo, utiliza el método setStatus
de la siguiente manera:
// Inicia un tramo.
ctx, span := t.Start(context.Background(), "span_name")
...
// Establece un error en un tramo con 'span.SetAttributes'.
span.SetAttributes(attribute.String(ext.ErrorMsg, "error_message"))
// Alternativamente, es posible establecer un error en un tramo mediante las opciones de tramo final.
EndOptions(sp, tracer.WithError(errors.New("persisted_option")))
sp.End()
Añadir tramos
A diferencia de otras bibliotecas de rastreo de Datadog, al rastrear aplicaciones de Go, es recomendado que gestiones y pases explícitamente el contexto de Go de tus tramos. Este enfoque asegura relaciones de tramo precisas y un rastreo con sentido. Para más información, consulta la documentación de la biblioteca de contexto de Go o la documentación de cualquier biblioteca de terceros integrada con tu aplicación.
// Solo se puede hacer después de los pasos de configuración.
// Aquí podemos aprovechar context.Context para pasar en opciones de tramo de inicio específicos de Datadog,
// como 'ddtracer.Measured()'
ctx, span := t.Start(
ddotel.ContextWithStartOptions(context.Background(), ddtracer.Measured()), "span_name")
span.End()
Rastrear la configuración del cliente y el Agent
Existen configuraciones adicionales que deben tenerse en cuenta tanto para el cliente de rastreo como para el Datadog Agent:
- Propagación del contexto con encabezados B3
- Excluye recursos específicos del envío de trazas a Datadog si no deseas incluir estas trazas en métricas calculadas, como checks de estado.
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.
Filtrado de recursos
Las trazas se pueden excluir en función de su nombre de recurso, para eliminar el tráfico Synthetic, como los checks de estado, de la notificación de trazas a Datadog. Esta y otras configuraciones de seguridad y ajuste se pueden encontrar en la página de Seguridad.