Instrumentación automática para LLM Observability

Este producto no es compatible con el sitio Datadog seleccionado. ().

Resumen

LLM Observability de Datadog puede rastrear y anotar automáticamente las llamadas a los marcos y bibliotecas LLM compatibles a través de varias integraciones LLM. Cuando ejecute su aplicación con el LLM Observability SDK, estas integraciones LLM están habilitadas por defecto y proporcionan trazas y observabilidad listas para usar, sin necesidad de cambiar su código.

La instrumentación automática funciona para llamadas a marcos y bibliotecas compatibles. Para rastrear otras llamadas (por ejemplo: llamadas a API, consultas a bases de datos, funciones internas), consulte la referencia del SDK de Observabilidad de LLM para saber cómo agregar instrumentación manual.

Frameworks y bibliotecas compatibles

    MarcoVersiones CompatiblesVersión del Rastreador
    Amazon Bedrock>= 1.31.57>= 2.9.0
    Amazon Bedrock Agents>= 1.38.26>= 3.10.0
    Anthropic>= 0.28.0>= 2.10.0
    CrewAI>= 0.105.0>= 3.5.0
    Google ADK>= 1.0.0>= 3.15.0
    Google GenAI>= 1.21.1>= 3.11.0
    LangChain>= 0.0.192>= 2.9.0
    LangGraph>= 0.2.23>= 3.10.1
    LiteLLM>= 1.70.0>= 3.9.0
    MCP>= 1.10.0>= 3.11.0
    OpenAI, Azure OpenAI>= 0.26.5>= 2.9.0
    OpenAI Agents>= 0.0.2>= 3.5.0
    Pydantic AI>= 0.3.0>= 3.11.0
    Strands Agents>= 1.11.0Cualquiera
    Vertex AI>= 1.71.1>= 2.18.0
    MarcoVersiones CompatiblesVersión del rastreador
    Amazon Bedrock>= 3.422.0>= 5.35.0 (CJS), >=5.35.0 (ESM)
    Anthropic>= 0.14.0>= 5.71.0 (CJS), >=5.71.0 (ESM)
    LangChain>= 0.1.0>= 5.32.0 (CJS), >=5.38.0 (ESM)
    OpenAI, Azure OpenAI>= 3.0.0>= 4.49.0, >= 5.25.0 (CJS), >= 5.38.0 (ESM)
    Vercel AI SDK>=4.0.0>= 5.63.0 (CJS), >=5.63.0 (ESM)
    VertexAI>= 1.0.0>= 5.44.0 (CJS), >=5.44.0 (ESM)
    Google GenAI>= 1.19.0>= 5.81.0 (CJS), >=5.81.0 (ESM)

    La instrumentación automática para proyectos ESM es compatible a partir de dd-trace@>=5.38.0. Para habilitar la instrumentación automática en sus proyectos ESM, ejecute su aplicación con la siguiente opción de Node:

    --import dd-trace/register.js

    Para la configuración de línea de comandos, utilice la siguiente opción en su lugar:

    --import dd-trace/initialize.mjs
# or
--loader dd-trace/initialize.mjs
    Solución de problemas: Cargador personalizado para incompatibilidad de módulos

    Si hay errores al iniciar su aplicación al usar esta opción, es probable que haya una incompatibilidad de módulos. Puede crear su propio archivo de gancho excluyendo el módulo y el archivo en cuestión:

    // hook.mjs

import { register } from 'node:module';

register('import-in-the-middle/hook.mjs', import.meta.url, {
  parentURL: import.meta.url,
  data: { exclude: [
    /langsmith/,
    /openai\/_shims/,
    /openai\/resources\/chat\/completions\/messages/,
    // Add any other modules you want to exclude
  ]}
});

    Para usar este cargador personalizado, ejecute su aplicación con la siguiente opción de Node:

    --import ./hook.mjs

    Para usar integraciones LLM Observability en aplicaciones empaquetadas (esbuild, Webpack), debe excluir los módulos de estas integraciones del empaquetado.

    esbuild

    Si está utilizando esbuild, consulte Empaquetado con el rastreador de Node.js.

    Webpack

    Para Webpack, especifique la integración correspondiente en la sección externals de la configuración de webpack:

    // webpack.config.js
