Referencia del SDK de LLM Observability

Documentos > Observabilidad de LLM > Instrumentación de LLM Observability > Referencia del SDK de LLM Observability

Resumen

Los SDK de Datadog LLM Observability proporcionan instrumentación automática, así como APIs de instrumentación manual, para ofrecer observabilidad y perspectivas en tus aplicaciones LLM.

Configuración

Requisitos

Una clave de API de Datadog.

El último paquete ddtrace está instalado (se requiere Python 3.7+):
```
pip install ddtrace
```

El último paquete dd-trace está instalado (se requiere Node.js 16+):
```
npm install dd-trace
```

Has descargado el último dd-trace-java JAR. El SDK de Datadog LLM Observability es compatible con dd-trace-java v1.51.0+ (se requiere Java 8+).

Configuración desde la línea de comandos

Habilita LLM Observability ejecutando tu aplicación usando el comando ddtrace-run y especificando las variables de entorno requeridas.

Nota: ddtrace-run activa automáticamente todas las integraciones de LLM Observability.

DD_SITE=<YOUR_DATADOG_SITE> DD_API_KEY=<YOUR_API_KEY> DD_LLMOBS_ENABLED=1 \
DD_LLMOBS_ML_APP=<YOUR_ML_APP_NAME> ddtrace-run <YOUR_APP_STARTUP_COMMAND>

Variables de entorno para la configuración de línea de comandos

DD_SITE: requerido - cadena
Sitio de Datadog de destino para el envío de datos LLM. Tu sitio es .
DD_LLMOBS_ENABLED: requerido - entero o cadena
Alternar para habilitar el envío de datos a LLM Observability. Debería estar configurado en 1 o true.
DD_LLMOBS_ML_APP: opcional - cadena
El nombre de su aplicación, servicio o proyecto LLM, bajo el cual se agrupan todas las trazas y tramos. Esto ayuda a distinguir entre diferentes aplicaciones o experimentos. Consulte Directrices de nomenclatura de aplicaciones para caracteres permitidos y otras restricciones. Para anular este valor para un tramo raíz dado, consulte Rastreo de múltiples aplicaciones. Si no se proporciona, esto se establece de forma predeterminada en el valor de DD_SERVICE, o el valor de un DD_LLMOBS_ML_APP propagado desde un servicio ascendente.
Nota: Antes de la versión ddtrace==3.14.0, este es un campo requerido.
DD_LLMOBS_AGENTLESS_ENABLED: opcional - entero o cadena - predeterminado: false
Solo es necesario si no está utilizando el Agente de Datadog, en cuyo caso esto debe configurarse en 1 o true.
DD_API_KEY: opcional - cadena
Su clave de API de Datadog. Solo es necesario si no está utilizando el Agente de Datadog.

Habilite LLM Observability ejecutando su aplicación con NODE_OPTIONS="--import dd-trace/initialize.mjs" y especificando las variables de entorno requeridas.

Nota: dd-trace/initialize.mjs activa automáticamente todas las integraciones de APM.

DD_SITE=<YOUR_DATADOG_SITE> DD_API_KEY=<YOUR_API_KEY> DD_LLMOBS_ENABLED=1 \
DD_LLMOBS_ML_APP=<YOUR_ML_APP_NAME> NODE_OPTIONS="--import dd-trace/initialize.mjs" node <YOUR_APP_ENTRYPOINT>

Variables de entorno para la configuración de línea de comandos

DD_SITE: requerido - cadena
El sitio de Datadog para enviar sus datos LLM. Su sitio es .
DD_LLMOBS_ENABLED: requerido - entero o cadena
Alternar para habilitar el envío de datos a LLM Observability. Debería estar configurado en 1 o true.
DD_LLMOBS_ML_APP: opcional - cadena
El nombre de su aplicación, servicio o proyecto LLM, bajo el cual se agrupan todas las trazas y tramos. Esto ayuda a distinguir entre diferentes aplicaciones o experimentos. Consulte Directrices de nomenclatura de aplicaciones para caracteres permitidos y otras restricciones. Para anular este valor para un tramo raíz dado, consulte Rastreo de múltiples aplicaciones. Si no se proporciona, esto se establece de forma predeterminada en el valor de DD_SERVICE, o el valor de un DD_LLMOBS_ML_APP propagado desde un servicio ascendente.
Nota: Antes de la versión dd-trace@5.66.0, este es un campo requerido.
DD_LLMOBS_AGENTLESS_ENABLED: opcional - entero o cadena - predeterminado: false
Solo es necesario si no está utilizando el Agente de Datadog, en cuyo caso esto debe configurarse en 1 o true.
DD_API_KEY: opcional - cadena
Su clave de API de Datadog. Solo es necesario si no está utilizando el Agente de Datadog.

Habilite LLM Observability ejecutando su aplicación con dd-trace-java y especificando los parámetros requeridos como variables de entorno o propiedades del sistema.

DD_SITE=<YOUR_DATADOG_SITE> DD_API_KEY=<YOUR_API_KEY> \
java -javaagent:path/to/your/dd-trace-java-jar/dd-java-agent-SNAPSHOT.jar \
-Ddd.service=my-app -Ddd.llmobs.enabled=true -Ddd.llmobs.ml.app=my-ml-app -jar path/to/your/app.jar

Variables de entorno y propiedades del sistema

Puede proporcionar los siguientes parámetros como variables de entorno (por ejemplo, DD_LLMOBS_ENABLED) o como propiedades del sistema Java (por ejemplo, dd.llmobs_enabled).

DD_SITE o dd.site: requerido - cadena
Sitio de Datadog de destino para la presentación de datos LLM. Tu sitio es .
DD_LLMOBS_ENABLED o dd.llmobs.enabled: requerido - entero o cadena
Alternar para habilitar el envío de datos a la Observabilidad LLM. Debería configurarse en 1 o true.
DD_LLMOBS_ML_APP o dd.llmobs.ml.app: opcional - cadena
El nombre de su aplicación, servicio o proyecto LLM, bajo el cual se agrupan todas las trazas y tramos. Esto ayuda a distinguir entre diferentes aplicaciones o experimentos. Consulte Directrices de nomenclatura de aplicaciones para los caracteres permitidos y otras restricciones. Para anular este valor para un tramo raíz dado, consulte Rastreo de múltiples aplicaciones. Si no se proporciona, esto se establece de forma predeterminada al valor de DD_SERVICE, o al valor de un DD_LLMOBS_ML_APP propagado desde un servicio ascendente.
Nota: Antes de la versión 1.54.0 de dd-trace-java, este es un campo requerido.
DD_LLMOBS_AGENTLESS_ENABLED o dd.llmobs.agentless.enabled: opcional - entero o cadena - predeterminado: false
Solo es necesario si no está utilizando el Agente de Datadog, en cuyo caso esto debe establecerse en 1 o true.
DD_API_KEY o dd.api.key: opcional - cadena
Su clave de API de Datadog. Solo es necesario si no está utilizando el Agente de Datadog.

Configuración en código

En lugar de usar configuración de línea de comandos, también puede habilitar LLM Observability programáticamente.

Utilice la función LLMObs.enable() para habilitar LLM Observability.

No utilice este método de configuración con el comando ddtrace-run.

from ddtrace.llmobs import LLMObs
LLMObs.enable(
  ml_app="<YOUR_ML_APP_NAME>",
  api_key="<YOUR_DATADOG_API_KEY>",
  site="<YOUR_DATADOG_SITE>",
  agentless_enabled=True,
)

Parámetros

ml_app: opcional - cadena
El nombre de su aplicación, servicio o proyecto LLM, bajo el cual se agrupan todas las trazas y tramos. Esto ayuda a distinguir entre diferentes aplicaciones o experimentos. Consulte Directrices de nomenclatura de aplicaciones para caracteres permitidos y otras restricciones. Para anular este valor para una traza dada, consulte Rastreo de múltiples aplicaciones. Si no se proporciona, este valor predeterminado es el de DD_LLMOBS_ML_APP.
integrations_enabled - predeterminado: true: opcional - booleano
Una bandera para habilitar el rastreo automático de llamadas LLM para las integraciones de LLM soportadas por Datadog integraciones de LLM. Si no se proporciona, todas las integraciones de LLM soportadas están habilitadas por defecto. Para evitar el uso de las integraciones de LLM, establezca este valor en false.
agentless_enabled: opcional - booleano - predeterminado: false
Solo es necesario si no está utilizando el Agente de Datadog, en cuyo caso este debe establecerse en True. Esto configura la biblioteca ddtrace para no enviar ningún dato que requiera el Agente de Datadog. Si no se proporciona, este valor predeterminado es el de DD_LLMOBS_AGENTLESS_ENABLED.
site: opcional - cadena
El sitio de Datadog para enviar sus datos LLM. Tu sitio es . Si no se proporciona, esto se establece de forma predeterminada al valor de DD_SITE.
api_key: opcional - cadena
Tu clave de API de Datadog. Solo es necesario si no está utilizando el Datadog Agent. Si no se proporciona, esto se establece de forma predeterminada al valor de DD_API_KEY.
env: opcional - cadena
El nombre del entorno de tu aplicación (ejemplos: prod, pre-prod, staging). Si no se proporciona, esto se establece de forma predeterminada al valor de DD_ENV.
service: opcional - cadena
El nombre del servicio utilizado para tu aplicación. Si no se proporciona, esto se establece de forma predeterminada al valor de DD_SERVICE.

No utilices este método de configuración con el comando dd-trace/initialize.mjs.

Utilice la init() función para habilitar LLM Observability.

const tracer = require('dd-trace').init({
  llmobs: {
    mlApp: "<YOUR_ML_APP_NAME>",
    agentlessEnabled: true,
  },
  site: "<YOUR_DATADOG_SITE>",
  env: "<YOUR_ENV>",
});

const llmobs = tracer.llmobs;

Opciones para la llmobsconfiguración

mlApp: opcional - cadena
El nombre de tu aplicación LLM, servicio o proyecto, bajo el cual se agrupan todas las trazas y tramos. Esto ayuda a distinguir entre diferentes aplicaciones o experimentos. Consulta Directrices de nomenclatura de aplicaciones para caracteres permitidos y otras restricciones. Para anular este valor para una traza dada, consulta Trazando múltiples aplicaciones. Si no se proporciona, esto se establece de forma predeterminada al valor de DD_LLMOBS_ML_APP.
agentlessEnabled: opcional - booleano - predeterminado: false
Solo es necesario si no estás utilizando el Datadog Agent, en cuyo caso esto debe establecerse en true. Esto configura la dd-trace biblioteca para no enviar ningún dato que requiera el Datadog Agent. Si no se proporciona, esto se establece en el valor de DD_LLMOBS_AGENTLESS_ENABLED.

Opciones para la configuración general del rastreador:

