Agent Observability HTTP API는 개발자가 LLM 관련 트레이스 및 스팬을 Datadog으로 전송하는 인터페이스를 제공합니다. 애플리케이션이 Python, Node.js 또는 Java로 작성된 경우 Agent Observability SDK를 사용할 수 있습니다.
API는 24시간 이내의 타임스탬프가 포함된 스팬을 허용하므로 지연된 데이터를 제한적으로 백필할 수 있습니다.
스팬 API
이 엔드포인트를 사용하여 Datadog으로 스팬을 전송합니다. 사용 가능한 스팬 종류에 대한 자세한 내용은 스팬 종류를 참조하세요.
{"data":{"type":"span","attributes":{"ml_app":"weather-bot","session_id":"1","feedback_join_key":"weather-request-123","tags":["service:weather-bot","env:staging","user_handle:example-user@example.com","user_id:1234"],"spans":[{"parent_id":"undefined","trace_id":"<TEST_TRACE_ID>","span_id":"<AGENT_SPAN_ID>","name":"health_coach_agent","meta":{"kind":"agent","input":{"value":"What is the weather like today and do i wear a jacket?"},"output":{"value":"It's very hot and sunny, there is no need for a jacket"}},"start_ns":1713889389104152000,"duration":10000000000},{"parent_id":"<AGENT_SPAN_ID>","trace_id":"<TEST_TRACE_ID>","span_id":"<WORKFLOW_ID>","name":"qa_workflow","meta":{"kind":"workflow","input":{"value":"What is the weather like today and do i wear a jacket?"},"output":{"value":"It's very hot and sunny, there is no need for a jacket"}},"start_ns":1713889389104152000,"duration":5000000000},{"parent_id":"<WORKFLOW_SPAN_ID>","trace_id":"<TEST_TRACE_ID>","span_id":"<LLM_SPAN_ID>","name":"generate_response","meta":{"kind":"llm","input":{"messages":[{"role":"system","content":"Your role is to ..."},{"role":"user","content":"What is the weather like today and do i wear a jacket?"}]},"output":{"messages":[{"content":"It's very hot and sunny, there is no need for a jacket","role":"assistant"}]}},"start_ns":1713889389104152000,"duration":2000000000}]}}}
Multi-message template form. Use placeholder syntax (like {{variable_name}}) to embed variables in message content. This should not be set with template).
variables
Dict[key (string), string]
템플릿을 렌더링하는 데 사용되는 변수입니다. 키는 템플릿의 자리 표시자 이름에 해당합니다.
query_variable_keys
[string]
사용자 쿼리를 포함하는 변수 키입니다. 환각 탐지에 사용됩니다.
context_variable_keys
[string]
실제/컨텍스트 콘텐츠를 포함하는 변수 키입니다. 환각 탐지에 사용됩니다.
tags
Dict[key (string), string]
프롬프트 실행에 첨부할 태그입니다.
{"id":"translation-prompt","chat_template":[{"role":"system","content":"You are a translation service. You translate to {{language}}."},{"role":"user","content":"{{user_input}}"}],"variables":{"language":"french","user_input":"<USER_INPUT_TEXT>"}}
Meta
필드
유형
설명
kind [필수]
string
스팬 종류는 "agent", "workflow", "llm", "tool", "task", "embedding" 또는 "retrieval"입니다.
이 엔드포인트를 사용하여 평가 및 최종 사용자 피드백을 Datadog으로 전송하세요. 평가는 스팬, 트레이스 또는 세션과 연결될 수 있습니다. 최종 사용자 피드백은 스팬, 트레이스, 세션 또는 고객이 정의한 피드백 조인 키와 연결될 수 있습니다.
엔드포인트
https://api./api/intake/llm-obs/v2/eval-metric
메서드
POST
eval_scope 필드를 사용하여 평가의 세분성을 설정하세요.
span(기본값): 평가가 특정 스팬과 연결됩니다. join_on을 사용하여 태그 키-값 쌍 또는 스팬 ID와 트레이스 ID 조합으로 대상 스팬을 식별하세요.
trace: 평가가 전체 트레이스와 연결됩니다. join_on를 사용하여 트레이스의 루트 스팬을 식별하세요.
session: 평가가 세션과 연결됩니다. join_on 대신 session_id를 제공하세요.
피드백을 제출하려면 event_kind을 feedback으로 설정하세요. 피드백 이벤트에는 submitter.id가 포함되어야 하며, join_on은 생략하고 span_id, trace_id, session_id, feedback_join_key 중 정확히 하나의 대상 필드를 제공해야 합니다. eval_scope가 생략되어 있으면 Datadog은 대상 필드에서 이를 추론합니다.
피드백이 단일 스팬, 트레이스 또는 세션이 아닌 인시던트 ID, 보고서 ID, 작업 ID 또는 릴리스 검사 ID와 같은 외부 엔터티에 적용되는 경우 feedback_join_key를 사용하세요. 피드백이 관련 텔레메트리와 함께 표시되도록 하려면 스팬 API를 사용하여 제출하거나 스팬 강화하기를 통해 feedback_join_key:incident-1234 태그를 추가할 때 관련 스팬에 동일한 feedback_join_key를 설정하세요.
피드백으로 대시보드 위젯을 만들려면 평가와 동일한 방식으로 위젯을 만들고 @event_kind:feedback 필터를 추가하세요.
피드백별로 스팬, 트레이스 또는 세션을 필터링하는 기능은 지원되지 않습니다. 예를 들어, 아직 불만족 피드백이 있는 트레이스만 필터링할 수는 없습니다. 대신 @event_kind:feedback 으로 범위가 지정된 대시보드를 사용하세요.
{"data":{"type":"evaluation_metric","attributes":{"metrics":[{"eval_scope":"span","join_on":{"span":{"span_id":"20245611112024561111","trace_id":"13932955089405749200"}},"ml_app":"weather-bot","timestamp_ms":1609459200,"metric_type":"categorical","label":"Sentiment","categorical_value":"Positive"},{"eval_scope":"trace","join_on":{"span":{"span_id":"20245611112024561111","trace_id":"13932955089405749200"}},"ml_app":"weather-bot","timestamp_ms":1609479200,"metric_type":"score","label":"Accuracy","score_value":3,"assessment":"fail","reasoning":"The response provided incorrect information about the weather forecast."},{"eval_scope":"session","session_id":"abc123def456","ml_app":"weather-bot","timestamp_ms":1609479200,"metric_type":"boolean","label":"Topic Relevancy","boolean_value":true},{"eval_scope":"span","join_on":{"tag":{"key":"msg_id","value":"1123132"}},"ml_app":"weather-bot","timestamp_ms":1609479200,"metric_type":"json","label":"Custom Evaluation","json_value":{"verdict":"pass","confidence":0.95,"is_valid":true,"metrics":{"accuracy":0.92,"precision":0.88},"passed_checks":["coherence","relevance","factuality"]}},{"event_kind":"feedback","feedback_join_key":"weather-request-123","ml_app":"weather-bot","timestamp_ms":1765990800016,"metric_type":"text","label":"user_comment","text_value":"The response did not answer whether I needed a jacket.","assessment":"fail","submitter":{"id":"user-123","type":"user"}}]}}}
{"data":{"type":"evaluation_metric","id":"456f4567-e89b-12d3-a456-426655440000","attributes":{"metrics":[{"id":"d4f36434-f0cd-47fc-884d-6996cee26da4","eval_scope":"span","join_on":{"span":{"span_id":"20245611112024561111","trace_id":"13932955089405749200"}},"ml_app":"weather-bot","timestamp_ms":1609459200,"metric_type":"categorical","label":"Sentiment","categorical_value":"Positive"},{"id":"cdfc4fc7-e2f6-4149-9c35-edc4bbf7b525","eval_scope":"trace","join_on":{"span":{"span_id":"20245611112024561111","trace_id":"13932955089405749200"}},"ml_app":"weather-bot","timestamp_ms":1609479200,"metric_type":"score","label":"Accuracy","score_value":3,"assessment":"fail","reasoning":"The response provided incorrect information about the weather forecast."},{"id":"haz3fc7-g3p2-1s37-8m12-ndk4hbf7a522","eval_scope":"session","session_id":"abc123def456","ml_app":"weather-bot","timestamp_ms":1609479200,"metric_type":"boolean","label":"Topic Relevancy","boolean_value":true},{"id":"abc1234-h4i5-6j78-9k01-lmn2opq3rst4","eval_scope":"span","join_on":{"tag":{"key":"msg_id","value":"1123132"}},"ml_app":"weather-bot","timestamp_ms":1609479200,"metric_type":"json","label":"Custom Evaluation","json_value":{"verdict":"pass","confidence":0.95,"is_valid":true,"metrics":{"accuracy":0.92,"precision":0.88},"passed_checks":["coherence","relevance","factuality"]}},{"id":"fedbk34-h4i5-6j78-9k01-lmn2opq3rst4","event_kind":"feedback","eval_scope":"external","feedback_join_key":"weather-request-123","ml_app":"weather-bot","timestamp_ms":1765990800016,"metric_type":"text","label":"user_comment","text_value":"The response did not answer whether I needed a jacket.","assessment":"fail","submitter":{"id":"user-123","type":"user"}}]}}}
피드백 이벤트의 경우 span_id, trace_id, session_id, feedback_join_key 중 정확히 하나를 제공하세요. eval_scope를 제공하는 경우 대상 필드와 일치해야 합니다. span_id는 "span"에 매핑되고, trace_id는 "trace"에 매핑되며, session_id는 "session"에 매핑되고, feedback_join_key는 "external"에 매핑됩니다.