module.exports = {
  resolve: {
    fallback: {
      graphql: false,
    }
  },
  externals: {
    openai: 'openai'
  }
}

    Inicialice correctamente el rastreador en su aplicación para asegurar que la auto-instrumentación funcione correctamente. Si está utilizando TypeScript o ESM para su aplicación Next.js, inicialice el rastreador en un archivo instrumentation.{ts/js} de la siguiente manera, especificando sus opciones de configuración como variables de entorno:

    // instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const initializeImportName = 'dd-trace/initialize.mjs';
    await import(/* webpackIgnore: true */ initializeImportName as 'dd-trace/initialize.mjs')
  }

  // ...
}

    De lo contrario, para aplicaciones Next.js en CommonJS, puede usar la función init directamente:

    // instrumentation.js
const tracer = require('dd-trace')

function register () {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    tracer.init({}); // specify options here or they will be read from environment variables
  }

  // ...
}

module.exports = register;

    Luego, asegúrese de especificar dd-trace y cualquier otra integración soportada en serverExternalPackages en su archivo next.config.{ts/js}:

    // next.config.ts
module.exports = {
  serverExternalPackages: ['dd-trace', 'openai'], // add any other supported integrations here to be auto-instrumented
}
    MarcoVersiones SoportadasVersión del Rastreador
    OpenAI, Azure OpenAI>= 3.0.0>= 1.59.0
    Datadog LLM Observability también admite cualquier marco que emita nativamente tramos compatibles con la convención semántica de OpenTelemetry GenAI v1.37+, sin requerir el rastreador de Datadog. Consulte Instrumentación de OpenTelemetry para más detalles.

    Integraciones de LLM

    Las integraciones LLM de Datadog capturan latencia, errores, parámetros de entrada, mensajes de entrada y salida, y el uso de tokens (cuando esté disponible) para las llamadas rastreadas.

      La integración de Amazon Bedrock proporciona instrumentación automática para las llamadas al modelo de chat del SDK de Python de Amazon Bedrock Runtime (usando Boto3/Botocore).

      Métodos rastreados

      La integración de Amazon Bedrock instrumenta los siguientes métodos:

      La integración de Amazon Bedrock no admite el trazado de llamadas de incrustación.

      La integración de Amazon Bedrock proporciona trazado automático para las llamadas al modelo de chat del SDK de Node.js de Amazon Bedrock (usando BedrockRuntimeClient).

      Métodos rastreados

      La integración de Amazon Bedrock instrumenta los siguientes métodos:

        La integración de Amazon Bedrock Agents proporciona trazado automático para las llamadas de invocación del agente del Amazon Bedrock Agents Runtime Python SDK (usando Boto3/Botocore).

        Métodos trazados

        La integración de Agentes de Amazon Bedrock instrumenta los siguientes métodos:

        La integración de Agentes de Amazon Bedrock, por defecto, solo traza el método general InvokeAgent. Para habilitar el trazado de pasos intra-agente, debe establecer enableTrace=True en los parámetros de solicitud de InvocarAgente.

          La integración de Anthropic proporciona trazado automático para las llamadas de mensajes de chat del SDK de Anthropic en Python.

          Métodos trazados

          La integración de Anthropic instrumenta los siguientes métodos:

          La integración de Anthropic proporciona trazado automático para las llamadas de mensajes de chat del SDK de Node.js de Anthropic.

          Métodos trazados

          La integración de Anthropic instrumenta los siguientes métodos:

            La integración de CrewAI traza automáticamente la ejecución de los inicios de Crew, incluyendo invocaciones de tareas/agentes/herramientas, realizadas a través del SDK de Python de CrewAI.

            Métodos trazados

            La integración de CrewAI instrumenta los siguientes métodos:

              La integración de Google ADK proporciona trazado automático para ejecuciones de agentes, llamadas a herramientas y ejecuciones de código realizadas a través del SDK de Python de Google ADK.

              Métodos trazados

              La integración de Google ADK instrumenta los siguientes métodos:

              Ambos métodos run_live y run_async son soportados.

                La integración de Google GenAI traza automáticamente los métodos en el Google GenAI Python SDK.

                Nota: El Google GenAI Python SDK sucede al Google GenerativeAI SDK y expone tanto la API de desarrollador de Gemini como Vertex.

                Métodos trazados

                La integración de Google GenAI instrumenta los siguientes métodos:

                • Generando contenido (incluyendo llamadas transmitidas):
                  • models.generate_content() (También captura chat.send_message())
                  • aio.models.generate_content() (También captura aio.chat.send_message())
                • Incorporando contenido -models.embed_content() -aio.models.embed_content()

                La integración de Google GenAI traza automáticamente los métodos en el Google GenAI Node.js SDK al instrumentar el @google/genai paquete.

                Nota: El Google GenAI Node.js SDK sucede al Google GenerativeAI SDK y expone tanto la API de desarrollador de Gemini como Vertex.

                Métodos trazados

                La integración de Google GenAI instrumenta los siguientes métodos:

                  La integración de LangChain proporciona trazado automático para el SDK de Python de LangChain LLM, modelo de chat y llamadas de cadena.

                  Métodos trazados

                  La integración de LangChain instrumenta los siguientes métodos:

                  • LLMs:

                    • llm.invoke(), llm.ainvoke()
                    • llm.stream(), llm.astream()

                  • Modelos de chat

                    • chat_model.invoke(), chat_model.ainvoke()
                    • chat_model.stream(), chat_model.astream()

                  • Cadenas/LCEL

                    • chain.invoke(), chain.ainvoke()
                    • chain.batch(), chain.abatch()
                    • chain.stream(), chain.astream()

                  • Embeddings

                    • OpenAI : OpenAIEmbeddings.embed_documents(), OpenAIEmbeddings.embed_query()

                  • Herramientas

                    • BaseTool.invoke(), BaseTool.ainvoke()

                  • Recuperación

                    • langchain_community.<vectorstore>.similarity_search()
                    • langchain_pinecone.similarity_search()

                  • Plantillas de Prompt

                    • BasePromptTemplate.invoke(), BasePromptTemplate.ainvoke()
                    Para obtener los mejores resultados, asigna plantillas a variables con nombres significativos. La instrumentación automática utiliza estos nombres para identificar los prompts.
                    # "translation_template" will be used to identify the template in Datadog