site: opcional - cadena
El sitio de Datadog para enviar tus datos de LLM. Tu sitio es . Si no se proporciona, esto se establece de forma predeterminada al valor de DD_SITE.
env: opcional - cadena
El nombre del entorno de tu aplicación (ejemplos: prod, pre-prod, staging). Si no se proporciona, esto se establece en el valor de DD_ENV.
service: opcional - cadena
El nombre del servicio utilizado para tu aplicación. Si no se proporciona, esto se establece de forma predeterminada al valor de DD_SERVICE.

Variables de entorno

Establece los siguientes valores como variables de entorno. No se pueden configurar programáticamente.

DD_API_KEY: opcional - cadena
Tu clave de API de Datadog. Solo es necesario si no está utilizando el Datadog Agent.

Configuración de AWS Lambda

Para instrumentar una función existente de AWS Lambda con LLM Observability, puedes usar la Datadog Extension y las respectivas capas de lenguaje.

Abre un Cloudshell en la consola de AWS.
Instala el cliente de la CLI de Datadog

npm install -g @datadog/datadog-ci

Establece la clave de API de Datadog y el sitio

export DD_API_KEY=<YOUR_DATADOG_API_KEY>
export DD_SITE=<YOUR_DATADOG_SITE>

Si ya tienes o prefieres usar un secreto en el Administrador de Secretos, puedes establecer la clave de API utilizando el ARN del secreto:

export DATADOG_API_KEY_SECRET_ARN=<DATADOG_API_KEY_SECRET_ARN>

Instala tu función Lambda con LLM Observability (esto requiere al menos la versión 77 de la Datadog Extension layer)

datadog-ci lambda instrument -f <YOUR_LAMBDA_FUNCTION_NAME> -r <AWS_REGION> -v 123 -e 94 --llmobs <YOUR_LLMOBS_ML_APP>

datadog-ci lambda instrument -f <YOUR_LAMBDA_FUNCTION_NAME> -r <AWS_REGION> -v 136 -e 94 --llmobs <YOUR_LLMOBS_ML_APP>

datadog-ci lambda instrument -f <YOUR_LAMBDA_FUNCTION_NAME> -r <AWS_REGION> -v 26 -e 94 --llmobs <YOUR_LLMOBS_ML_APP>

Invoca tu función Lambda y verifica que las trazas de LLM Observability sean visibles en la interfaz de usuario de Datadog.

Limpia manualmente las trazas de LLM Observability utilizando el método flush antes de que la función Lambda regrese.

from ddtrace.llmobs import LLMObs
def handler():
  # function body
  LLMObs.flush()

import tracer from 'dd-trace';
const llmobs = tracer.llmobs;

export const handler = async (event) => {
  // your function body
  llmobs.flush();
};

Después de instalar el SDK y ejecutar tu aplicación, deberías esperar ver algunos datos en LLM Observability provenientes de la instrumentación automática. La instrumentación manual puede ser utilizada para capturar marcos personalizados o operaciones de bibliotecas que aún no están soportadas.

Instrumentación manual

Para capturar una operación de LLM, se puede usar un decorador de función para instrumentar fácilmente los flujos de trabajo:

from ddtrace.llmobs.decorators import workflow

@workflow
def handle_user_request():
    ...

o un enfoque basado en un administrador de contexto para capturar operaciones granulares:

from ddtrace.llmobs import LLMObs

with LLMObs.llm(model="gpt-4o"):
    call_llm()
    LLMObs.annotate(
        metrics={
            "input_tokens": ...,
            "output_tokens": ...,
        },
    )

Para una lista de tipos de tramos disponibles, consulta la documentación de Tipos de tramos. Para un trazado más granular de operaciones dentro de funciones, consulta Trazado de tramos utilizando métodos en línea.

Para trazar un tramo, utiliza llmobs.wrap(options, function) como envoltorio de función para la función que deseas trazar. Para una lista de tipos de tramos disponibles, consulta la documentación de Tipos de tramos. Para un trazado más granular de operaciones dentro de funciones, consulta Trazado de tramos utilizando métodos en línea.

Tipos de tramos

Los tipos de tramos son requeridos y se especifican en el objeto options pasado a las funciones de trazado llmobs (trace, wrap y decorate). Consulta la documentación de Tipos de tramos para una lista de tipos de tramos soportados.

Nota: Los tramos con un tipo de tramo inválido no se envían a LLM Observability.

Captura automática de argumentos/salida/nombre de función

llmobs.wrap (junto con llmobs.decorate para TypeScript) intenta capturar automáticamente las entradas, salidas y el nombre de la función que se está rastreando. Si necesitas anotar manualmente un tramo, consulta Enriqueciendo tramos. Las entradas y salidas que anotes anularán la captura automática. Además, para anular el nombre de la función, pasa la propiedad name en el objeto de opciones a la función llmobs.wrap:

function processMessage () {
  ... // user application logic
  return
}
processMessage = llmobs.wrap({ kind: 'workflow', name: 'differentFunctionName' }, processMessage)

Condiciones para finalizar un tramo para una función envuelta

llmobs.wrap extiende el comportamiento subyacente de tracer.wrap. El tramo subyacente creado cuando se llama a la función se finaliza bajo las siguientes condiciones:

Si la función devuelve una Promesa, entonces el tramo finaliza cuando la promesa se resuelve o se rechaza.
Si la función toma un callback como su último parámetro, entonces el tramo finaliza cuando se llama a ese callback.
Si la función no acepta un callback y no devuelve una Promesa, entonces el tramo finaliza al final de la ejecución de la función.

El siguiente ejemplo demuestra la segunda condición, donde el último argumento es un callback:

Ejemplo

const express = require('express')
const app = express()

function myAgentMiddleware (req, res, next) {
  const err = ... // user application logic
  // the span for this function is finished when `next` is called
  next(err)
}
myAgentMiddleware = llmobs.wrap({ kind: 'agent' }, myAgentMiddleware)

app.use(myAgentMiddleware)

Si la aplicación no utiliza la función de callback, se recomienda usar un bloque trazado en línea en su lugar. Consulta Trazando tramos usando métodos en línea para más información.

const express = require('express')
const app = express()

function myAgentMiddleware (req, res) {
  // the `next` callback is not being used here
  return llmobs.trace({ kind: 'agent', name: 'myAgentMiddleware' }, () => {
    return res.status(200).send('Hello World!')
  })
}

app.use(myAgentMiddleware)

Iniciando un tramo

Existen múltiples métodos para iniciar un tramo, según el tipo de tramo que estés iniciando. Consulta la documentación de Tipos de tramos para una lista de tipos de tramos soportados.

Todos los tramos se inician como una instancia de objeto de LLMObsSpan. Cada tramo tiene métodos que puedes usar para interactuar con el tramo y registrar datos.

Finalizando un tramo

Los tramos deben ser finalizados para que la traza sea enviada y visible en la aplicación de Datadog.

Para finalizar un tramo, llama a finish() en una instancia del objeto tramo. Si es posible, envuelve el tramo en un bloque de try/finally para asegurar que el tramo se envíe incluso si ocurre una excepción.

Ejemplo

    try {
        LLMObsSpan workflowSpan = LLMObs.startWorkflowSpan("my-workflow-span-name", "ml-app-override", "session-141");
        // user logic
        // interact with started span
    } finally {
      workflowSpan.finish();
    }

llamadas a LLM

Si estás utilizando algún proveedor o marco de LLM que sea compatible con las integraciones de LLM de Datadog, no necesitas iniciar manualmente un tramo de LLM para trazar estas operaciones.

Para trazar una llamada a LLM, utiliza el decorador de función ddtrace.llmobs.decorators.llm().

Argumentos

model_name: requerido - cadena
El nombre del LLM invocado.
name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se predetermina al nombre de la función trazada.
model_provider: opcional - cadena - predeterminado: "custom"
El nombre del proveedor del modelo.
Nota: Para mostrar el costo estimado en dólares estadounidenses, establece model_provider en uno de los siguientes valores: openai, azure_openai o anthropic.
session_id: opcional - cadena
El ID de la sesión de usuario subyacente. Consulte Seguimiento de sesiones de usuario para más información.
ml_app: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

from ddtrace.llmobs.decorators import llm

@llm(model_name="claude", name="invoke_llm", model_provider="anthropic")
def llm_call():
    completion = ... # user application logic to invoke LLM
    return completion

Para rastrear una llamada de LLM, especifique el tipo de tramo como llm, y opcionalmente especifique los siguientes argumentos en el objeto de opciones.

Argumentos

modelName: opcional - cadena - predeterminado: "custom"
El nombre del LLM invocado.
name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se predetermina al nombre de la función rastreada.
modelProvider: opcional - cadena - predeterminado: "custom"
El nombre del proveedor del modelo.
Nota: Para mostrar el costo estimado en dólares estadounidenses, establezca modelProvider en uno de los siguientes valores: openai, azure_openai o anthropic.
sessionId: opcional - cadena
El ID de la sesión de usuario subyacente. Consulte Seguimiento de sesiones de usuario para más información.
mlApp: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

function llmCall () {
  const completion = ... // user application logic to invoke LLM
  return completion
}
llmCall = llmobs.wrap({ kind: 'llm', name: 'invokeLLM', modelName: 'claude', modelProvider: 'anthropic' }, llmCall)

Para rastrear una llamada de LLM, importe y llame al siguiente método con los argumentos que se enumeran a continuación:

import datadog.trace.api.llmobs.LLMObs;
LLMObs.startLLMSpan(spanName, modelName, modelProvider, mlApp, sessionID);

Argumentos

spanName: opcional - cadena
El nombre de la operación. Si no se proporciona, spanName se establece en el tipo de tramo.
modelName: opcional - cadena - predeterminado: "custom"
El nombre del LLM invocado.
modelProvider: opcional - cadena - predeterminado: "custom"
El nombre del proveedor del modelo.
Nota: Para mostrar el costo estimado en dólares estadounidenses, establezca modelProvider en uno de los siguientes valores: openai, azure_openai o anthropic.
mlApp: opcional - Cadena
El nombre de la aplicación de ML a la que pertenece la operación. Proporcionar un valor no nulo anula el nombre de la aplicación de ML proporcionado al inicio de la aplicación. Consulte Rastreo de múltiples aplicaciones para más información.
sessionId: opcional - Cadena
El ID de la sesión de usuario subyacente. Consulte Seguimiento de sesiones de usuario para más información.

Ejemplo

import datadog.trace.api.llmobs.LLMObs;

public class MyJavaClass {
  public String invokeModel() {
    LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
    String inference = ... // user application logic to invoke LLM
    llmSpan.annotateIO(...); // record the input and output
    llmSpan.finish();
    return inference;
  }
}

Flujos de trabajo

