트레이스 워크플로우
트레이스 워크플로우 (Trace Workflows)
트레이스, 스팬, 스레드가 플랫폼에 도착한 뒤 어떤 일이 일어나는지 한눈에 보고 싶을 때가 있죠. Workflows는 post-ingestion 파이프라인 전체(데이터셋 ingest, 큐 ingest, 평가 규칙, 분류기)를 그래프로 시각화하고 아래의 탭들로 관리하게 해주는 화면이에요. 이 글에서 각 워크플로우를 살펴볼게요.
출처: 문서
본문
Workflows는 트레이스, 스팬, 스레드에 대한 post-ingestion 파이프라인 전체를 단일 뷰로 보여줘요. 데이터셋 ingest 작업, 큐 ingest 작업, 평가 규칙, 분류기를 그래프로 시각화하고 그 아래의 탭들로 관리해요.
Workflows — post-ingestion 파이프라인 전체를 그래프로
위쪽의 Traces, Spans, Threads 버튼으로 그래프와 모든 탭을 특정 엔터티 타입으로 한정할 수 있어요. 페이지의 모든 것이 해당 타입에 관련된 워크플로우만 보여주도록 갱신돼요.
데이터셋 Ingest (Dataset Ingestion)
데이터셋 ingest 작업은 일치하는 트레이스, 스팬, 스레드를 golden으로 데이터셋에 지속적으로 흡수해요. 각 작업은 들어오는 데이터에 대해 자동으로 실행되며, 조건에 맞는 항목을 수동 개입 없이 대상 데이터셋에 추가해요.
데이터셋 Ingest
데이터셋 ingest 작업을 만들려면:
- Workflows로 이동해 Traces, Spans, 또는 Threads를 선택해요.
- Dataset Ingestion 탭을 클릭해요.
- New ingestion task를 클릭해요.
- 사이드 드로어에서 작업을 구성해요 — 대상 데이터셋 선택, 필터 설정, 작업 이름 지정.
- 작업을 저장해요.
각 작업 행은 이름, 대상 데이터셋, 데이터 모델, golden 수를 보여줘요. 토글로 삭제하지 않고 작업을 켜거나 끌 수 있어요. 편집 아이콘으로 구성을 갱신하고, 삭제 아이콘으로 영구 제거해요.
큐 Ingest (Queue Ingestion)
큐 ingest 작업은 일치하는 트레이스, 스팬, 스레드를 인간 검토용 annotation queue로 지속적으로 라우팅해요. 특정 기준을 만족하는 데이터로 큐를 자동으로 채우는 데 사용해요.
큐 Ingest
큐 ingest 작업을 만들려면:
- Workflows로 이동해 Traces, Spans, 또는 Threads를 선택해요.
- Queue Ingestion 탭을 클릭해요.
- New ingestion task를 클릭해요.
- 대상 annotation queue를 선택하고 사이드 드로어에서 작업을 구성해요.
- 작업을 저장해요.
각 작업 행은 이름, 대상 큐, 데이터 모델, 지금까지 ingest된 항목 수를 보여줘요. 토글, 편집, 삭제는 데이터셋 ingest 작업과 같은 방식으로 동작해요.
평가 규칙 (Evaluation Rules)
평가 규칙은 코드 변경 없이 ingest 시점에 들어오는 트레이스, 스팬, 스레드에서 metric collection을 자동 실행해요. 규칙은 데이터를 만든 SDK 호출이 이미 metric collection을 제공하지 않은 경우에만 발동하므로, 인라인 평가를 보완하는 코드 없는(no-code) 방식이에요.
평가 규칙
SDK 호출이 이미
metric_collection을 전달하면 그 값이 우선돼요 — 해당 항목에 대해 규칙은 건너뛰어져요. 규칙은 SDK가 metric collection을 제공하지 않을 때만 평가를 부착해요.
평가 규칙을 만들려면:
- Workflows로 이동해 Traces, Spans, 또는 Threads를 선택해요.
- Evaluation Rules 탭을 클릭해요.
- New rule을 클릭해요.
- 사이드 드로어에서 규칙을 구성해요(아래 필드 참조).
- Create Rule을 클릭해요.
필드
| 필드 | 필수 | 설명 |
|---|---|---|
| Name | 예 | 규칙의 고유한 이름. |
| Description | 아니요 | 규칙의 목적에 대한 선택적 맥락. |
| Enabled | 예 | 켜면 활성화돼요. 비활성화된 규칙은 저장되지만 ingest 시점에 건너뛰어져요. |
| Data Model | 예 | Trace, Span, 또는 Thread — 규칙이 무엇에, 언제 실행되는지 결정해요. |
| Span Type | Span 규칙 전용 | 특정 span 타입으로 제한: LLM, Agent, Tool, Retriever, 또는 Custom. 모든 span을 매칭하려면 Any로 두세요. |
| Metric Collection | 예 | 실행할 metric collection. Trace와 span 규칙은 single-turn 컬렉션을, thread 규칙은 multi-turn 컬렉션을 요구해요. |
| Filters | 아니요 | 규칙을 데이터 하위 집합으로 한정해요(예: 특정 환경, 태그, 메타데이터 값). 비우면 모든 엔터티를 매칭해요. |
| Sample Rate | 아니요 | 규칙이 발동하는 일치 엔터티의 비율(0.0–1.0). 샘플링은 결정적이에요 — 같은 항목은 주어진 규칙에 대해 항상 같은 결정을 해요. 기본값은 1.0. 컬렉션 및 메트릭별 비율이 어떻게 합쳐지는지는 Sample Rate를 참고하세요. |
| Time Limit | Thread 규칙 전용 | 스레드가 평가 대상이 되기 전에 필요한 비활성 초 수. 이 기간 동안 새 트레이스가 없으면 스레드가 평가돼요. 기본값은 300. |
| Overwrite Evaluations | Thread 규칙 전용 | on이면 각 유휴 주기마다 이전 평가를 대체해요. off(기본)면 각 주기마다 새 메트릭 행 세트를 추가해 전체 이력을 보존해요. |
데이터 모델
| 데이터 모델 | 언제 실행되나요 | metric collection 타입 |
|---|---|---|
| Trace | ingest 시점에 각 들어오는 트레이스마다 | Single-turn |
| Span | ingest 시점에 각 들어오는 스팬마다 | Single-turn |
| Thread | 스레드가 구성된 time limit 동안 유휴 상태가 된 뒤 | Multi-turn |
필터
필터는 규칙이 적용되는 트레이스, 스팬, 스레드를 좁혀요. 환경, 태그, 메타데이터 필드, 지연 시간, 그 밖의 차원을 대상으로 할 수 있어요. eval 메트릭, annotation, signal용 필터 탭은 규칙에는 사용할 수 없어요 — 그 차원들은 ingest 시점에는 존재하지 않기 때문이에요.
선택한 데이터 모델의 모든 엔터티를 매칭하려면 Filters를 비워 두세요.
Thread 규칙과 API metric collection
스레드의 경우 평가 규칙이 자동 평가의 주요 실행 방식이에요 — 스레드 수준 평가를 촉발하는 인라인 SDK 파라미터는 없어요. 필요하면 Evaluate Threads 함수로 스레드를 명시적으로 평가할 수도 있어요.
특정 metric collection을 대상으로 하는 활성 thread 규칙은 한 번에 하나만 가능해요. 같은 컬렉션을 대상으로 하는 다른 활성 thread 규칙과 충돌하는 규칙을 켜는 것은, 충돌 규칙이 비활성화될 때까지 차단돼요.
분류기 (Classifiers)
분류기는 ingest되는 트레이스와 스레드에, 내가 정의한 설명과 라벨 세트를 기반으로 라벨을 할당해요. 분류기가 만드는 라벨은 Signals와 Observatory·Dashboards 전반의 필터 가능한 차원으로 표면화돼요.
분류기
분류기는 Spans에는 사용할 수 없어요. 분류기를 보고 관리하려면 Traces 또는 Threads 탭으로 전환하세요.
분류기는 어떻게 판단하나요?
분류기가 실행되면 내부의 LLM은 다음을 받아요.
- 분류기의 설명 — 이 분류기가 무엇을 찾는가?
- 라벨 목록과 각 라벨의 설명 — 이 라벨은 언제 할당되어야 하는가?
- 트레이스 또는 스레드 페이로드 — input, output, metadata, error, tags, 그리고 (스레드의 경우) 대화 턴.
모델은 라벨 하나를 고르거나 "no match"를 반환해요. 규칙 엔진도, 메타데이터 기반 사전 필터링도, 정규 표현식도 없어요. 설명이 데이터에 대해 어떻게 읽히는지에 따라 모든 것이 결정돼요.
구체성이 중요해요. 모호한 라벨 설명은 모호한 라벨을 만들어요. 각 설명의 구체적인 예시(예: "사용자가 실망을 표현하거나, 포기하거나, 오답 때문에 같은 질문을 다시 말하면
Negative로 라벨링")가 다른 어떤 수단보다 정확도를 끌어올려요.
분류기 만들기
분류기를 만들려면:
- Workflows로 이동해 Traces 또는 Threads를 선택해요.
- Classifiers 탭을 클릭해요.
- New classifier를 클릭해요.
- 대화상자에서 분류기에 이름과 설명을 줘요.
- 분류기를 저장해요.
만든 뒤 행의 편집 아이콘을 클릭하면 사이드 드로어에서 분류기 편집기가 열려요. 여기서 라벨을 관리하고 생성 설정을 구성해요.
라벨
각 분류기에는 하나 이상의 라벨이 있어요. New Label(Name + Description)로 수동으로 추가하거나, Generate Labels로 대량 자동 제안할 수 있어요. 각 라벨은 자체 활성화 토글이 있는데, 비활성화된 라벨은 새 항목에 할당되지 않지만 분류기의 이력에는 남아요.
라벨 생성 (Generate Labels)
아직 필요한 라벨을 모른다면, Generate Labels는 최근 트레이스 또는 스레드에서 라벨 세트를 제안해요. 먼저 Configure Generation을 클릭해 프롬프트와 클러스터링 파라미터를 설정하고, 그다음 Generate Labels로 3단계 파이프라인을 실행해요.
- Summarizing — 모델이 구성된 요약 프롬프트로 최근 트레이스/스레드 샘플을 요약해요.
- Clustering — 요약이 K-means로 구성된 클러스터 수로 그룹화돼요.
- Labeling — 각 클러스터가 후보 라벨(이름 + 설명)로 바뀌어 행에 Recommended로 표시돼요.
추천 라벨은 일반 편집 메뉴 대신 Accept(✓)와 Decline(✕) 동작을 보여줘요. 수락된 라벨은 일반 라벨이 되어 다음 ingest 틱부터 실행돼요. 거절된 라벨은 삭제돼요. 추천이 아직 보류 중인데 재생성을 실행하면 기존 것들이 먼저 버려져요.
생성 구성(요약 프롬프트와 클러스터 수)은 Generate Labels 버튼이 활성화되기 전에 저장되어야 해요.
자동 분류 (Auto Classify)
분류기 편집기의 Auto Classify 토글은 최상위 Enabled 토글과 별개예요.
- Enabled — 분류기를 완전히 켜거나 끄는 스위치.
- Auto Classify — on이면 기존 라벨이 트레이스/스레드에 맞지 않을 때 분류기가 새 라벨(라벨 목록에 Recommended로 저장)을 제안할 수 있어요. off면 이미 정의한 라벨에서만 고르거나 no match를 반환해요.
엣지 케이스를 계속 발견하고 싶으면 Auto Classify를 켜 두고, 고정된 분류 체계(taxonomy)를 원하면 끄면 돼요.
Sample rate
분류기 목록 아래의 Sample Rate는 들어오는 트레이스(또는 스레드)의 어느 비율을 분류에 보낼지 제어해요 — 1.0은 모든 것을 분류하고, 0.1은 대략 10개 중 1개를 분류해요. 해당 데이터 모델의 모든 활성 분류기가 공유하는 프로젝트 전역 설정이에요.
Time limit (스레드 전용)
thread 분류기의 경우 Time Limit은 스레드가 분류 대상이 되기 전에 필요한 비활성 초 수를 정의해요. 이 기간 동안 새 트레이스가 없으면 분류가 실행돼요. 후속 턴이 더는 안 오는 정도로는 길고, 대화 창을 놓치지 않을 정도로는 짧게 설정하세요.
비용
각 분류는 청구를 위해 사용 이벤트를 기록해요. 실시간 사용량과 예상 비용은 **Project Settings → Data Usage**의 Signals 줄에서 확인할 수 있어요.
Signals
분류기 라벨이 어떻게 Signals(카드, 분석, 추세 발견, Observatory 필터)로 표면화되는지 확인해보세요.
Dashboards
대시보드 위젯에서 메트릭을 분류기 라벨로 쪼개거나, 라벨의 볼륨을 시간에 따라 추세로 볼 수 있어요.
더 알아보기
- LLM Tracing Troubleshooting — tracing 시 흔한 문제와 해결책
- Online Evals — ingest 시점의 온라인 평가