translation_template = PromptTemplate.from_template("Translate {text} to {language}")
chain = translation_template | llm

                  La integración de LangChain proporciona trazado automático para las llamadas a LLM, modelo de chat, cadena y embeddings de OpenAI a través del SDK de LangChain Node.js.

                  Métodos trazados

                  La integración de LangChain instrumenta los siguientes métodos:

                    La integración de LangGraph traza automáticamente las invocaciones de Pregel/CompiledGraph y RunnableSeq (node) realizadas a través del SDK de LangGraph Python.

                    Métodos trazados

                    La integración de LangGraph instrumenta versiones sincrónicas y asincrónicas de los siguientes métodos:

                      La integración de LiteLLM proporciona trazado automático para el SDK de LiteLLM Python y métodos de enrutador de servidor proxy.

                      Métodos trazados

                      La integración de LiteLLM instrumenta los siguientes métodos:

                      • Completaciones de chat (incluyendo llamadas transmitidas):
                        • litellm.completion
                        • litellm.acompletion
                      • Completaciones (incluyendo llamadas transmitidas):
                        • litellm.text_completion
                        • litellm.atext_completion
                      • Completaciones de chat de enrutador (incluyendo llamadas transmitidas):
                        • router.Router.completion
                        • router.Router.acompletion
                      • Completaciones de enrutador (incluyendo llamadas transmitidas):
                        • router.Router.text_completion
                        • router.Router.atext_completion

                        La integración de Model Context Protocol (MCP) instrumenta las llamadas a herramientas del cliente y del servidor en el SDK de MCP.

                        Métodos trazados

                        La integración de MCP instrumenta los siguientes métodos:

                          La integración de OpenAI proporciona trazado automático para los puntos finales de finalización y chat del SDK de Python de OpenAI hacia OpenAI y Azure OpenAI.

                          Métodos trazados

                          La integración de OpenAI instrumenta los siguientes métodos, incluyendo llamadas transmitidas:

                          • Finalizaciones:
                            • OpenAI().completions.create(), AzureOpenAI().completions.create()
                            • AsyncOpenAI().completions.create(), AsyncAzureOpenAI().completions.create()
                          • Finalizaciones de chat:
                            • OpenAI().chat.completions.create(), AzureOpenAI().chat.completions.create()
                            • AsyncOpenAI().chat.completions.create(), AsyncAzureOpenAI().chat.completions.create()
                          • Respuestas:
                            • OpenAI().responses.create()
                            • AsyncOpenAI().responses.create()
                            • OpenAI().responses.parse() (a partir de ddtrace==3.17.0)
                            • AsyncOpenAI().responses.parse() (a partir de ddtrace==3.17.0)
                          • Llamadas realizadas a DeepSeek a través del SDK de Python de OpenAI (a partir de ddtrace==3.1.0)

                          La integración de OpenAI proporciona trazado automático para los puntos de conexión de finalización, chat y embeddings del SDK de Node.js de OpenAI hacia OpenAI y Azure OpenAI.

                          Métodos trazados

                          La integración de OpenAI instrumenta los siguientes métodos, incluyendo llamadas transmitidas:

                          La integración de OpenAI proporciona trazado automático para los endpoints de completion, chat completion, embeddings y responses del OpenAI Java SDK para OpenAI y Azure OpenAI.

                          Métodos rastreados

                          La integración de OpenAI instrumenta los siguientes métodos en OpenAIClient, incluyendo llamadas transmitidas:

                          • Completions:
                            • openAiClient.completions().create()
                            • openAiClient.completions().createStreaming()
                            • openAiClient.async().completions().create()
                            • openAiClient.async().completions().createStreaming()
                          • Chat completions:
                            • openAiClient.chat().completions().create()
                            • openAiClient.chat().completions().createStreaming()
                            • openAiClient.async().chat().completions().create()
                            • openAiClient.async().chat().completions().createStreaming()
                          • Embeddings:
                            • openAiClient.embeddings().create()
                            • openAiClient.async().embeddings().create()
                          • Respuestas:
                            • openAiClient.responses().create()
                            • openAiClient.responses().createStreaming()
                            • openAiClient.async().responses().create()
                            • openAiClient.async().responses().createStreaming()

                          El proveedor (OpenAI vs Azure OpenAI) se detecta automáticamente según el baseUrl configurado en ClientOptions. Todos los métodos admiten variantes tanto bloqueantes como asíncronas (basadas en CompletableFuture).

                            La integración de Agentes de OpenAI convierte el trazado incorporado del OpenAI Agents SDK en lo convierte al formato de LLM Observability y lo envía al producto de LLM Observability de Datadog agregando un procesador de trazas de Datadog.

                            Las siguientes operaciones son compatibles:

                              La integración de Pydantic AI instrumenta las invocaciones de agentes y las llamadas a herramientas realizadas utilizando el marco de agentes Pydantic AI.

                              Métodos rastreados

                              La integración de Pydantic AI instrumenta los siguientes métodos:

                              • Invocaciones de Agentes (incluyendo cualquier herramienta o conjunto de herramientas asociadas con el agente):
                                • agent.Agent.iter (también rastrea agent.Agent.run y agent.Agent.run_sync)
                                • agent.Agent.run_stream

                                A partir de v1.11.0, Agentes de Strands emite de manera nativa tramos compatibles con convenciones semánticas de OpenTelemetry GenAI v1.37, que Datadog LLM Observability ingiere automáticamente sin requerir el tracer de Datadog.

                                Para instrucciones de configuración y un ejemplo completo, consulte Instrumentación de OpenTelemetry — Usando Agentes de Strands.

                                  La integración del Vercel AI SDK traza automáticamente la generación de texto y objetos, embeddings y llamadas a herramientas al interceptar los tramos de OpenTelemetry creados por el núcleo subyacente del Vercel AI SDK y convertirlos en tramos de Datadog LLM Observability.

                                  Métodos rastreados

                                  Telemetría del SDK de Vercel AI Core

                                  Esta integración parchea automáticamente el tracer pasado a cada uno de los métodos rastreados bajo la opción experimental_telemetry. Si no se pasa ninguna configuración experimental_telemetry, la integración permite que aún se envíen tramos de Observabilidad LLM.

                                  require('dd-trace').init({
  llmobs: {
    mlApp: 'my-ml-app',
  }
});