Para rastrear un tramo de flujo de trabajo, use el decorador de función ddtrace.llmobs.decorators.workflow().

Argumentos

name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece en el nombre de la función rastreada.
session_id: opcional - cadena
El ID de la sesión de usuario subyacente. Consulte Seguimiento de sesiones de usuario para más información.
ml_app: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

from ddtrace.llmobs.decorators import workflow

@workflow
def process_message():
    ... # user application logic
    return

Para rastrear un tramo de flujo de trabajo, especifique el tipo de tramo como workflow, y opcionalmente especifique argumentos en el objeto de opciones.

Argumentos

name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece en el nombre de la función rastreada.
sessionId: opcional - cadena
El ID de la sesión de usuario subyacente. Consulte Seguimiento de sesiones de usuario para más información.
mlApp: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

function processMessage () {
  ... // user application logic
  return
}
processMessage = llmobs.wrap({ kind: 'workflow' }, processMessage)

Para rastrear un tramo de flujo de trabajo, importe y llame al siguiente método con los argumentos que se enumeran a continuación:

import datadog.trace.api.llmobs.LLMObs;
LLMObs.startWorkflowSpan(spanName, mlApp, sessionID);

Argumentos

spanName: opcional - Cadena
El nombre de la operación. Si no se proporciona, spanName se establece en el tipo de tramo.
mlApp: opcional - Cadena
El nombre de la aplicación de ML a la que pertenece la operación. Proporcionar un valor no nulo anula el nombre de la aplicación de ML proporcionado al inicio de la aplicación. Vea Rastreo de múltiples aplicaciones para más información.
sessionId: opcional - Cadena
El ID de la sesión de usuario subyacente. Vea Seguimiento de sesiones de usuario para más información.

Ejemplo

import datadog.trace.api.llmobs.LLMObs;

public class MyJavaClass {
  public String executeWorkflow() {
    LLMObsSpan workflowSpan = LLMObs.startWorkflowSpan("my-workflow-span-name", null, "session-141");
    String workflowResult = workflowFn(); // user application logic
    workflowSpan.annotateIO(...); // record the input and output
    workflowSpan.finish();
    return workflowResult;
  }
}

Agentes

Para rastrear la ejecución de un agente, use el decorador de función ddtrace.llmobs.decorators.agent().

Argumentos

name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece en el nombre de la función rastreada.
session_id: opcional - cadena
El ID de la sesión de usuario subyacente. Vea Seguimiento de sesiones de usuario para más información.
ml_app: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Vea Rastreo de múltiples aplicaciones para más información.

Ejemplo

from ddtrace.llmobs.decorators import agent

@agent
def react_agent():
    ... # user application logic
    return

Para rastrear la ejecución de un agente, especifique el tipo de tramo como agent, y opcionalmente especifique argumentos en el objeto de opciones.

Argumentos

name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece en el nombre de la función rastreada.
sessionId: opcional - cadena
El ID de la sesión de usuario subyacente. Vea Seguimiento de sesiones de usuario para más información.
mlApp: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Vea Rastreo de múltiples aplicaciones para más información.

Ejemplo

function reactAgent () {
  ... // user application logic
  return
}
reactAgent = llmobs.wrap({ kind: 'agent' }, reactAgent)

Para rastrear la ejecución de un agente, importe y llame al siguiente método con los argumentos que se enumeran a continuación

import datadog.trace.api.llmobs.LLMObs;
LLMObs.startAgentSpan(spanName, mlApp, sessionID);

Argumentos

spanName: opcional - Cadena
El nombre de la operación. Si no se proporciona, spanName se establece en el nombre de la función rastreada.
mlApp: opcional - Cadena
El nombre de la aplicación de ML a la que pertenece la operación. Proporcionar un valor no nulo anula el nombre de la aplicación de ML proporcionado al inicio de la aplicación. Vea Rastreo de múltiples aplicaciones para más información.
sessionId: opcional - Cadena
El ID de la sesión de usuario subyacente. Vea Seguimiento de sesiones de usuario para más información.

Llamadas a herramientas

Para rastrear una llamada a una herramienta, use el decorador de función ddtrace.llmobs.decorators.tool().

Argumentos

name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece en el nombre de la función rastreada.
session_id: opcional - cadena
El ID de la sesión de usuario subyacente. Vea Seguimiento de sesiones de usuario para más información.
ml_app: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Vea Rastreo de múltiples aplicaciones para más información.

Ejemplo

from ddtrace.llmobs.decorators import tool

@tool
def call_weather_api():
    ... # user application logic
    return

Para rastrear una llamada a una herramienta, especifique el tipo de tramo como tool, y opcionalmente especifique argumentos en el objeto de opciones.

Argumentos

name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece en el nombre de la función rastreada.
sessionId: opcional - cadena
El ID de la sesión de usuario subyacente. Consulte Seguimiento de sesiones de usuario para más información.
mlApp: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

function callWeatherApi () {
  ... // user application logic
  return
}
callWeatherApi = llmobs.wrap({ kind: 'tool' }, callWeatherApi)

Para rastrear una llamada a una herramienta, importa y llama al siguiente método con los argumentos que se enumeran a continuación:

import datadog.trace.api.llmobs.LLMObs;
LLMObs.startToolSpan(spanName, mlApp, sessionID);

Argumentos

spanName: opcional - Cadena
El nombre de la operación. Si no se proporciona, spanName se establece en el nombre de la función rastreada.
mlApp: opcional - Cadena
El nombre de la aplicación de ML a la que pertenece la operación. Proporcionar un valor no nulo anula el nombre de la aplicación de ML proporcionado al inicio de la aplicación. Vea Rastreo de múltiples aplicaciones para más información.
sessionId: opcional - Cadena
El ID de la sesión de usuario subyacente. Vea Seguimiento de sesiones de usuario para más información.

Tareas

Para rastrear un tramo de tarea, utiliza el decorador de función LLMObs.task().

Argumentos

name: opcional - Cadena
El nombre de la operación. Si no se proporciona, name se establece en el nombre de la función rastreada.
session_id: opcional - Cadena
El ID de la sesión de usuario subyacente. Vea Seguimiento de sesiones de usuario para más información.
ml_app: opcional - Cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

from ddtrace.llmobs.decorators import task

@task
def sanitize_input():
    ... # user application logic
    return

Para rastrear un tramo de tarea, especifique el tipo de tramo como task, y opcionalmente especifique argumentos en el objeto de opciones.

Argumentos

name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece de forma predeterminada en el nombre de la función rastreada.
sessionId: opcional - cadena
El ID de la sesión de usuario subyacente. Consulte Rastreo de sesiones de usuario para más información.
mlApp: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

function sanitizeInput () {
  ... // user application logic
  return
}
sanitizeInput = llmobs.wrap({ kind: 'task' }, sanitizeInput)

Para rastrear un tramo de tarea, importe y llame al siguiente método con los argumentos que se enumeran a continuación:

import datadog.trace.api.llmobs.LLMObs;
LLMObs.startTaskSpan(spanName, mlApp, sessionID);

Argumentos

spanName: opcional - Cadena
El nombre de la operación. Si no se proporciona, spanName se establece de forma predeterminada en el nombre de la función rastreada.
mlApp: opcional - Cadena
El nombre de la aplicación de ML a la que pertenece la operación. Proporcionar un valor no nulo anula el nombre de la aplicación de ML suministrado al inicio de la aplicación. Consulte Rastreo de múltiples aplicaciones para más información.
sessionId: opcional - Cadena
El ID de la sesión de usuario subyacente. Consulte Rastreo de sesiones de usuario para más información.

Embeddings

Para rastrear una operación de embedding, use el decorador de función LLMObs.embedding().

Nota: Anotar la entrada de un tramo de embedding requiere un formato diferente al de otros tipos de tramo. Consulte Enriqueciendo tramos para más detalles sobre cómo especificar entradas de embedding.

Argumentos

model_name: requerido - cadena
El nombre del LLM invocado.
name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece en el nombre de la función rastreada.
model_provider: opcional - cadena - predeterminado: "custom"
session_id: opcional - cadena
El ID de la sesión de usuario subyacente. Consulte Rastreo de sesiones de usuario para más información.
ml_app: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

from ddtrace.llmobs.decorators import embedding

@embedding(model_name="text-embedding-3", model_provider="openai")
def perform_embedding():
    ... # user application logic
    return

Para rastrear una operación de embedding, especifique el tipo de tramo como embedding, y opcionalmente especifique argumentos en el objeto de opciones.

Argumentos

modelName: opcional - cadena - predeterminado: "custom"
El nombre del LLM invocado.
name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece en el nombre de la función rastreada.
modelProvider: opcional - cadena - predeterminado: "custom"
El nombre del proveedor del modelo.
sessionId: opcional - cadena
El ID de la sesión de usuario subyacente. Consulte Rastreo de sesiones de usuario para más información.
mlApp: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

function performEmbedding () {
  ... // user application logic
  return
}
performEmbedding = llmobs.wrap({ kind: 'embedding', modelName: 'text-embedding-3', modelProvider: 'openai' }, performEmbedding)

Recuperaciones

Para rastrear un tramo de recuperación, use el decorador de función ddtrace.llmobs.decorators.retrieval().

Nota: Anotar la salida de un tramo de recuperación requiere un formato diferente al de otros tipos de tramo. Vea Enriqueciendo tramos para más detalles sobre cómo especificar salidas de recuperación.

Argumentos

name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece de forma predeterminada en el nombre de la función rastreada.
session_id: opcional - cadena
El ID de la sesión de usuario subyacente. Consulte Rastreo de sesiones de usuario para más información.
ml_app: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

from ddtrace.llmobs.decorators import retrieval

@retrieval
def get_relevant_docs(question):
    context_documents = ... # user application logic
    LLMObs.annotate(
        input_data=question,
        output_data = [
            {"id": doc.id, "score": doc.score, "text": doc.text, "name": doc.name} for doc in context_documents
        ]
    )
    return

Para rastrear un tramo de recuperación, especifique el tipo de tramo como retrieval, y opcionalmente especifique los siguientes argumentos en el objeto de opciones.

Nota: Anotar la salida de un tramo de recuperación requiere un formato diferente al de otros tipos de tramo. Consulte Enriqueciendo tramos para más detalles sobre cómo especificar salidas de recuperación.

Argumentos

name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece de forma predeterminada en el nombre de la función rastreada.
sessionId: opcional - cadena
El ID de la sesión de usuario subyacente. Consulte Rastreo de sesiones de usuario para más información.
mlApp: opcional - cadena
El nombre de la aplicación de ML a la que pertenece la operación. Consulte Rastreo de múltiples aplicaciones para más información.

Ejemplo

Lo siguiente también incluye un ejemplo de anotación de un tramo. Consulte Enriqueciendo tramos para más información.

