Referencia del SDK de LLM Observability

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

Esta traducción no está actualizada. Para consultar la última versión en inglés, haz clic aquí

Descripción general

Los SDK de LLM Observability de Datadog proveen instrumentación automática, así como APIs de instrumentación manual, para ofrecer observabilidad e información sobre tus aplicaciones LLM.

Configuración

Requisitos

Una clave de API de Datadog.

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

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

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

Configuración de 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 destino para el envío de datos LLM. Tu sitio es .
DD_LLMOBS_ENABLED: requerido - entero o cadena
Alterna 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 tu aplicación, servicio o proyecto de 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 span 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 requerido si no estás utilizando el Agente de Datadog, en cuyo caso esto debería configurarse en 1 o true.
DD_API_KEY: opcional - cadena
Tu clave de API de Datadog. Solo es necesario si no estás utilizando el Agente de Datadog.

Habilita LLM Observability ejecutando tu 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 tus datos LLM. Tu sitio es .
DD_LLMOBS_ENABLED: requerido - entero o cadena
Alterna 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 tu 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. Consulta Directrices de nomenclatura de aplicaciones para caracteres permitidos y otras restricciones. Para anular este valor para un tramo raíz dado, consulta 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 requerido si no estás utilizando el Agente de Datadog, en cuyo caso esto debería configurarse en 1 o true.
DD_API_KEY: opcional - cadena
Tu clave de API de Datadog. Solo es necesario si no estás utilizando el Agente de Datadog.

Habilita LLM Observability ejecutando tu 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

Puedes 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 destino para el envío 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 LLM Observability. Debería estar configurado en 1 o true.
DD_LLMOBS_ML_APP o dd.llmobs.ml.app: opcional - cadena
El nombre de tu 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. Consulta Directrices de nomenclatura de aplicaciones para caracteres permitidos y otras restricciones. Para anular este valor para un tramo raíz dado, consulta 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 requerido si no estás utilizando el Agente de Datadog, en cuyo caso esto debe establecerse en 1 o true.
DD_API_KEY o dd.api.key: opcional - cadena
Tu clave de API de Datadog. Solo es necesario si no estás utilizando el Agente de Datadog.

Configuración en código

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

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

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

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 tu 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. Consulta Directrices de nomenclatura de aplicaciones para caracteres permitidos y otras restricciones. Para anular este valor para una traza dada, consulta Rastreo de múltiples aplicaciones. Si no se proporciona, esto se establece de forma predeterminada al valor de DD_LLMOBS_ML_APP.
integrations_enabled - predeterminado: true: opcional - booleano
Una bandera para habilitar automáticamente el rastreo de llamadas LLM para las integraciones de LLM soportadas por Datadog. Si no se proporciona, todas las integraciones de LLM soportadas están habilitadas por defecto. Para evitar el uso de las integraciones de LLM, establece este valor en false.
agentless_enabled: opcional - booleano - predeterminado: false
Solo es necesario si no estás utilizando el Agente de Datadog, en cuyo caso esto debería establecerse en True. Esto configura la biblioteca ddtrace para no enviar ningún dato que requiera el Agente de Datadog. Si no se proporciona, esto se establece de forma predeterminada al valor de DD_LLMOBS_AGENTLESS_ENABLED.
site: opcional - cadena
El sitio de Datadog para enviar los datos de tu LLM. Tu sitio es . Si no se proporciona, esto se establece en el valor de DD_SITE.
api_key: opcional - cadena
Tu clave de API de Datadog. Solo es necesario si no estás utilizando el Agente de Datadog. Si no se proporciona, esto se establece en el 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 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 en el valor de DD_SERVICE.

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

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

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 configuración de llmobs

mlApp: opcional - cadena
El nombre de tu aplicación LLM, servicio o proyecto, bajo el cual se agrupan todos los rastros y spans. 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 un rastreo dado, consulta Rastreo de múltiples aplicaciones. Si no se proporciona, esto se establece en el valor de DD_LLMOBS_ML_APP.
agentlessEnabled: opcional - booleano - predeterminado: false
Solo es necesario si no estás utilizando el Agente de Datadog, en cuyo caso esto debe configurarse en true. Esto configura la biblioteca dd-trace para no enviar ningún dato que requiera el Agente de Datadog. Si no se proporciona, esto se establece por defecto 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 los datos de tu LLM. Tu sitio es . Si no se proporciona, esto se establece en el 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 por defecto 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 en el 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ás utilizando el Agente de Datadog.

Configuración de AWS Lambda

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

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

npm install -g @datadog/datadog-ci

Configura la clave 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 Secrets Manager, puedes establecer la clave 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 capa de extensión de Datadog).

datadog-ci lambda instrument -f <YOUR_LAMBDA_FUNCTION_NAME> -r <AWS_REGION> -v 125 -e 97 --llmobs <YOUR_LLMOBS_ML_APP>