const { generateText } = require('ai');
const { openai } = require('@ai-sdk/openai');

async function main () {
  let result = await generateText({
    model: openai('gpt-4o'),
    ...
    experimental_telemetry: {
      isEnabled: true,
      tracer: someTracerProvider.getTracer('ai'), // this tracer will be patched to format and send created spans to Datadog LLM Observability
    }
  });

  result = await generateText({
    model: openai('gpt-4o'),
    ...
  }); // since no tracer is passed in, the integration will enable it to still send LLM Observability spans
}

                                  Nota: Si experimental_telemetry.isEnabled está configurado en false, la integración no lo activa y no envía tramos a la Observabilidad LLM.

                                    La integración de Vertex AI traza automáticamente la generación de contenido y las llamadas de mensajes de chat realizadas a través del SDK de Python de Vertex AI de Google.

                                    Métodos rastreados

                                    La integración de Vertex AI instrumenta los siguientes métodos:

                                    • Generando contenido (incluyendo llamadas transmitidas):

                                      • model.generate_content()
                                      • model.generate_content_async()

                                    • Mensajes de chat (incluyendo llamadas transmitidas):

                                      • chat.send_message()
                                      • chat.send_message_async()

                                    La integración de Vertex AI traza automáticamente la generación de contenido y las llamadas de mensajes de chat realizadas a través del SDK de Node.js de Vertex AI de Google.

                                    Métodos rastreados

                                    La integración de Vertex AI instrumenta los siguientes métodos:

                                    Habilitar o deshabilitar integraciones LLM

                                    Todas las integraciones están habilitadas por defecto.

                                    Deshabilitar todas las integraciones LLM

                                      Utiliza la configuración del SDK en código y especifica integrations_enabled=False.

                                      Ejemplo: Configuración del SDK en código que deshabilita todas las integraciones LLM

                                      from ddtrace.llmobs import LLMObs