function getRelevantDocs (question) {
  const contextDocuments = ... // user application logic
  llmobs.annotate({
    inputData: question,
    outputData: contextDocuments.map(doc => ({
      id: doc.id,
      score: doc.score,
      text: doc.text,
      name: doc.name
    }))
  })
  return
}
getRelevantDocs = llmobs.wrap({ kind: 'retrieval' }, getRelevantDocs)

Anidando tramos

Iniciar un nuevo tramo antes de que el tramo actual haya terminado traza automáticamente una relación padre-hijo entre los dos tramos. El tramo padre representa la operación más grande, mientras que el tramo hijo representa una suboperación más pequeña anidada dentro de ella.

from ddtrace.llmobs.decorators import task, workflow

@workflow
def extract_data(document):
    preprocess_document(document)
    ... # performs data extraction on the document
    return

@task
def preprocess_document(document):
    ... # preprocesses a document for data extraction
    return

function preprocessDocument (document) {
  ... // preprocesses a document for data extraction
  return
}
preprocessDocument = llmobs.wrap({ kind: 'task' }, preprocessDocument)

function extractData (document) {
  preprocessDocument(document)
  ... // performs data extraction on the document
  return
}
extractData = llmobs.wrap({ kind: 'workflow' }, extractData)

import datadog.trace.api.llmobs.LLMObs;
import datadog.trace.api.llmobs.LLMObsSpan;

public class MyJavaClass {
  public void preprocessDocument(String document) {
  LLMObsSpan taskSpan = LLMObs.startTaskSpan("preprocessDocument", null, "session-141");
   ...   // preprocess document for data extraction
   taskSpan.annotateIO(...); // record the input and output
   taskSpan.finish();
  }

  public String extractData(String document) {
    LLMObsSpan workflowSpan = LLMObs.startWorkflowSpan("extractData", null, "session-141");
    preprocessDocument(document);
    ... // perform data extraction on the document
    workflowSpan.annotateIO(...); // record the input and output
    workflowSpan.finish();
  }
}

Enriqueciendo tramos

El parámetro métricas aquí se refiere a valores numéricos adjuntos como atributos en tramos individuales — no métricas de la plataforma Datadog. Para ciertas claves reconocidas como input_tokens, output_tokens, y total_tokens, Datadog utiliza estos atributos de tramo para generar métricas de plataforma correspondientes (como ml_obs.span.llm.input.tokens) para su uso en tableros y seguimientos.

El SDK proporciona el método LLMObs.annotate() para enriquecer tramos con entradas, salidas y metadatos.

El método LLMObs.annotate() acepta los siguientes argumentos:

Argumentos

span: opcional - Tramo - predeterminado: el tramo activo actual
El tramo a anotar. Si span no se proporciona (como cuando se utilizan decoradores de función), el SDK anota el tramo activo actual.
input_data: opcional - tipo serializable de JSON o lista de diccionarios
Ya sea un tipo serializable de JSON (para tramos que no son LLM) o una lista de diccionarios con este formato: {"content": "...", "role": "...", "tool_calls": ..., "tool_results": ...}, donde "tool_calls" son una lista opcional de diccionarios de llamadas a herramientas con claves requeridas: "name", "arguments", y claves opcionales: "tool_id", "type", y "tool_results" son una lista opcional de diccionarios de resultados de herramientas con clave requerida: "result", y claves opcionales: "name", "tool_id", "type" para escenarios de llamadas a funciones. Nota: Los tramos de incrustación son un caso especial y requieren una cadena o un diccionario (o una lista de diccionarios) con este formato: {"text": "..."}.
output_data: opcional - tipo serializable de JSON o lista de diccionarios
Ya sea un tipo serializable de JSON (para tramos que no son LLM) o una lista de diccionarios con este formato: {"content": "...", "role": "...", "tool_calls": ...}, donde "tool_calls" son una lista opcional de diccionarios de llamadas a herramientas con claves requeridas: "name", "arguments", y claves opcionales: "tool_id", "type" para escenarios de llamadas a funciones. Nota: Los tramos de recuperación son un caso especial y requieren una cadena o un diccionario (o una lista de diccionarios) con este formato: {"text": "...", "name": "...", "score": float, "id": "..."}.
tool_definitions: opcional - lista de diccionarios
Lista de diccionarios de definición de herramientas para escenarios de llamadas a funciones. Cada definición de herramienta debe tener una clave "name": "..." requerida y claves opcionales "description": "..." y "schema": {...}.
metadata: opcional - diccionario
Un diccionario de pares clave-valor serializables de JSON que los usuarios pueden agregar como información de metadatos relevante para la operación de entrada o salida descrita por el tramo (model_temperature, max_tokens, top_k, etc.).
metrics: opcional - diccionario
Un diccionario de claves serializables de JSON y valores numéricos que los usuarios pueden agregar como métricas relevantes para la operación descrita por el tramo (input_tokens, output_tokens, total_tokens, time_to_first_token, etc.). La unidad para time_to_first_token está en segundos, similar a la métrica duration que se emite por defecto.
tags: opcional - diccionario
Un diccionario de pares clave-valor serializables en JSON que los usuarios pueden agregar como etiquetas en el tramo. Ejemplos de claves: session, env, system y version. Para más información sobre etiquetas, consulte Introducción a las Etiquetas.

Ejemplo

from ddtrace.llmobs import LLMObs
from ddtrace.llmobs.decorators import embedding, llm, retrieval, workflow

@llm(model_name="model_name", model_provider="model_provider")
def llm_call(prompt):
    resp = ... # llm call here
    LLMObs.annotate(
        span=None,
        input_data=[{"role": "user", "content": "Hello world!"}],
        output_data=[{"role": "assistant", "content": "How can I help?"}],
        metadata={"temperature": 0, "max_tokens": 200},
        metrics={"input_tokens": 4, "output_tokens": 6, "total_tokens": 10},
        tags={"host": "host_name"},
    )
    return resp

@workflow
def extract_data(document):
    resp = llm_call(document)
    LLMObs.annotate(
        input_data=document,
        output_data=resp,
        tags={"host": "host_name"},
    )
    return resp

@embedding(model_name="text-embedding-3", model_provider="openai")
def perform_embedding():
    ... # user application logic
    LLMObs.annotate(
        span=None,
        input_data={"text": "Hello world!"},
        output_data=[0.0023064255, -0.009327292, ...],
        metrics={"input_tokens": 4},
        tags={"host": "host_name"},
    )
    return

@retrieval(name="get_relevant_docs")
def similarity_search():
    ... # user application logic
    LLMObs.annotate(
        span=None,
        input_data="Hello world!",
        output_data=[{"text": "Hello world is ...", "name": "Hello, World! program", "id": "document_id", "score": 0.9893}],
        tags={"host": "host_name"},
    )
    return

El SDK proporciona el método llmobs.annotate() para anotar tramos con entradas, salidas y metadatos.

El método LLMObs.annotate() acepta los siguientes argumentos:

Argumentos

span: opcional - Tramo - predeterminado: el tramo activo actual
El tramo a anotar. Si span no se proporciona (como al usar envolturas de función), el SDK anota el tramo activo actual.
annotationOptions: requerido - objeto
Un objeto de diferentes tipos de datos para anotar el tramo.

El annotationOptions objeto puede contener lo siguiente:

inputData: opcional - tipo serializable en JSON o lista de objetos
Ya sea un tipo serializable en JSON (para tramos no LLM) o una lista de diccionarios con este formato: {role: "...", content: "..."} (para tramos LLM). Nota: Los tramos de incrustación son un caso especial y requieren una cadena o un objeto (o una lista de objetos) con este formato: {text: "..."}.
outputData: opcional - tipo serializable en JSON o lista de objetos
Ya sea un tipo serializable en JSON (para tramos no LLM) o una lista de objetos con este formato: {role: "...", content: "..."} (para tramos LLM). Nota: Los tramos de recuperación son un caso especial y requieren una cadena o un objeto (o una lista de objetos) con este formato: {text: "...", name: "...", score: number, id: "..."}.
metadata: opcional - objeto
Un objeto de pares clave-valor serializables en JSON que los usuarios pueden agregar como información de metadatos relevante para la operación de entrada o salida descrita por el tramo (model_temperature, max_tokens, top_k, etc.).
metrics: opcional - objeto
Un objeto de claves serializables en JSON y valores numéricos que los usuarios pueden agregar como métricas relevantes a la operación descrita por el tramo (input_tokens, output_tokens, total_tokens, etc.).
tags: opcional - objeto
Un objeto de pares clave-valor serializables en JSON que los usuarios pueden agregar como etiquetas respecto al contexto del tramo (session, environment, system, versioning, etc.). Para más información sobre etiquetas, consulte Introducción a las Etiquetas.

Ejemplo

function llmCall (prompt) {
  const completion = ... // user application logic to invoke LLM
  llmobs.annotate({
    inputData: [{ role: "user", content: "Hello world!" }],
    outputData: [{ role: "assistant", content: "How can I help?" }],
    metadata: { temperature: 0, max_tokens: 200 },
    metrics: { input_tokens: 4, output_tokens: 6, total_tokens: 10 },
    tags: { host: "host_name" }
  })
  return completion
}
llmCall = llmobs.wrap({ kind:'llm', modelName: 'modelName', modelProvider: 'modelProvider' }, llmCall)

function extractData (document) {
  const resp = llmCall(document)
  llmobs.annotate({
    inputData: document,
    outputData: resp,
    tags: { host: "host_name" }
  })
  return resp
}
extractData = llmobs.wrap({ kind: 'workflow' }, extractData)

function performEmbedding () {
  ... // user application logic
  llmobs.annotate(
    undefined, { // this can be set to undefined or left out entirely
      inputData: { text: "Hello world!" },
      outputData: [0.0023064255, -0.009327292, ...],
      metrics: { input_tokens: 4 },
      tags: { host: "host_name" }
    }
  )
}
performEmbedding = llmobs.wrap({ kind: 'embedding', modelName: 'text-embedding-3', modelProvider: 'openai' }, performEmbedding)

function similaritySearch () {
  ... // user application logic
  llmobs.annotate(undefined, {
    inputData: "Hello world!",
    outputData: [{ text: "Hello world is ...", name: "Hello, World! program", id: "document_id", score: 0.9893 }],
    tags: { host: "host_name" }
  })
  return
}
similaritySearch = llmobs.wrap({ kind: 'retrieval', name: 'getRelevantDocs' }, similaritySearch)

El SDK proporciona varios métodos para anotar tramos con entradas, salidas, métricas y metadatos.

Anotando entradas y salidas

Utilice el método miembro annotateIO() de la interfaz LLMObsSpan para agregar datos de entrada y salida estructurados a un LLMObsSpan. Esto incluye argumentos opcionales y objetos de mensaje LLM.