datadog-ci lambda instrument -f <YOUR_LAMBDA_FUNCTION_NAME> -r <AWS_REGION> -v 139 -e 97 --llmobs <YOUR_LLMOBS_ML_APP>

datadog-ci lambda instrument -f <YOUR_LAMBDA_FUNCTION_NAME> -r <AWS_REGION> -v 27 -e 97 --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 retorne.

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 auto-instrumentación. La instrumentación manual puede ser utilizada para capturar marcos personalizados o operaciones de bibliotecas que aún no son compatibles.

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 de grano fino:

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 un 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 tramo son requeridos y se especifican en el objeto options que se pasa a las funciones de trazado llmobs (trace, wrap y decorate). Consulta la documentación de Tipos de tramos para una lista 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 necesita anotar manualmente un tramo, consulte 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 name propiedad 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 rastreado en línea en su lugar. consulta Rastreando tramos utilizando 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 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 él y registrar datos.

Finalizando un tramo

Los tramos deben completarse para que la traza se envíe y sea 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 try/finally para asegurar que 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();
    }

Las 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 rastrear estas operaciones.

Si estás instrumentando manualmente un tramo de LLM, debes registrar los conteos de tokens (como input_tokens, output_tokens, y total_tokens) tú mismo anotando el tramo. Consulta Enriqueciendo tramos para más información.

Para rastrear 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 establece de forma predeterminada en el nombre de la función rastreada.
model_provider: opcional - cadena - predeterminado: "custom"
El nombre del proveedor del modelo.
Nota: Para mostrar el costo estimado en dólares estadounidenses, establezca 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 import LLMObs
from ddtrace.llmobs.decorators import llm

@llm(model_name="claude", name="invoke_llm", model_provider="anthropic")
def llm_call(prompt):
    completion = ... # user application logic to invoke LLM
    LLMObs.annotate(
        input_data=[{"role": "user", "content": prompt}],
        output_data=[{"role": "assistant", "content": completion}],
        metrics={"input_tokens": 4, "output_tokens": 6, "total_tokens": 10},
    )
    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 Trazado de múltiples aplicaciones para más información.

Ejemplo

function llmCall (prompt) {
  const completion = ... // user application logic to invoke LLM
  llmobs.annotate({
    inputData: [{ role: "user", content: prompt }],
    outputData: [{ role: "assistant", content: completion }],
    metrics: { input_tokens: 4, output_tokens: 6, total_tokens: 10 }
  })
  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 de forma predeterminada 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.setMetrics(Map.of(
      "input_tokens", 617,
      "output_tokens", 338,
      "total_tokens", 955
    ));
    llmSpan.finish();
    return inference;
  }
}

Flujos de trabajo

Para rastrear un tramo de flujo de trabajo, utiliza 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 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 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. Consulta 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 de forma predeterminada 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. Consulta 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, importa y llama al siguiente método con los argumentos listados 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 de forma predeterminada 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. Consulta 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 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, utiliza 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 de forma predeterminada en el nombre de la función rastreada.
session_id: opcional - cadena
El ID de la sesión de usuario subyacente. Consulta 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. Consulta 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, especifica el tipo de tramo como agent, y opcionalmente especifica 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. Consulta 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. Consulta 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, importa y llama 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 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 proporcionado al inicio de la aplicación. Consulta Rastreo de múltiples aplicaciones para más información.
sessionId: opcional - Cadena
El ID de la sesión de usuario subyacente. Consulta Rastreo de sesiones de usuario para más información.

Llamadas a herramientas

Para rastrear una llamada a una herramienta, utiliza 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 de forma predeterminada en el nombre de la función rastreada.
session_id: opcional - cadena
El ID de la sesión de usuario subyacente. Consulta 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. Consulta 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, especifica el tipo de tramo como tool, y opcionalmente especifica 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. Consulta 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. Consulta 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 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 sobrescribe el nombre de la aplicación de ML suministrado al inicio de la aplicación. Consulta Rastreo de múltiples aplicaciones para más información.
sessionId: opcional - cadena
El ID de la sesión de usuario subyacente. Consulta Rastreo 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 de forma predeterminada en el nombre de la función rastreada.
session_id: opcional - cadena
El ID de la sesión de usuario subyacente. Consulta 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. Consulta 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 por defecto 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 Seguimiento 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 listados 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 por defecto 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 ML suministrado al inicio de la aplicación. Proporcionar un valor no nulo anula el nombre de la aplicación ML suministrado al inicio de la aplicación. Consulte Seguimiento 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.

Incrustaciones

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

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

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 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 embedding

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

Para rastrear una operación de incrustación, 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 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 Seguimiento 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 tramos. 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 por defecto 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 Seguimiento 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.

Argumentos

