Instrumentación automática para LLM Observability

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

Información general

Datadog LLM Observability puede rastrear automáticamente y anotar llamadas a frameworks y bibliotecas LLM compatibles a través de varias integraciones LLM. Cuando ejecutas tu aplicación LLM con el SDK de LLM Observability, estas integraciones LLM están habilitadas por defecto y proporcionan trazas y observabilidad predefinidas, sin que tengas que cambiar tu código.

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

Frameworks y bibliotecas compatibles

    FrameworkVersiones 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
    Vertex AI>= 1.71.1>= 2.18.0
    FrameworkVersiones 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)

    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 tus proyectos ESM, ejecuta tu aplicación con la siguiente opción de Node:

    --import dd-trace/register.js

    Para la configuración de la línea de comandos, utiliza 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 la incompatibilidad de módulos

    Si se producen errores al iniciar la aplicación cuando se utiliza esta opción, es probable que se trate de una incompatibilidad entre módulos. Puedes crear tu propio archivo hook con el módulo y el archivo en cuestión excluidos:

    // 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 utilizar este cargador personalizado, ejecuta tu aplicación con la siguiente opción de Node:

    --import ./hook.mjs

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

    esbuild

    Si utilizas esbuild, consulta Bundling with the Node.js tracer.

    Webpack

    Para Webpack, especifica 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'
  }
}

    Inicializa correctamente el rastreador en tu aplicación para garantizar que la autoinstrumentación funcione correctamente. Si utilizas TypeScript o ESM para tu aplicación Next.js, inicializa el rastreador en un archivo instrumentation.{ts/js} como se indica a continuación, especificando tus 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 CommonJS Next.js, puedes utilizar directamente la función init:

    // 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;

    A continuación, asegúrate de especificar dd-trace y cualquier otra integración compatible en serverExternalPackages en tu archivo next.config.{ts/js}:

    // next.config.ts