Argumentos

Si un argumento es nulo o vacío, no sucede nada. Por ejemplo, si inputData es una cadena no vacía mientras que outputData es nulo, entonces solo se registra inputData.

inputData: opcional - Cadena o Lista<LLMObs.LLMMessage>
Ya sea una cadena (para tramos no LLM) o una lista de LLMObs.LLMMessages para tramos LLM.
outputData: opcional - Cadena o Lista<LLMObs.LLMMessage>
Ya sea una cadena (para tramos no LLM) o una lista de LLMObs.LLMMessages para tramos LLM.

Mensajes LLM

Los tramos de LLM deben ser anotados con Mensajes LLM usando el objeto LLMObs.LLMMessage.

El objeto LLMObs.LLMMessage puede ser instanciado llamando a LLMObs.LLMMessage.from() con los siguientes argumentos:

role: requerido - Cadena
Una cadena que describe el rol del autor del mensaje.
content: requerido - Cadena
Una cadena que contiene el contenido del mensaje.

Ejemplo

import datadog.trace.api.llmobs.LLMObs;

public class MyJavaClass {
  public String invokeChat(String userInput) {
    LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
    String systemMessage = "You are a helpful assistant";
    Response chatResponse = ... // user application logic to invoke LLM
    llmSpan.annotateIO(
      Arrays.asList(
        LLMObs.LLMMessage.from("user", userInput),
        LLMObs.LLMMessage.from("system", systemMessage)
      ),
      Arrays.asList(
        LLMObs.LLMMessage.from(chatResponse.role, chatResponse.content)
      )
    );
    llmSpan.finish();
    return chatResponse;
  }
}

Agregando métricas

Agregar métricas en bloque

El método miembro setMetrics() de la interfaz LLMObsSpan acepta los siguientes argumentos para adjuntar múltiples métricas en bloque:

Argumentos

metrics: requerido - Mapa<String, Número>
Un mapa de claves serializables en JSON y valores numéricos que los usuarios pueden agregar para registrar métricas relevantes a la operación descrita por el tramo (por ejemplo, input_tokens, output_tokens o total_tokens).

Agregar una sola métrica

El método miembro setMetric() de la interfaz LLMObsSpan acepta los siguientes argumentos para adjuntar una sola métrica:

Argumentos

key: requerido - Secuencia de caracteres
El nombre de la métrica.
value: requerido - int, long, o double
El valor de la métrica.

Ejemplos

import datadog.trace.api.llmobs.LLMObs;

public class MyJavaClass {
  public String invokeChat(String userInput) {
    LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
    String chatResponse = ... // user application logic to invoke LLM
    llmSpan.setMetrics(Map.of(
      "input_tokens", 617,
      "output_tokens", 338,
      "time_per_output_token", 0.1773
    ));
    llmSpan.setMetric("total_tokens", 955);
    llmSpan.setMetric("time_to_first_token", 0.23);
    llmSpan.finish();
    return chatResponse;
  }
}

Agregando etiquetas

Para más información sobre etiquetas, consulte Introducción a las Etiquetas.

Agregar etiquetas en bloque

El método miembro setTags() de la interfaz LLMObsSpan acepta los siguientes argumentos para adjuntar múltiples etiquetas en bloque:

Argumentos

tags: requerido - Mapa<String, Object>
Un mapa de pares clave-valor serializables en JSON que los usuarios pueden agregar como etiquetas para describir el contexto del tramo (por ejemplo, session, environment, system, o version).

Agregar una sola etiqueta

El método miembro setTag() de la interfaz LLMObsSpan acepta los siguientes argumentos para adjuntar una sola etiqueta:

Argumentos

key: requerido - Cadena
La clave de la etiqueta.
value: requerido - int, long, double, boolean, o Cadena
El valor de la etiqueta.

Ejemplos

import datadog.trace.api.llmobs.LLMObs;

public class MyJavaClass {
  public String invokeChat(String userInput) {
    LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
    String chatResponse = ... // user application logic to invoke LLM
    llmSpan.setTags(Map.of(
      "chat_source", "web",
      "users_in_chat", 3
    ));
    llmSpan.setTag("is_premium_user", true);
    llmSpan.finish();
    return chatResponse;
  }
}

Anotando errores

Agregando un Throwable (recomendado)

El método miembro addThrowable() de la interfaz LLMObsSpan acepta el siguiente argumento para adjuntar un throwable con una traza de pila:

Argumentos

throwable: requerido - Throwable
El throwable/excepción que ocurrió.

Agregando un mensaje de error

El método miembro setErrorMessage() de la interfaz LLMObsSpan acepta el siguiente argumento para adjuntar una cadena de error:

Argumentos

errorMessage: requerido - Cadena
El mensaje del error.

Estableciendo una bandera de error

El método miembro setError() de la interfaz LLMObsSpan acepta el siguiente argumento para indicar un error con la operación:

Argumentos

error: requerido - boolean
true si el tramo tuvo un error.

Ejemplos

import datadog.trace.api.llmobs.LLMObs;

public class MyJavaClass {
  public String invokeChat(String userInput) {
    LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
    String chatResponse = "N/A";
    try {
      chatResponse = ... // user application logic to invoke LLM
    } catch (Exception e) {
      llmSpan.addThrowable(e);
      throw new RuntimeException(e);
    } finally {
      llmSpan.finish();
    }
    return chatResponse;
  }
}

Anotando metadatos

El método miembro setMetadata() de la interfaz LLMObsSpan acepta los siguientes argumentos:

metadata: requerido - Mapa<String, Object>
Un mapa de pares clave-valor serializables en JSON que contiene metadatos relevantes para la operación de entrada o salida descrita por el tramo.

Ejemplo

import datadog.trace.api.llmobs.LLMObs;

public class MyJavaClass {
  public String invokeChat(String userInput) {
    LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
    llmSpan.setMetadata(
      Map.of(
        "temperature", 0.5,
        "is_premium_member", true,
        "class", "e1"
      )
    );
    String chatResponse = ... // user application logic to invoke LLM
    return chatResponse;
  }
}

Anotando tramos auto-instrumentados

El método LLMObs.annotation_context() del SDK devuelve un administrador de contexto que se puede usar para modificar todos los tramos auto-instrumentados iniciados mientras el contexto de anotación está activo.

El método LLMObs.annotation_context() acepta los siguientes argumentos:

Argumentos

name: opcional - str
Nombre que anula el nombre del tramo para cualquier tramo auto-instrumentado que se inicie dentro del contexto de anotación.
prompt: opcional - diccionario
Un diccionario que representa el prompt utilizado para una llamada a LLM. Consulte la documentación del Objeto Prompt para el esquema completo y las claves admitidas. También puede importar el Prompt objeto de ddtrace.llmobs.utils y pasarlo como el argumento prompt. Nota: Este argumento solo se aplica a los tramos de LLM.
tags: opcional - diccionario
Un diccionario de pares clave-valor serializables en JSON que los usuarios pueden agregar como etiquetas en el tramo. Ejemplos de claves: session, env, system y version. Para más información sobre etiquetas, consulte Introducción a las Etiquetas.

Ejemplo

from ddtrace.llmobs import LLMObs
from ddtrace.llmobs.decorators import workflow

@workflow
def rag_workflow(user_question):
    context_str = retrieve_documents(user_question).join(" ")

    with LLMObs.annotation_context(
        prompt = Prompt(
            id="chatbot_prompt",
            version="1.0.0",
            template="Please answer the question using the provided context: {{question}}\n\nContext:\n{{context}}",
            variables={
                "question": user_question,
                "context": context_str,
            }
        ),
        tags = {
            "retrieval_strategy": "semantic_similarity"
        },
        name = "augmented_generation"
    ):
        completion = openai_client.chat.completions.create(...)
    return completion.choices[0].message.content

El llmobs.annotationContext() del SDK acepta una función de callback que se puede usar para modificar todos los tramos auto-instrumentados iniciados mientras se está dentro del contexto de la función de callback.

El método llmobs.annotationContext() acepta las siguientes opciones en el primer argumento:

Opciones

name: opcional - str
Nombre que anula el nombre del tramo para cualquier tramo auto-instrumentado que se inicie dentro del contexto de anotación.
tags: opcional - objeto
Un objeto de pares clave-valor serializables en JSON que los usuarios pueden agregar como etiquetas en el tramo. Ejemplos de claves: session, env, system y version. Para más información sobre las etiquetas, consulte Introducción a las Etiquetas.

Ejemplo

const { llmobs } = require('dd-trace');

function ragWorkflow(userQuestion) {
    const contextStr = retrieveDocuments(userQuestion).join(" ");

    const completion = await llmobs.annotationContext({
      tags: {
        retrieval_strategy: "semantic_similarity"
      },
      name: "augmented_generation"
    }, async () => {
      const completion = await openai_client.chat.completions.create(...);
      return completion.choices[0].message.content;
    });
}

Seguimiento de prompt

Adjunte metadatos estructurados del prompt al tramo de LLM para que pueda reproducir resultados, auditar cambios y comparar el rendimiento del prompt entre versiones. Al usar plantillas, LLM Observability también proporciona seguimiento de versiones basado en cambios en el contenido de la plantilla.

Utilice LLMObs.annotation_context(prompt=...) para adjuntar metadatos de prompt antes de la llamada al LLM. Para más detalles sobre la anotación de tramos, consulte Enriqueciendo tramos.

Argumentos

prompt: requerido - diccionario
Un diccionario tipado que sigue el esquema de Prompt a continuación.

Estructura del prompt

Claves soportadas:

id (str): Identificador lógico para este prompt. Debería ser único por ml_app. Por defecto es {ml_app}-unnamed_prompt
version (str): Etiqueta de versión para el prompt (por ejemplo, “1.0.0”). Consulte seguimiento de versiones para más detalles.
variables (Dict[str, str]): Variables utilizadas para poblar los marcadores de posición de la plantilla.
template (str): Cadena de plantilla con marcadores de posición (por ejemplo, "Traducir {{text}} a {{lang}}").
chat_template (Lista[Mensaje]): Formato de plantilla de múltiples mensajes. Proporcione una lista de { "role": "<role>", "content": "<template string with placeholders>" } objetos.
tags (Dict[str, str]): Etiquetas para adjuntar a la ejecución del prompt.
rag_context_variables (Lista[str]): Claves variables que contienen contenido de verdad/contexto. Utilizado para detección de alucinaciones.
rag_query_variables (Lista[str]): Claves variables que contienen la consulta del usuario. Utilizado para detección de alucinaciones.

Ejemplo: prompt de plantilla única

from ddtrace.llmobs import LLMObs