name: opcional - cadena
El nombre de la operación. Si no se proporciona, name se establece por defecto 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 Seguimiento de múltiples aplicaciones para más información.

Ejemplo

A continuación se incluye también un ejemplo de cómo anotar 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 metrics parámetro 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 span para generar métricas de plataforma correspondientes (como ml_obs.span.llm.input.tokens) para su uso en tableros y monitores.

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 al usar decoradores de función), el SDK anota el tramo activo actual.
input_data: opcional - tipo serializable en JSON o lista de diccionarios
Ya sea un tipo serializable en 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 en JSON o lista de diccionarios
Ya sea un tipo serializable en 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 requerida "name": "..." y claves opcionales "description": "..." y "schema": {...}.
metadata: opcional - diccionario
Un diccionario de pares clave-valor serializables en JSON que los usuarios pueden agregar como información de metadatos relevante a 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 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, 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 funciones), el SDK anota el tramo activo actual.
annotationOptions: requerido - objeto
Un objeto de diferentes tipos de datos para anotar el tramo.

El objeto annotationOptions puede contener lo siguiente:

inputData: opcional - tipo serializable en JSON o lista de objetos
Ya sea un tipo serializable en JSON (para tramos que no son LLM) o una lista de diccionarios con este formato: {role: "...", contenido: "..."} (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 que no son 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 para 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 de LLM.

Argumentos

Si un argumento es nulo o está 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 que no son LLM) o una lista de LLMObs.LLMMessages para tramos LLM.
outputData: opcional - Cadena o Lista<LLMObs.LLMMessage>
Ya sea una cadena (para tramos que no son LLM) o una lista de LLMObs.LLMMessages para tramos LLM.

Mensajes LLM

Los tramos LLM deben ser anotados con mensajes LLM utilizando 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 métrica única

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

Argumentos

key: requerido - _ CharSequence_
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 - _ Map<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 etiqueta única

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

Argumentos

key: requerido - Cadena
La clave de la etiqueta.
value: requerido - int, long, doble, booleano, 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 setErrorMessage() método miembro de la LLMObsSpan interfaz acepta el siguiente argumento para adjuntar una cadena de error:

Argumentos

errorMessage: requerido - Cadena
El mensaje del error.

Estableciendo una bandera de error

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

Argumentos

error: requerido - booleano
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 setMetadata() miembro de la interfaz LLMObsSpan acepta los siguientes argumentos:

metadata: requerido - Map<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 reemplaza 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 objeto Prompt de ddtrace.llmobs.utils y pasarlo como el argumento prompt. Nota: Este argumento solo se aplica a los tramos 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 las 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 reemplaza 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 prompts

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

Utilice LLMObs.annotation_context(prompt=...) para adjuntar metadatos del 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”). Consulta seguimiento de versiones para más detalles.
variables (Dict[str, str]): Variables utilizadas para llenar los marcadores de posición de la plantilla.
template (str): Cadena de plantilla con marcadores de posición (por ejemplo, "Traducir {{text}} to {{lang}}").
chat_template (List[Mensaje]): Forma 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 (List[str]): Claves de variables que contienen contenido de verdad contextual. Utilizado para detección de alucinaciones.
rag_query_variables (List[str]): Claves de 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 prompt 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 del 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 (string): Etiqueta de versión para el prompt (por ejemplo, “1.0.0”). Consulta seguimiento de versiones para más detalles.
variables (Record<string, string>): Variables utilizadas para llenar los marcadores de posición de la plantilla.
template (string | List[Message]): Template string with placeholders (for example, "Translate {{texto}} a {{lang}}"). Alternatively, a list of { "role": "<role>", "content": "<template string with placeholders>" } objects.
tags (Record<string, string>): Etiquetas para adjuntar a la ejecución del prompt.
contextVariables (string[]): Claves de variables que contienen el contenido de ground truth y de contexto. Utilizado para detección de alucinaciones.
queryVariables (string[]): Claves de variables que contienen la consulta del usuario. Utilizado para 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