module.exports = {
  serverExternalPackages: ['dd-trace', 'openai'], // add any other supported integrations here to be auto-instrumented
}

    Integraciones LLM

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

      La integración con Amazon Bedrock proporciona instrumentación automática para las llamadas al modelo de chat del SDK de Amazon Bedrock Runtime Python (utilizando 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 rastreo de llamadas de incrustación.

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

      Métodos rastreados

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

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

        Métodos rastreados

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

        La integración de Amazon Bedrock Agents, por defecto, solo rastrea el método general InvokeAgent. Para habilitar el rastreo de los pasos dentro del agent, debes establecer enableTrace=True en los parámetros de solicitud de InvokeAgent.

          La integración de Anthropic proporciona un rastreo automático de las llamadas a mensajes de chat del SDK de Anthropic Python.

          Métodos rastreados

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

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

          Métodos rastreados

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

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

            Métodos rastreados

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

              La integración con Google ADK proporciona un rastreo automático de las ejecuciones de agents, llamadas a herramientas y ejecuciones de código realizadas a través del SDK de ADK Python de Google.

              Métodos rastreados

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

              Se admiten los métodos run_live y run_async.

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

                Nota: El SDK de Google GenAI Python tiene prioridad sobre el SDK de Google GenerativeAI, y expone tanto Gemini Developer API como Vertex.

                Métodos rastreados

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

                • Generación de contenidos (incluidas las llamadas retransmitidas):
                  • models.generate_content() (también captura chat.send_message())
                  • aio.models.generate_content() (también captura aio.chat.send_message())
                • Contenido incrustado -models.embed_content() -aio.models.embed_content()

                  La integración de LangChain proporciona rastreo automático para el LLM, el modelo de chat y las llamadas a la cadena del SDK de LangChain Python.

                  Métodos rastreados

                  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()

                  • Incrustaciones

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

                  • Herramientas

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

                  • Recuperación

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

                  • Plantillas para mensajes

                    • BasePromptTemplate.invoke(), BasePromptTemplate.ainvoke()
                    Para obtener mejores resultados, asigna plantillas a variables con nombres significativos. La instrumentación automática utiliza estos nombres para identificar las indicaciones.
                    # "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 rastreo automático para LLM del SDK de LangChain Node.js, modelo de chat, cadena y incrustaciones de llamadas a OpenAI.

                  Métodos rastreados

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

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

                    Métodos rastreados

                    La integración LangGraph instrumenta versiones síncronas y asíncronas de los siguientes métodos:

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

                      Métodos rastreados

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

                      • Finalizaciones del chat (incluidas las llamadas retransmitidas):
                        • litellm.completion
                        • litellm.acompletion
                      • Finalizaciones (incluidas las llamadas retransmitidas):
                        • litellm.text_completion
                        • litellm.atext_completion
                      • Finalizaciones del chat del enrutador (incluidas las llamadas retransmitidas):
                        • router.Router.completion
                        • router.Router.acompletion
                      • Finalizaciones de enrutadores (incluidas las llamadas retransmitidas):
                        • router.Router.text_completion
                        • router.Router.atext_completion

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

                        Métodos rastreados

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

                          La integración de OpenAI proporciona rastreo automático para la finalización del SDK de OpenAI Python y los endpoints de finalización de chat a OpenAI y Azure OpenAI.

                          Métodos rastreados

                          La integración de OpenAI instrumenta los siguientes métodos, incluidas las llamadas trasmitidas:

                          • 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 OpenAI Python (a partir de ddtrace==3.1.0)

                          La integración OpenAI proporciona rastreo automático para la finalización del SDK de OpenAI Node.js, finalización de chat, y endpoints de incrustaciones a OpenAI y Azure OpenAI.

                          Métodos rastreados

                          La integración de OpenAI instrumenta los siguientes métodos, incluidas las llamadas trasmitidas:

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

                            Se admiten las siguientes operaciones:

                              La integración de Pydantic AI instrumenta las invocaciones a agents y las llamadas a herramientas realizadas usando el framework de agents de Pydantic AI.

                              Métodos rastreados

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

                              • Invocaciones del Agent (incluidas las herramientas o conjuntos de herramientas asociados al agent):
                                • agent.Agent.iter (también rastrea agent.Agent.run y agent.Agent.run_sync)
                                • agent.Agent.run_stream

                                La integración del SDK de Vercel AI rastrea automáticamente la generación de texto y objetos, las incrustaciones y las llamadas a herramientas interceptando los tramos de OpenTelemetry creados por el núcleo subyacente del SDK de Vercel AI y convirtiéndolos en tramos de Datadog LLM Observability.

                                Métodos rastreados

                                Telemetría del SDK de Vercel AI Core

                                Esta integración parchea automáticamente el rastreador pasado en cada uno de los métodos rastreados bajo la opciónexperimental_telemetry. Si no se pasa ninguna configuración experimental_telemetry, la integración permite seguir enviando tramos de LLM Observability.

                                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 LLM Observability.

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

                                  Métodos rastreados

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

                                  • Generación de contenidos (incluidas las llamadas retransmitidas):

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

                                  • Mensajes de chat (incluidas las llamadas retransmitidas):

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

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

                                  Métodos rastreados

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

                                  Activar o desactivar las integraciones LLM

                                  Todas las integraciones están activadas por defecto.

                                  Desactivar todas las integraciones LLM

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

                                    Ejemplo: la configuración del SDK en el código que desactiva 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 el código y especifica plugins: false.

                                    Ejemplo: la configuración del SDK en el código que desactiva todas las integraciones LLM

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

                                    Habilitar solo integraciones LLM específicas

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

                                      Ejemplo: la configuración del SDK en el código que solo activa la integraciones 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 el código y desactiva todas las integraciones con plugins: false.
                                      2. Habilita manualmente determinadas integraciones con use().

                                      Ejemplo: la configuración del SDK en el código que solo activa la integraciones 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 el parcheo de 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 integración que se desactivan automáticamente cuando se inicializa el rastreador.
                                      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 rastreador.
                                      Ejemplo: DD_TRACE_DISABLED_INSTRUMENTATIONS=openai,http

                                      Referencias adicionales

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

                                      Referencia del SDK de LLM ObservabilityDOCUMENTACIÓN more more Sigue, compara y optimiza tus mensajes LLM con Datadog LLM ObservabilityBLOG more more Obtén visibilidad de principio a fin de los clientes MCP con Datadog LLM ObservabilityBLOG more more