LLMObs.enable(
  ml_app="<YOUR_ML_APP_NAME>",
  api_key="<YOUR_DATADOG_API_KEY>",
  integrations_enabled=False
)

                                      Utiliza la configuración del SDK en código y especifica plugins: false.

                                      Ejemplo: Configuración del SDK en código que desactiva todas las integraciones de LLM

                                      const tracer = require('dd-trace').init({
  llmobs: { ... },
  plugins: false
});
const { llmobs } = tracer;

                                      Solo habilitar integraciones específicas de LLM

                                        1. Utiliza la configuración del SDK en código y desactiva todas las integraciones con integrations_enabled=False.
                                        2. Habilita manualmente integraciones seleccionadas con ddtrace.patch().

                                        Ejemplo: Configuración del SDK en código que solo habilita la integración de LangChain

                                        from ddtrace import patch
from ddtrace.llmobs import LLMObs

LLMObs.enable(
  ml_app="<YOUR_ML_APP_NAME>",
  api_key="<YOUR_DATADOG_API_KEY>",
  integrations_enabled=False
)

patch(langchain=True)
                                        1. Utiliza la configuración del SDK en código y desactiva todas las integraciones con plugins: false.
                                        2. Habilita manualmente integraciones seleccionadas con use().

                                        Ejemplo: Configuración del SDK en código que solo habilita la integración de LangChain

                                        const tracer = require('dd-trace').init({
  llmobs: { ... },
  plugins: false
});
const { llmobs } = tracer;
tracer.use('langchain', true);

                                        Para un control más específico sobre la aplicación de parches a bibliotecas y la integración que inicia el tramo, puedes establecer las siguientes variables de entorno:

                                        DD_TRACE_DISABLED_PLUGINS
                                        Una cadena separada por comas de nombres de integraciones que se desactivan automáticamente cuando se inicializa el trazador.
                                        Ejemplo: DD_TRACE_DISABLED_PLUGINS=openai,http
                                        DD_TRACE_DISABLED_INSTRUMENTATIONS
                                        Una cadena separada por comas de nombres de bibliotecas que no se parchean cuando se inicializa el trazador.
                                        Ejemplo: DD_TRACE_DISABLED_INSTRUMENTATIONS=openai,http

                                        Lectura adicional

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

                                        Referencia del SDK de Observabilidad de LLMDOCUMENTATION more more Realice un seguimiento, compare y optimice sus prompts de LLM con LLM Observability de Datadog.BLOG more more Obtenga visibilidad de extremo a extremo en los clientes de MCP con Datadog LLM ObservabilityBLOG more more