Anotar 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 placeholder (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 al calcular 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 de template o chat_template para generar automáticamente un identificador de versión numérico.
Versionado manual: Cuando se proporciona una etiqueta version, LLM Observability utiliza tu etiqueta de versión especificada exactamente como se proporcionó.
Historial de versiones: Tanto las versiones auto-generadas como las manuales se mantienen en el historial de versiones para rastrear la evolución del prompt a lo largo del tiempo.

Esto te 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 tus propias etiquetas de versión.

Monitoreo de costos

Adjunta métricas de tokens (para seguimiento automático de costos) o métricas de costos (para seguimiento manual de costos) a tus 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 costo te permiten proporcionar tu propio precio al usar modelos personalizados o no soportados. Para más detalles, consulta Costos.

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

En este contexto, "métricas de tokens" y "métricas de costos" se refieren a pares clave-valor numéricos que adjuntas a los tramos a través del metrics parámetro del LLMObs.annotate() método. Estos son distintos de las métricas de observabilidad LLM 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 métricas de plataforma correspondientes (como ml_obs.span.llm.input.cost) para su uso en tableros y seguimiento.

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

Datadog admite proveedores de modelos comunes como OpenAI, Azure OpenAI, Anthropic y Google Gemini. Al usar estos proveedores, solo necesitas anotar tu solicitud LLM con model_name, model_provider y el uso de tokens. Datadog calcula automáticamente el costo estimado basado en los precios 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: Usando un modelo personalizado

Para modelos personalizados o no soportados, debes 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 Observabilidad LLM proporciona métodos para exportar y enviar tus evaluaciones a Datadog.

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

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

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

Exportando un tramo

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

Argumentos

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

span: opcional - Tramo
El tramo del cual extraer el contexto (ID de tramo e ID de traza). Si no se proporciona (como al usar 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 de un tramo. Necesitarás usar este método para asociar tu evaluación con el tramo correspondiente.

Argumentos

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

span: opcional - Tramo
El tramo para extraer el contexto del tramo (tramo e IDs de traza) de. Si no se proporciona (como al usar 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 tu 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, renombra tu LLMObs.submit_evaluation_for llamadas con LLMObs.submit_evaluation.

Nota: Las evaluaciones personalizadas son evaluadores que implementas y alojas tú 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 en tu aplicación, usa la página Observabilidad LLM > Configuraciones > 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 diccionario
El valor de la evaluación. Debe ser una cadena (metric_type==categorical), entero/flotante (metric_type==score), booleano (metric_type==boolean) o diccionario (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). Usa 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: Exactamente uno de span o span_with_tag_value es requerido. 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, el valor predeterminado será 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 evaluació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 asocia la evaluación. Esto debe 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 - 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 cadena que los usuarios pueden agregar como etiquetas relacionadas con la evaluación. Para más información sobre las etiquetas, consulte Introducción a las Etiquetas.
assessment: opcional - cadena
Una evaluació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 asocia 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 - Mapa<String, Object>
Un diccionario de pares clave-valor de cadenas utilizado 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 procesadora. La función procesadora tiene acceso a las etiquetas de tramo para permitir la modificación condicional de entrada/salida. Las funciones procesadoras 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: evitando 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: evitando 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 un 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 sesión

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 del 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 span raíz para una nueva traza o span 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 un tramo en un nuevo proceso, especifique el argumento sessionId con el ID de cadena de la sesión de usuario subyacente, que se envía como una etiqueta en el tramo.

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 tramo 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 de HTTP. Si su aplicación realiza solicitudes utilizando estas bibliotecas compatibles, puede habilitar el trazado distribuido ejecutando:

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

Si su aplicación no utiliza ninguna de estas bibliotecas compatibles, puede habilitar el trazado distribuido propagando manualmente la información de tramo 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 para ser incluidos 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 (incluidos aquellos con decoradores de función), se predetermina 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 (incluidos los 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 de 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 populares marcos web. Requerir el trazador habilita automáticamente estas integraciones, pero puede desactivarlas opcionalmente con:

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

Trazado avanzado

Trazando tramos usando 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 argumentos que sus contrapartes de decorador de función, con la adición de que name predetermina 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 o ámbitos:

Inicie 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.
Pase el objeto de tramo como un argumento a otras funciones.
Detenga 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 salga hasta que se envíen todas las trazas de observabilidad de LLM.

Rastreando múltiples aplicaciones

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

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

Para anular esta configuración y usar un nombre de aplicación de LLM diferente para un tramo raíz dado, pase el argumento ml_app con el nombre de cadena de la aplicación de 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

Trazando tramos usando métodos en línea

El SDK llmobs proporciona un método en línea correspondiente para rastrear 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 obligatorio, 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 termina cuando la promesa es resuelta o rechazada.
Si la función toma un callback como su último parámetro, entonces el tramo termina cuando ese callback es llamado.
Si la función no acepta un callback y no devuelve una Promesa, entonces el tramo termina 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 rastreada:

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 funciones en TypeScript

El SDK de Observabilidad LLM de Node.js ofrece una llmobs.decorate función que sirve como un decorador de funciones para aplicaciones de TypeScript. El comportamiento de rastreo 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 salga hasta que se envíen todas las trazas de observabilidad de LLM.

Trazando múltiples aplicaciones

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

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

Para anular esta configuración y usar un nombre de aplicación de LLM diferente para un tramo raíz dado, pase el argumento mlApp con el nombre de cadena de la aplicación de 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 su 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 al final
Puede contener los siguientes caracteres:
- Alfanuméricos
- Guiones bajos
- Guiones
- Dos puntos
- Períodos
- Barra

Lectura adicional

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

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