def answer_question(text):
    # Attach prompt metadata to the upcoming LLM span using LLMObs.annotation_context()
    with LLMObs.annotation_context(prompt={
        "id": "translation-template",
        "version": "1.0.0",
        "chat_template": [{"role": "user", "content": "Translate to {{lang}}: {{text}}"}],
        "variables": {"lang": "fr", "text": text},
        "tags": {"team": "nlp"}
    }):
        # Example provider call (replace with your client)
        completion = openai_client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": f"Translate to fr: {text}"}]
        )
    return completion

Ejemplo: plantillas de prompt de LangChain

Cuando utilice la plantilla de prompts de LangChain con auto-instrumentación, asigne plantillas a variables con nombres significativos. La auto-instrumentación 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

Utilice llmobs.annotationContext({ prompt: ... }, () => { ... }) para adjuntar metadatos de prompt antes de la llamada al LLM. Para más detalles sobre la anotación de tramos, consulte Enriqueciendo tramos.

Argumentos

Opciones

prompt: requerido - objeto
Un objeto que sigue el esquema de Prompt a continuación.

Estructura del prompt

Propiedades soportadas:

id (cadena): Identificador lógico para este prompt. Debería ser único por ml_app. Por defecto es {ml_app}-unnamed_prompt
version (cadena): Etiqueta de versión para el prompt (por ejemplo, “1.0.0”). Consulte seguimiento de versiones para más detalles.
variables (Registro<string, string>): Variables utilizadas para poblar los marcadores de posición de la plantilla.
template (cadena | Lista[Mensaje]): Cadena de plantilla con marcadores de posición (por ejemplo, "Traducir {{text}} a {{lang}}"). Alternatively, a list of { "role": "<role>", "content": "<template string with placeholders>" } objects.
tags (Registro<string, string>): Etiquetas para adjuntar a la ejecución del prompt.
contextVariables (cadena[]): Claves de variable que contienen contenido de verdad contextual. Utilizado para la detección de alucinaciones.
queryVariables (cadena[]): Claves de variable que contienen la consulta del usuario. Utilizado para la detección de alucinaciones.

Ejemplo: prompt de plantilla única

const { llmobs } = require('dd-trace');

function answerQuestion(text) {
    // Attach prompt metadata to the upcoming LLM span using LLMObs.annotation_context()
    return llmobs.annotationContext({
      prompt: {
        id: "translation-template",
        version: "1.0.0",
        chat_template: [{"role": "user", "content": "Translate to {{lang}}: {{text}}"}],
        variables: {"lang": "fr", "text": text},
        tags: {"team": "nlp"}
      }
    }, () => {
      // Example provider call (replace with your client)
      return openaiClient.chat.completions.create({
          model: "gpt-4o",
          messages: [{"role": "user", "content": f"Translate to fr: {text}"}]
        });
    });
}

Notas

La anotación de un prompt solo está disponible en los tramos de LLM.
Coloca la anotación inmediatamente antes de la llamada al proveedor para que se aplique al tramo de LLM correcto.
Utiliza un prompt único id para distinguir diferentes prompts dentro de tu aplicación.
Mantén las plantillas estáticas utilizando la sintaxis de marcador de posición (como {{variable_name}}) and define dynamic content in the variables section.
Para múltiples llamadas de LLM auto-instrumentadas dentro de un bloque, utiliza un contexto de anotación para aplicar los mismos metadatos de prompt en todas las llamadas. Consulta Anotando tramos auto-instrumentados.

Seguimiento de versiones

LLM Observability proporciona versionado automático para tus prompts cuando no se especifica una versión explícita. Cuando proporcionas un template o chat_template en los metadatos de tu prompt sin una etiqueta version, el sistema genera automáticamente una versión calculando un hash del contenido de la plantilla. Si proporcionas una etiqueta version, LLM Observability utiliza la etiqueta de versión que especificaste en lugar de generar una automáticamente.

El sistema de versionado funciona de la siguiente manera:

Versionado automático: Cuando no se proporciona una etiqueta version, LLM Observability calcula un hash del contenido template o chat_template para generar automáticamente un identificador de versión numérico.
Versionado manual: Cuando se proporciona una version etiqueta, LLM Observability utiliza su etiqueta de versión especificada exactamente como se proporciona
Historial de versiones: Tanto las versiones generadas automáticamente como las manuales se mantienen en el historial de versiones para rastrear la evolución de los prompts a lo largo del tiempo

Esto le brinda la flexibilidad de confiar en la gestión automática de versiones basada en cambios en el contenido de la plantilla, o mantener el control total sobre el versionado con sus propias etiquetas de versión.

Monitoreo de costos

Adjunte métricas de tokens (para el seguimiento automático de costos) o métricas de costos (para el seguimiento manual de costos) a sus tramos de LLM/embedding. Las métricas de tokens permiten a Datadog calcular costos utilizando los precios del proveedor, mientras que las métricas de costos le permiten proporcionar su propio precio al usar modelos personalizados o no compatibles. Para más detalles, consulte Costos.

Si está utilizando instrumentación automática, las métricas de tokens y costos aparecen en sus tramos automáticamente. Si está instrumentando manualmente, siga la guía a continuación.

En este contexto, "métricas de tokens" y "métricas de costos" se refieren a pares numéricos clave-valor que se adjuntan a los tramos mediante el parámetro metrics del método LLMObs.annotate(). Estas son distintas de las métricas de LLM Observability de la plataforma Datadog. Para claves reconocidas como input_tokens, output_tokens, input_cost y output_cost, Datadog utiliza estos atributos de tramo para generar las métricas de plataforma correspondientes (como ml_obs.span.llm.input.cost) para su uso en tableros y monitores.

Caso de uso: Usando un proveedor de modelo común

Datadog admite proveedores de modelos comunes, como OpenAI, Azure OpenAI, Anthropic y Google Gemini. Cuando utilice estos proveedores, solo necesita anotar su solicitud de LLM con model_name, model_provider y el uso de tokens. Datadog calcula automáticamente el costo estimado basado en la tarifa del proveedor.

from ddtrace.llmobs import LLMObs
from ddtrace.llmobs.decorators import llm

@llm(model_name="gpt-5.1", model_provider="openai")
def llm_call(prompt):
    resp = ... # llm call here
    # Annotate token metrics
    LLMObs.annotate(
        metrics={
          "input_tokens": 50,
          "output_tokens": 120,
          "total_tokens": 170,
          "non_cached_input_tokens": 13,  # optional
          "cache_read_input_tokens": 22,  # optional
          "cache_write_input_tokens": 15, # optional
        },
    )
    return resp

Caso de uso: Uso de un modelo personalizado

Para modelos personalizados o no compatibles, debe anotar el tramo manualmente con los datos de costo.

from ddtrace.llmobs import LLMObs
from ddtrace.llmobs.decorators import llm

@llm(model_name="custom_model", model_provider="model_provider")
def llm_call(prompt):
    resp = ... # llm call here
    # Annotate cost metrics
    LLMObs.annotate(
        metrics={
          "input_cost": 3,
          "output_cost": 7,
          "total_cost": 10,
          "non_cached_input_cost": 1,    # optional
          "cache_read_input_cost": 0.6,  # optional
          "cache_write_input_cost": 1.4, # optional
        },
    )
    return resp

##Evaluaciones

El SDK de LLM Observability proporciona métodos para exportar y enviar sus evaluaciones a Datadog.

Para construir evaluadores reutilizables basados en clases (BaseEvaluator, BaseSummaryEvaluator) con metadatos de resultados ricos, consulte la Guía del Desarrollador de Evaluación.

Las evaluaciones deben unirse a un solo tramo. Puede identificar el tramo objetivo utilizando cualquiera de estos dos métodos:

Unión basada en etiquetas - Una evaluación se une utilizando un par de etiquetas clave-valor único que se establece en un solo tramo. La evaluación fallará al unirse si el par de etiquetas clave-valor coincide con múltiples tramos o con ningún tramo.
Referencia directa al tramo - Únase a una evaluación utilizando la combinación única de ID de traza e ID de tramo del tramo.

Exportando un tramo

LLMObs.export_span() se puede usar para extraer el contexto del tramo de un tramo. Este método es útil para asociar su evaluación con el tramo correspondiente.

Argumentos

El LLMObs.export_span() método acepta el siguiente argumento:

span: opcional - Tramo
El tramo del cual extraer el contexto del tramo (IDs de tramo y de traza). Si no se proporciona (como cuando se utilizan decoradores de función), el SDK exporta el tramo activo actual.

Ejemplo

from ddtrace.llmobs import LLMObs
from ddtrace.llmobs.decorators import llm

@llm(model_name="claude", name="invoke_llm", model_provider="anthropic")
def llm_call():
    completion = ... # user application logic to invoke LLM
    span_context = LLMObs.export_span(span=None)
    return completion

llmobs.exportSpan() se puede usar para extraer el contexto del tramo de un tramo. Necesitará usar este método para asociar su evaluación con el tramo correspondiente.

Argumentos

El llmobs.exportSpan() método acepta el siguiente argumento:

span: opcional - Tramo
El tramo del cual extraer el contexto del tramo (IDs de tramo y de traza). Si no se proporciona (como cuando se utilizan envolturas de función), el SDK exporta el tramo activo actual.

Ejemplo

function llmCall () {
  const completion = ... // user application logic to invoke LLM
  const spanContext = llmobs.exportSpan()
  return completion
}
llmCall = llmobs.wrap({ kind: 'llm', name: 'invokeLLM', modelName: 'claude', modelProvider: 'anthropic' }, llmCall)

Enviando evaluaciones

LLMObs.submit_evaluation() se puede usar para enviar su evaluación personalizada asociada con un tramo dado.

LLMObs.submit_evaluation_for está en desuso y se eliminará en la próxima versión principal de ddtrace (4.0). Para migrar, renombre sus llamadas a LLMObs.submit_evaluation_for con LLMObs.submit_evaluation.

Nota: Las evaluaciones personalizadas son evaluadores que usted implementa y aloja usted mismo. Estos difieren de las evaluaciones listas para usar, que son calculadas automáticamente por Datadog utilizando evaluadores integrados. Para configurar evaluaciones listas para usar para su aplicación, utilice la página Observabilidad LLM > Settings > Evaluaciones en Datadog.

El método LLMObs.submit_evaluation() acepta los siguientes argumentos:

Argumentos

