Descripción general

Si el entorno de ejecución de su aplicación no es compatible de forma nativa con un SDK de Datadog, puede utilizar el SDK de OpenTelemetry para enviar telemetría a Datadog. Este enfoque le proporciona trazas y métricas sin esperar a que exista compatibilidad nativa con el entorno de ejecución.

Esta guía explica cómo instrumentar una aplicación de Bun como ejemplo. Bun es compatible con la mayoría de las API de Node.js, por lo que puede utilizar el SDK de Node.js de OpenTelemetry para instrumentar aplicaciones de Bun. Puede aplicar el mismo patrón a otros entornos de ejecución no soportados que sean compatibles con el SDK de OpenTelemetry

Nivel de soporte

Requisitos previos

• Un backend compatible con OpenTelemetry configurado para enviar datos a Datadog. Consulte Enviar datos de OpenTelemetry a Datadog para conocer las opciones de configuración, incluyendo el colector DDOT, el colector de OpenTelemetry o la ingesta directa de OTLP.
• Bun instalado (v1.0 o posterior).
• Una aplicación de Bun que desea instrumentar.

Instrumentar una aplicación de Bun

Instalar paquetes de OpenTelemetry

Desde el directorio raíz de su proyecto, instale los paquetes de OpenTelemetry requeridos:

bun add @opentelemetry/api \
  @opentelemetry/sdk-node \
  @opentelemetry/sdk-metrics \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http \
  @opentelemetry/exporter-metrics-otlp-http \
  @opentelemetry/resources \
  @opentelemetry/semantic-conventions

Cree un módulo de inicialización de telemetría

En Node.js, OpenTelemetry normalmente se carga a través del indicador --require, que precarga la instrumentación antes de que se ejecute el código de su aplicación. El sistema de resolución de módulos de Bun funciona de manera diferente, por lo que debe inicializar OpenTelemetry mediante programación.

Cree un archivo tracing.ts que configure el SDK de OpenTelemetry para Node.js:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';

const resource = resourceFromAttributes({
  [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || '<YOUR_SERVICE_NAME>',
  [ATTR_SERVICE_VERSION]: process.env.OTEL_SERVICE_VERSION || '1.0.0',
  'telemetry.sdk.runtime': 'bun',
});

const sdk = new NodeSDK({
  resource,
  traceExporter: new OTLPTraceExporter(),
  metricReaders: [new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter(),
  })],
  instrumentations: [getNodeAutoInstrumentations({
    // Disable fs instrumentation to avoid compatibility issues with Bun
    '@opentelemetry/instrumentation-fs': { enabled: false },
  })],
});

sdk.start();

process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('OpenTelemetry SDK shut down'))
    .catch((err) => console.error('Error shutting down OpenTelemetry SDK', err))
    .finally(() => process.exit(0));
});

Reemplace <YOUR_SERVICE_NAME> con el nombre del servicio de su aplicación.

Inicialice la telemetría en el punto de entrada de su aplicación

Importe el módulo tracing.ts antes de cualquier otra importación de la aplicación. El SDK de OpenTelemetry debe inicializarse primero para aplicar parches a las bibliotecas para la instrumentación automática.

import './tracing';

// Import your application code after tracing is initialized
import { startApp } from './app';

startApp();

Configure las variables de entorno

Establezca las siguientes variables de entorno para configurar el punto de conexión del exportador OTLP y la identidad de su servicio:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_SERVICE_NAME="<YOUR_SERVICE_NAME>"

El valor OTEL_EXPORTER_OTLP_ENDPOINT depende de su configuración:

• Colector local (DDOT u OpenTelemetry Collector): http://localhost:4318 (HTTP predeterminado) o http://localhost:4317 (gRPC)
• Colector remoto: Utilice la dirección y el puerto del colector

Para opciones de configuración adicionales, consulte la especificación de variables de entorno de OpenTelemetry.

Ejecute su aplicación

Inicie su aplicación Bun:

bun run index.ts

Agregue instrumentación manual para las API nativas de Bun

Las API integradas de Bun, como Bun.serve(), bun:sqlite y las API nativas de E/S de archivos, no se instrumentan automáticamente. Para capturar telemetría de estas API, cree tramos manualmente con el paquete @opentelemetry/api.

El siguiente ejemplo envuelve un controlador de rutas Bun.serve() con un tramo personalizado:

import { trace, SpanKind } from '@opentelemetry/api';

const tracer = trace.getTracer('bun-app');

export function startServer() {
  Bun.serve({
    port: 3000,
    fetch(req) {
      return tracer.startActiveSpan('handleRequest', { kind: SpanKind.SERVER }, (span) => {
        try {
          span.setAttribute('http.method', req.method);
          span.setAttribute('http.url', req.url);
          return new Response('Hello from Bun!');
        } finally {
          span.end();
        }
      });
    },
  });
}

Para más patrones de instrumentación manual, consulte la documentación de instrumentación de OpenTelemetry JS.

Verifique las trazas en Datadog

Después de que su aplicación maneje algunas solicitudes:

1. Vaya a APM > Traces en Datadog.
2. Busque el nombre de su servicio.
3. Confirme que las trazas aparezcan con los tramos y metadatos esperados.

Limitaciones

• Cobertura de instrumentación automática: Las bibliotecas de instrumentación automática de OpenTelemetry para Node.js dependen de la capa de compatibilidad con Node.js de Bun. La mayoría de las bibliotecas comunes (clientes HTTP, Express, controladores de bases de datos) funcionan, pero algunos paquetes de instrumentación podrían no funcionar como se espera.
• APIs nativas de Bun: Las APIs integradas de Bun como Bun.serve(), bun:sqlite y las APIs nativas de E/S de archivos no se instrumentan automáticamente. Consulte Agregar instrumentación manual para APIs nativas de Bun para ver un ejemplo.
• Compatibilidad de bibliotecas: No se garantiza que todas las bibliotecas de instrumentación de Node.js funcionen con Bun. Pruebe sus dependencias específicas y deshabilite cualquier instrumentación que cause errores pasando opciones de configuración a getNodeAutoInstrumentations(). El paquete @opentelemetry/instrumentation-fs es una fuente común de problemas y está deshabilitado en la configuración de ejemplo anterior.

Lecturas adicionales

Documentación, enlaces y artículos útiles adicionales:

Compatibilidad entre Datadog y OpenTelemetryDOCUMENTACIÓN Utilice componentes personalizados de OpenTelemetryDOCUMENTACIÓN Instrumente su aplicación con OpenTelemetryDOCUMENTACIÓN