스팬 및 트레이스 쿼리

이 제품은 선택한 Datadog 사이트에서 지원되지 않습니다. ().

개요

이 페이지에서는 Datadog의 Agent Observability Trace Explorer를 사용하여 LLM 애플리케이션의 스팬과 트레이스를 쿼리하는 방법에 대해 설명합니다.

스팬 쿼리와 트레이스 쿼리 비교

Agent Observability에서 _스팬_은 LLM 애플리케이션에서 단일 작업을 나타내는 단위입니다. _트레이스_는 LLM 애플리케이션에서 요청을 처리하는 것과 관련된 엔드투엔드 작업을 나타내며, 종종 하나 이상의 중첩된 스팬으로 구성됩니다. 이 용어에 대한 자세한 내용은 Agent Observability 용어 및 개념을 참조하세요.

Agent Observability Trace Explorer에서 트레이스 또는 스팬 중에서 검색 대상을 선택합니다.

  • 루트 스팬이 쿼리와 일치하는 트레이스를 찾으려면 Traces를 선택합니다.
  • 중첩된 하위 스팬을 포함한 모든 스팬을 검색하려면 Spans를 선택합니다.

일부 검색어는 트레이스에만 적용됩니다. 예시는 트레이스 수준 쿼리를 참조하세요.

특성으로 쿼리

_스팬 특성_은 각 스팬에 직접 연결된 키-값 쌍입니다. 특성은 성능 메트릭, 리소스 식별자, 파라미터 값 등 스팬 실행에 대한 세부 정보를 캡처합니다.

특성 쿼리는 @key:value 형식을 취합니다. 모든 특성 키 앞에는 @ 기호가 붙습니다.

쿼리일치 항목
@duration:>5s완료하는 데 5초 이상 걸린 스팬

태그로 쿼리

_스팬 태그_는 스팬, 서비스, 환경 전반에 걸쳐 텔레메트리 데이터를 그룹화, 분할 및 상호 연관시키는 데 사용되는 키-값 쌍입니다. 태그는 종종 애플리케이션 이름, 환경 또는 배포 지역과 같은 더 넓은 컨텍스트를 나타내며, 효율적인 검색 및 집계를 용이하게 하기 위해 스팬에 연결됩니다.

태그 쿼리는 key:value 형식을 취합니다. 특성 키와 달리 태그 키 앞에는 @ 기호가 붙지 않습니다.

쿼리일치 항목
ml_app:my_llm_app이름이 my_llm_app

LLM 입력 및 출력 쿼리

자유 텍스트 쿼리를 사용하여 입력 또는 출력 쌍이 있는 모든 스팬에서 특정 키워드, 구문 또는 문자열을 검색할 수도 있습니다. 자유 텍스트 검색을 사용하려면 쿼리를 "로 래핑하세요.

쿼리일치 항목
"what's the weather"입력 또는 출력에 what's the weather 문자열을 포함하는 에이전트, 워크플로 또는 LLM 스팬
자유 텍스트 쿼리는 스팬 입력 또는 출력의 처음 20,500자로 제한됩니다.

연산자

AND(교집합), OR(합집합) 및 -(차집합) 불리언 연산자를 사용하여 여러 검색어를 결합할 수 있습니다.

쿼리일치 항목
@duration:>5s AND -"foo"완료하는 데 5초 이상 걸렸으며 입력 또는 출력에 foo 문자열을 포함하지 않는 스팬

쿼리 구문

Agent Observability Trace Explorer는 Datadog의 APM Trace Explorer와 동일한 쿼리 구문을 사용합니다. 와일드카드 검색, 숫자 값 처리, 특수 문자 이스케이프 등을 포함한 쿼리 구문에 대한 자세한 내용은 Trace Explorer 쿼리 구문을 참조하세요.

쿼리 예시

쿼리일치 항목
@status:error상태가 error
@meta.error.type:"Max turns exceeded"오류 유형이 Max turns exceeded
@duration:>5s완료하는 데 5초 이상 걸린 스팬 또는 트레이스
@trace.total_tokens:>=1000총 1000개 이상의 토큰을 소비한 트레이스
ml_app:my_llm_app이름이 my_llm_app
"what's the weather"입력 또는 출력에 what's the weather 문자열을 포함하는 에이전트, 워크플로 또는 LLM 스팬

평가 쿼리

@evaluation 특성을 사용하여 평가 결과별로 스팬 또는 트레이스를 찾으세요.

평가

평가 결과별로 스팬을 검색할 수 있습니다. 예를 들어, user_mood라는 평가가 있고, 범주형 값에 happy, sad, tired가 있는 경우, @evaluation.user_mood.value:happy 쿼리를 사용할 수 있습니다.

쿼리일치 항목
@evaluation.user_satisfaction.value:>5user_satisfaction
@evaluation.user_mood.value:happyuser_mood라는 평가(범주형 값에 happy, sad, tired

피드백 쿼리

@feedback 특성을 사용하여 최종 사용자 피드백 제출별로 스팬 또는 트레이스를 찾으세요. 예를 들어, 사용자가 user_satisfaction 레이블에 범주형 값 thumbs_up 또는 thumbs_down을 사용하여 피드백을 제출하는 경우 @feedback.user_satisfaction.value:thumbs_down 쿼리를 사용할 수 있습니다.

쿼리일치 항목
@feedback.user_satisfaction.value:thumbs_downuser_satisfaction
@feedback.user_comment.assessment:failuser_comment
@feedback.user_score.value:<2user_score

메타데이터 쿼리

@meta 특성을 사용하여 메타데이터 정보별로 스팬을 찾으세요.

쿼리일치 항목
@meta.span.kind:llmllm 스팬 종류의 스팬.
@meta.model_provider:openai모델 공급자가 OpenAI인 스팬 또는 트레이스
@meta.model_name:gpt-4.1모델이 GPT-4.1인 스팬 또는 트레이스

사용자 지정 메타데이터

계측 중에 첨부된 사용자 지정 메타데이터 필드별로 스팬 및 트레이스를 쿼리할 수 있습니다. 사용자 지정 메타데이터 필드는 @meta.metadata.<key>에서 액세스할 수 있습니다.

쿼리일치 항목
@meta.metadata.config.debug_mode:false사용자 지정 메타데이터 필드 config.debug_mode가 false
@meta.metadata.job_id:job_14fb81c3사용자 지정 메타데이터 필드 job_id가 job_14fb81c3

트레이스 수준 쿼리

중첩된 스팬의 특성을 기반으로 트레이스를 검색하려면 @child 특성을 사용하세요.

쿼리일치 항목
@child.@evaluation.hallucination.value:"hallucination found"환각(hallucination) 하위 스팬이 있는 트레이스
@child.@meta.span.kind:retrieval AND @meta.span.kind:workflow검색 스팬을 포함하는 워크플로 트레이스

@trace 특성을 사용하여 예상 총 비용, LLM 호출 수 또는 도구 수와 같은 트레이스 수준 정보에 액세스하세요.

쿼리일치 항목
@trace.llm_calls:>3LLM 호출이 3회 이상인 트레이스
@trace.tool_calls:>=4도구 호출이 4회 이상인 트레이스
@trace.number_of_tools:<55개 미만의 서로 다른 도구를 호출하는 트레이스

추가 자료

추가적인 유용한 설명서, 링크 및 기사:

Trace Explorer 쿼리 구문설명서 more more Agent Observability로 조사학습 센터 more more