label: requerido - cadena
El nombre de la evaluación.
metric_type: requerido - cadena
El tipo de la evaluación. Debe ser categorical, score, boolean o json.
value: requerido - cadena, tipo numérico, o dict
El valor de la evaluación. Debe ser una cadena (metric_type==categorical), entero/flotante (metric_type==score), booleano (metric_type==boolean), o dict (metric_type==json).
span: opcional - diccionario
Un diccionario que identifica de manera única el tramo asociado con esta evaluación. Debe contener span_id (cadena) y trace_id (cadena). Utilice LLMObs.export_span() para generar este diccionario.
span_with_tag_value: opcional - _ diccionario_
Un diccionario que identifica de manera única el tramo asociado con esta evaluación. Debe contener tag_key (cadena) y tag_value (cadena).
Nota: Se requiere exactamente uno de span o span_with_tag_value. Proporcionar ambos, o ninguno, genera un ValueError.
ml_app: requerido - cadena
El nombre de la aplicación de ML.
timestamp_ms: opcional - entero
La marca de tiempo Unix en milisegundos cuando se generó el resultado de la métrica de evaluación. Si no se proporciona, esto se establece en la hora actual.
tags: opcional - diccionario
Un diccionario de pares clave-valor de cadena que los usuarios pueden agregar como etiquetas relacionadas con la evaluación. Para más información sobre etiquetas, consulte Introducción a las Etiquetas.
assessment: opcional - cadena
Una valoración de esta evaluación. Los valores aceptados son pass y fail.
reasoning: opcional - cadena
Una explicación textual del resultado de la evaluación.
metadata: opcional - diccionario
Un diccionario que contiene metadatos estructurados arbitrarios asociados con el resultado de la evaluación.

Ejemplo

from ddtrace.llmobs import LLMObs
from ddtrace.llmobs.decorators import llm

@llm(model_name="claude", name="invoke_llm", model_provider="anthropic")
def llm_call():
    completion = ... # user application logic to invoke LLM

    # joining an evaluation to a span via a tag key-value pair
    msg_id = get_msg_id()
    LLMObs.annotate(
        tags = {'msg_id': msg_id}
    )

    LLMObs.submit_evaluation(
        span_with_tag_value = {
            "tag_key": "msg_id",
            "tag_value": msg_id
        },
        ml_app = "chatbot",
        label="harmfulness",
        metric_type="score",
        value=10,
        tags={"evaluation_provider": "ragas"},
        assessment="fail",
        reasoning="Malicious intent was detected in the user instructions.",
        metadata={"details": ["jailbreak", "SQL injection"]}
    )

    # joining an evaluation to a span via span ID and trace ID
    span_context = LLMObs.export_span(span=None)
    LLMObs.submit_evaluation(
        span_context = span_context,
        ml_app = "chatbot",
        label="harmfulness",
        metric_type="score",
        value=10,
        tags={"evaluation_provider": "ragas"},
        assessment="fail",
        reasoning="Malicious intent was detected in the user instructions.",
        metadata={"details": ["jailbreak", "SQL injection"]}
    )
    return completion

llmobs.submitEvaluation() se puede usar para enviar su evaluación personalizada asociada con un tramo dado.

El método llmobs.submitEvaluation() acepta los siguientes argumentos:

Argumentos

span_context: requerido - diccionario
El contexto del tramo con el que se asociará la evaluación. Esto debería ser la salida de LLMObs.export_span().
evaluationOptions: requerido - objeto
Un objeto de los datos de evaluación.

El objeto evaluationOptions puede contener lo siguiente:

label: requerido - cadena
El nombre de la evaluación.
metricType: requerido - cadena
El tipo de la evaluación. Debe ser uno de “categórico”, “puntaje”, “booleano” o “json”.
value: requerido - tipo de cadena o numérico
El valor de la evaluación. Debe ser una cadena (para categórico metric_type), número (para puntaje metric_type), booleano (para booleano metric_type), o un objeto JSON (para json metric_type).
tags: opcional - diccionario
Un diccionario de pares clave-valor de cadenas que los usuarios pueden agregar como etiquetas relacionadas con la evaluación. Para más información sobre etiquetas, consulte Introducción a las Etiquetas.
assessment: opcional - cadena
Una valoración de esta evaluación. Los valores aceptados son pass y fail.
reasoning: opcional - cadena
Una explicación textual del resultado de la evaluación.
metadata: opcional - diccionario
Un objeto JSON que contiene metadatos estructurados arbitrarios asociados con el resultado de la evaluación.

Ejemplo

function llmCall () {
  const completion = ... // user application logic to invoke LLM
  const spanContext = llmobs.exportSpan()
  llmobs.submitEvaluation(spanContext, {
    label: "harmfulness",
    metricType: "score",
    value: 10,
    tags: { evaluationProvider: "ragas" }
  })
  return completion
}
llmCall = llmobs.wrap({ kind: 'llm', name: 'invokeLLM', modelName: 'claude', modelProvider: 'anthropic' }, llmCall)

Utilice LLMObs.SubmitEvaluation() para enviar su evaluación personalizada asociada con un tramo dado.

El método LLMObs.SubmitEvaluation() acepta los siguientes argumentos:

Argumentos

llmObsSpan: requerido - LLMObsSpan
El contexto del tramo con el que se asociará la evaluación.
label: requerido - Cadena
El nombre de la evaluación.
categoricalValue o scoreValue: requerido - Cadena o doble
El valor de la evaluación. Debe ser una cadena (para evaluaciones categóricas) o un doble (para evaluaciones de puntaje).
tags: opcional - Map<String, Object>
Un diccionario de pares clave-valor de cadenas utilizados para etiquetar la evaluación. Para más información sobre etiquetas, consulte Introducción a las Etiquetas.

Ejemplo

import datadog.trace.api.llmobs.LLMObs;

public class MyJavaClass {
  public String invokeChat(String userInput) {
    LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
    String chatResponse = "N/A";
    try {
      chatResponse = ... // user application logic to invoke LLM
    } catch (Exception e) {
      llmSpan.addThrowable(e);
      throw new RuntimeException(e);
    } finally {
      llmSpan.finish();

      // submit evaluations
      LLMObs.SubmitEvaluation(llmSpan, "toxicity", "toxic", Map.of("language", "english"));
      LLMObs.SubmitEvaluation(llmSpan, "f1-similarity", 0.02, Map.of("provider", "f1-calculator"));
    }
    return chatResponse;
  }
}

Procesamiento de tramos

Para modificar los datos de entrada y salida en tramos, puede configurar una función de procesador. La función del procesador tiene acceso a las etiquetas de tramo para habilitar la modificación condicional de entrada/salida. Las funciones del procesador pueden devolver el tramo modificado para emitirlo, o devolver None/null para evitar que el tramo sea emitido por completo. Esto es útil para filtrar tramos que contienen datos sensibles o que cumplen ciertos criterios.

Ejemplo

from ddtrace.llmobs import LLMObs
from ddtrace.llmobs import LLMObsSpan

def redact_processor(span: LLMObsSpan) -> LLMObsSpan:
    if span.get_tag("no_output") == "true":
        for message in span.output:
            message["content"] = ""
    return span


# If using LLMObs.enable()
LLMObs.enable(
  ...
  span_processor=redact_processor,
)
# else when using `ddtrace-run`
LLMObs.register_processor(redact_processor)

with LLMObs.llm("invoke_llm_with_no_output"):
    LLMObs.annotate(tags={"no_output": "true"})

Ejemplo: modificación condicional con auto-instrumentación

Al usar auto instrumentación, el tramo no siempre es accesible contextualmente. Para modificar condicionalmente las entradas y salidas en tramos auto-instrumentados, se puede usar annotation_context() además de un procesador de tramos.

from ddtrace.llmobs import LLMObs
from ddtrace.llmobs import LLMObsSpan

def redact_processor(span: LLMObsSpan) -> LLMObsSpan:
    if span.get_tag("no_input") == "true":
        for message in span.input:
            message["content"] = ""
    return span

LLMObs.register_processor(redact_processor)


def call_openai():
    with LLMObs.annotation_context(tags={"no_input": "true"}):
        # make call to openai
        ...

Ejemplo: evitar que los tramos sean emitidos

from ddtrace.llmobs import LLMObs
from ddtrace.llmobs import LLMObsSpan
from typing import Optional

def filter_processor(span: LLMObsSpan) -> Optional[LLMObsSpan]:
    # Skip spans that are marked as internal or contain sensitive data
    if span.get_tag("internal") == "true" or span.get_tag("sensitive") == "true":
        return None  # This span will not be emitted

    # Process and return the span normally
    return span

LLMObs.register_processor(filter_processor)

# This span will be filtered out and not sent to Datadog
with LLMObs.workflow("internal_workflow"):
    LLMObs.annotate(tags={"internal": "true"})
    # ... workflow logic

Ejemplo

const tracer = require('dd-trace').init({
  llmobs: {
    mlApp: "<YOUR_ML_APP_NAME>"
  }
})

const llmobs = tracer.llmobs

function redactProcessor(span) {
  if (span.getTag("no_output") === "true") {
    for (const message of span.output) {
      message.content = ""
    }
  }
  return span
}

llmobs.registerProcessor(redactProcessor)

Ejemplo: modificación condicional con auto-instrumentación

Al usar auto instrumentación, el tramo no siempre es accesible contextualmente. Para modificar condicionalmente las entradas y salidas en tramos auto-instrumentados, se puede usar llmobs.annotationContext() además de un procesador de tramos.

const { llmobs } = require('dd-trace');

function redactProcessor(span) {
  if (span.getTag("no_input") == "true") {
    for (const message of span.input) {
      message.content = "";
    }
  }

  return span;
}

llmobs.registerProcessor(redactProcessor);

async function callOpenai() {
  await llmobs.annotationContext({ tags: { no_input: "true" } }, async () => {
    // make call to openai
  });
}

Ejemplo: evitar que los tramos sean emitidos

const tracer = require('dd-trace').init({
  llmobs: {
    mlApp: "<YOUR_ML_APP_NAME>"
  }
})

const llmobs = tracer.llmobs

function filterProcessor(span) {
  // Skip spans that are marked as internal or contain sensitive data
  if (span.getTag("internal") === "true" || span.getTag("sensitive") === "true") {
    return null  // This span will not be emitted
  }

  // Process and return the span normally
  return span
}

llmobs.registerProcessor(filterProcessor)

// This span will be filtered out and not sent to Datadog
function internalWorkflow() {
  return llmobs.trace({ kind: 'workflow', name: 'internalWorkflow' }, (span) => {
    llmobs.annotate({ tags: { internal: "true" } })
    // ... workflow logic
  })
}

Seguimiento de sesiones de usuario

El seguimiento de sesiones permite asociar múltiples interacciones con un usuario dado.

Al iniciar un tramo raíz para una nueva traza o tramo en un nuevo proceso, especifique el argumento session_id con el ID de cadena de la sesión de usuario subyacente, que se envía como una etiqueta en el tramo. Opcionalmente, también puede especificar las etiquetas user_handle, user_name y user_id.

from ddtrace.llmobs.decorators import workflow

@workflow(session_id="<SESSION_ID>")
def process_user_message():
    LLMObs.annotate(
        ...
        tags = {"user_handle": "poodle@dog.com", "user_id": "1234", "user_name": "poodle"}
    )
    return

Etiquetas de seguimiento de sesiones

Etiqueta	Descripción
`session_id`	El ID que representa una única sesión de usuario, por ejemplo, una sesión de chat.
`user_handle`	El identificador para el usuario de la sesión de chat.
`user_name`	El nombre del usuario de la sesión de chat.
`user_id`	El ID del usuario de la sesión de chat.

Al iniciar un tramo raíz para una nueva traza o tramo en un nuevo proceso, especifique el argumento sessionId con el ID de cadena de la sesión de usuario subyacente:

function processMessage() {
    ... # user application logic
    return
}
processMessage = llmobs.wrap({ kind: 'workflow', sessionId: "<SESSION_ID>" }, processMessage)

Al iniciar un tramo raíz para una nueva traza o tramo en un nuevo proceso, especifique el argumento sessionId con el ID de cadena de la sesión de usuario subyacente:

import datadog.trace.api.llmobs.LLMObs;

public class MyJavaClass {
  public String processChat(int userID) {
    LLMObsSpan workflowSpan = LLMObs.startWorkflowSpan("incoming-chat", null, "session-" + System.currentTimeMillis() + "-" + userID);
    String chatResponse = answerChat(); // user application logic
    workflowSpan.annotateIO(...); // record the input and output
    workflowSpan.finish();
    return chatResponse;
  }
}

Trazado distribuido

El SDK admite el trazado a través de servicios o servidores distribuidos. El trazado distribuido funciona propagando información de tramos a través de solicitudes web.

La biblioteca ddtrace proporciona algunas integraciones listas para usar que admiten el trazado distribuido para populares marcos web y bibliotecas HTTP. Si su aplicación realiza solicitudes utilizando estas bibliotecas admitidas, puede habilitar el trazado distribuido ejecutando:

from ddtrace import patch
patch(<INTEGRATION_NAME>=True)

Si su aplicación no utiliza ninguna de estas bibliotecas admitidas, puede habilitar el trazado distribuido propagando manualmente la información de tramos hacia y desde los encabezados HTTP. El SDK proporciona los métodos auxiliares LLMObs.inject_distributed_headers() y LLMObs.activate_distributed_headers() para inyectar y activar contextos de trazado en los encabezados de solicitud.

Inyectando encabezados distribuidos

El método LLMObs.inject_distributed_headers() toma un tramo e inyecta su contexto en los encabezados HTTP que se incluirán en la solicitud. Este método acepta los siguientes argumentos:

request_headers: requerido - diccionario
Los encabezados HTTP para extender con atributos de contexto de trazado.
span: opcional - tramo - predeterminado: The current active span.
El tramo para inyectar su contexto en los encabezados de solicitud proporcionados. Cualquier tramo (incluyendo aquellos con decoradores de función), por defecto corresponde al tramo activo actual.

Activando encabezados distribuidos

El método LLMObs.activate_distributed_headers() toma encabezados HTTP y extrae atributos de contexto de trazado para activar en el nuevo servicio.

Nota: Debe llamar a LLMObs.activate_distributed_headers() antes de iniciar cualquier tramo en su servicio descendente. Los tramos iniciados previamente (incluyendo los tramos de decoradores de función) no se capturan en el trazado distribuido.

Este método acepta el siguiente argumento:

request_headers: requerido - diccionario
Los encabezados HTTP para extraer atributos del contexto de trazado.

Ejemplo

client.py

from ddtrace.llmobs import LLMObs
from ddtrace.llmobs.decorators import workflow

@workflow
def client_send_request():
    request_headers = {}
    request_headers = LLMObs.inject_distributed_headers(request_headers)
    send_request("<method>", request_headers)  # arbitrary HTTP call

server.py

from ddtrace.llmobs import LLMObs

def server_process_request(request):
    LLMObs.activate_distributed_headers(request.headers)
    with LLMObs.task(name="process_request") as span:
        pass  # arbitrary server work

La biblioteca dd-trace proporciona integraciones listas para usar que soportan trazado distribuido para marcos web populares. Requerir el trazador habilita automáticamente estas integraciones, pero puedes desactivarlas opcionalmente con:

const tracer = require('dd-trace').init({
  llmobs: { ... },
})
tracer.use('http', false) // disable the http integration

Trazado avanzado

Trazado de tramos utilizando métodos en línea

Para cada tipo de tramo, la clase ddtrace.llmobs.LLMObs proporciona un método en línea correspondiente para trazar automáticamente la operación que implica un bloque de código dado. Estos métodos tienen la misma firma de argumento que sus contrapartes de decorador de función, con la adición de que name por defecto es el tipo de tramo (llm, workflow, etc.) si no se proporciona. Estos métodos pueden ser utilizados como administradores de contexto para finalizar automáticamente el tramo después de que se complete el bloque de código encerrado.

Ejemplo

from ddtrace.llmobs import LLMObs

def process_message():
    with LLMObs.workflow(name="process_message", session_id="<SESSION_ID>", ml_app="<ML_APP>") as workflow_span:
        ... # user application logic
    return

Persistiendo un tramo a través de contextos

Para iniciar y detener manualmente un tramo a través de diferentes contextos:

Inicia un tramo manualmente utilizando los mismos métodos (por ejemplo, el método LLMObs.workflow para un tramo de flujo de trabajo), pero como una llamada de función simple en lugar de como un administrador de contexto.
Pasa el objeto de tramo como un argumento a otras funciones.
Detén el tramo manualmente con el método span.finish(). Nota: el tramo debe finalizarse manualmente, de lo contrario no se envía.

Ejemplo

from ddtrace.llmobs import LLMObs

def process_message():
    workflow_span = LLMObs.workflow(name="process_message")
    ... # user application logic
    separate_task(workflow_span)
    return

def separate_task(workflow_span):
    ... # user application logic
    workflow_span.finish()
    return

Forzar el vaciado en entornos sin servidor

LLMObs.flush() es una función bloqueante que envía todos los datos de observabilidad de LLM en búfer al backend de Datadog. Esto puede ser útil en entornos sin servidor para evitar que una aplicación se cierre hasta que se envíen todas las trazas de observabilidad de LLM.

Rastreo de múltiples aplicaciones

El SDK admite el rastreo de múltiples aplicaciones LLM desde el mismo servicio.

Puedes configurar una variable de entorno DD_LLMOBS_ML_APP con el nombre de tu aplicación LLM, en la que se agrupan por defecto todos los tramos generados.

Para anular esta configuración y usar un nombre de aplicación LLM diferente para un tramo raíz dado, pasa el argumento ml_app con el nombre de cadena de la aplicación LLM subyacente al iniciar un tramo raíz para una nueva traza o un tramo en un nuevo proceso.

from ddtrace.llmobs.decorators import workflow

@workflow(name="process_message", ml_app="<NON_DEFAULT_ML_APP_NAME>")
def process_message():
    ... # user application logic
    return

Trazado de tramos utilizando métodos en línea

El llmobs SDK proporciona un método en línea correspondiente para trazar automáticamente la operación que implica un bloque de código dado. Estos métodos tienen la misma firma de argumentos que sus contrapartes de envoltura de función, con la adición de que name es requerido, ya que el nombre no puede inferirse de un callback anónimo. Este método finalizará el tramo bajo las siguientes condiciones:

Si la función devuelve una Promesa, entonces el tramo finaliza cuando la promesa se resuelve o se rechaza.
Si la función toma un callback como su último parámetro, entonces el tramo finaliza cuando se llama a ese callback.
Si la función no acepta un callback y no devuelve una Promesa, entonces el tramo finaliza al final de la ejecución de la función.

Ejemplo sin un callback

function processMessage () {
  return llmobs.trace({ kind: 'workflow', name: 'processMessage', sessionId: '<SESSION_ID>', mlApp: '<ML_APP>' }, workflowSpan => {
    ... // user application logic
    return
  })
}

Ejemplo con un callback

function processMessage () {
  return llmobs.trace({ kind: 'workflow', name: 'processMessage', sessionId: '<SESSION_ID>', mlApp: '<ML_APP>' }, (workflowSpan, cb) => {
    ... // user application logic
    let maybeError = ...
    cb(maybeError) // the span will finish here, and tag the error if it is not null or undefined
    return
  })
}

El tipo de retorno de esta función coincide con el tipo de retorno de la función trazada:

function processMessage () {
  const result = llmobs.trace({ kind: 'workflow', name: 'processMessage', sessionId: '<SESSION_ID>', mlApp: '<ML_APP>' }, workflowSpan => {
    ... // user application logic
    return 'hello world'
  })

  console.log(result) // 'hello world'
  return result
}

Decoradores de función en TypeScript

El SDK de LLM Observability de Node.js ofrece una llmobs.decorate función que sirve como un decorador de función para aplicaciones de TypeScript. El comportamiento de traza de esta función es el mismo que llmobs.wrap.

Ejemplo

// index.ts
import tracer from 'dd-trace';
tracer.init({
  llmobs: {
    mlApp: "<YOUR_ML_APP_NAME>",
  },
});

const { llmobs } = tracer;

class MyAgent {
  @llmobs.decorate({ kind: 'agent' })
  async runChain () {
    ... // user application logic
    return
  }
}

Forzar el vaciado en entornos sin servidor

llmobs.flush() es una función bloqueante que envía todos los datos de observabilidad de LLM en búfer al backend de Datadog. Esto puede ser útil en entornos sin servidor para evitar que una aplicación se cierre hasta que se envíen todas las trazas de LLM Observability.

Rastreo de múltiples aplicaciones

El SDK admite el rastreo de múltiples aplicaciones de LLM desde el mismo servicio.

Puedes configurar una variable de entorno DD_LLMOBS_ML_APP con el nombre de tu aplicación LLM, en la que se agrupan por defecto todos los tramos generados.

Para anular esta configuración y usar un nombre de aplicación LLM diferente para un tramo raíz dado, pasa el argumento mlApp con el nombre de cadena de la aplicación LLM subyacente al iniciar un tramo raíz para una nueva traza o un tramo en un nuevo proceso.

function processMessage () {
  ... // user application logic
  return
}
processMessage = llmobs.wrap({ kind: 'workflow', name: 'processMessage', mlApp: '<NON_DEFAULT_ML_APP_NAME>' }, processMessage)

Directrices para nombrar aplicaciones

El nombre de tu aplicación (el valor de DD_LLMOBS_ML_APP) debe seguir estas directrices:

Debe ser una cadena Unicode en minúsculas
Puede tener hasta 193 caracteres de longitud
No puede contener guiones bajos contiguos o finales
Puede contener los siguientes caracteres:
- Alfanuméricos
- Guiones bajos
- Guiones
- Dos puntos
- Puntos
- Barras

Lectura adicional

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

Rastrea, compara y optimiza tus prompts de LLM con Datadog LLM ObservabilityBLOG