런타임 컨트롤
런타임 컨트롤 (Runtime Controls)
프로덕션 관측성 지표를 임계값과 비교해 평가하는 컨트롤이에요. 이 문서에서는 런타임 컨트롤 구성 방법, 데이터 모델별 집계(aggregation), 임계값 동작, 그리고 흔히 쓰는 런타임 컨트롤 예시를 설명할게요.
출처: 문서
본문
런타임 컨트롤은 프로덕션 관측성 데이터를 임계값과 비교해 평가해요. 알림과 동일한 지표 모델을 쓰지만, 그 결과를 감사 가능한 거버넌스 요구사항으로 바꿔요.
각 런타임 컨트롤은 최근 24시간 기간(trailing 24-hour window) 을 평가해요.
런타임 컨트롤은 언제 사용하나요?
- 요구사항이 프로젝트 설정이 아니라 측정 가능한 프로덕션 동작에 달려 있을 때.
- 신뢰성, 품질, 지연 시간, 비용, 트래픽, 또는 인간 피드백 임계값을 지속적으로 강제해야 할 때.
- 요구사항이 정밀하게 필터링된 트레이스, 스팬, 스레드, 지표 결과, 어노테이션 집합에 적용되어야 할 때.
런타임 컨트롤 구성
런타임 컨트롤은 네 부분으로 구성돼요:
- 데이터 모델 — Trace, Span, Thread, Metric data, Annotation 중 선택해요.
- 집계(Aggregation) — 계산할 값을 선택해요. 사용 가능한 집계는 데이터 모델에 따라 달라져요.
- 임계값(Threshold) — Above 또는 Below를 선택하고 숫자 값을 입력해요.
- 필터(Filter) — 선택적으로 환경, 태그, 메타데이터, 기타 속성으로 평가할 데이터를 좁힐 수 있어요.
필터는 컨트롤에 기여하는 레코드를 결정해요. 거버넌스하고 싶은 정확한 트레이스, 스팬, 스레드, 지표 결과, 어노테이션을 대상으로 필터를 사용해요. 예를 들어 metric data 컨트롤은 특정 지표로 필터링하고, trace 컨트롤은 집계를 계산하기 전에 환경·태그·메타데이터로 필터링할 수 있어요. AND 그룹 내 조건은 모두 일치해야 하고, 레코드가 여러 조건 집합 중 하나와만 일치해도 될 때는 OR 그룹을 사용해요.
데이터 모델과 집계
Trace
Trace 컨트롤은 엔드투엔드 LLM 애플리케이션 요청을 집계해요. 요청 볼륨, 품질, 지연 시간, 비용, 사용자 활동을 거버넌스하는 데 사용해요.
| 집계 | 측정 내용 |
|---|---|
| Trace count | 일치하는 트레이스의 총 수 |
| Error rate | 오류를 포함하는 일치 트레이스의 비율 |
| Pass rate | 평가를 통과하는 일치 트레이스의 비율 |
| Unique end users | 일치 트레이스가 나타내는 고유 최종 사용자 수 |
| Unique threads | 일치 트레이스가 나타내는 고유 스레드 수 |
| Avg latency | 일치 트레이스 전체의 평균 지연 시간 |
| P50 latency | 일치 트레이스 전체의 중앙값 지연 시간 |
| P90 latency | 일치 트레이스 전체의 90번째 백분위 지연 시간 |
| P99 latency | 일치 트레이스 전체의 99번째 백분위 지연 시간 |
| Total cost | 일치 트레이스 전체의 LLM 비용 합계 |
| Avg cost | 일치 트레이스 하나당 평균 LLM 비용 |
| Unique metadata values | 선택한 메타데이터의 고유 값 수 |
Span
Span 컨트롤은 트레이스 안의 개별 작업을 집계해요. 모델 호출, 도구 호출, 검색기(retriever), 또는 다른 계측된 작업의 동작을 격리하는 데 사용해요.
| 집계 | 측정 내용 |
|---|---|
| Span count | 일치 스팬의 총 수 |
| Error rate | 오류를 포함하는 일치 스팬의 비율 |
| Error count | 오류를 포함하는 일치 스팬의 총 수 |
| Avg latency | 일치 스팬 전체의 평균 지연 시간 |
| P50 latency | 일치 스팬 전체의 중앙값 지연 시간 |
| P90 latency | 일치 스팬 전체의 90번째 백분위 지연 시간 |
| P99 latency | 일치 스팬 전체의 99번째 백분위 지연 시간 |
| Total cost | 일치 스팬 전체의 LLM 비용 합계 |
| Input cost | 일치 스팬 전체의 입력 토큰 비용 합계 |
| Output cost | 일치 스팬 전체의 출력 토큰 비용 합계 |
| Avg cost | 일치 스팬 하나당 평균 LLM 비용 |
| Unique metadata values | 선택한 메타데이터의 고유 값 수 |
| Input tokens | 일치 스팬 전체의 총 입력 토큰 사용량 |
| Output tokens | 일치 스팬 전체의 총 출력 토큰 사용량 |
| Total tokens | 일치 스팬 전체의 입력·출력 토큰 총합 |
Thread
Thread 컨트롤은 다중 턴 대화를 집계해요.
| 집계 | 측정 내용 |
|---|---|
| Thread count | 일치 스레드의 총 수 |
| Unique end users | 일치 스레드가 나타내는 고유 최종 사용자 수 |
| Unique metadata values | 선택한 메타데이터의 고유 값 수 |
Metric data
Metric data 컨트롤은 평가 지표 결과를 집계해요. 먼저 지표 데이터 소스 — Trace, Span, Thread, Test run — 를 선택한 다음 집계를 고르면 돼요.
| 집계 | 측정 내용 |
|---|---|
| Metric count | 일치하는 지표 결과의 총 수 |
| Avg score | 일치 지표 결과 전체의 평균 점수 |
| Median score | 일치 지표 결과 전체의 중앙값 점수 |
| Pass rate | 통과하는 일치 지표 결과의 비율 |
| Failure rate | 실패하는 일치 지표 결과의 비율 |
Annotation
Annotation 컨트롤은 데이터에 붙은 인간 피드백을 집계해요.
| 집계 | 측정 내용 |
|---|---|
| Annotation count | 일치 어노테이션의 총 수 |
| Avg rating | 일치 어노테이션 전체의 평균 평점 |
임계값 동작
임계값 방향(direction)은 컨트롤이 실패하는 조건을 나타내요:
| 방향 | 컨트롤은 다음일 때 실패… | 예시 |
|---|---|---|
| Above | 집계 값이 임계값보다 큼 | 오류율이 5%를 초과하면 실패 |
| Below | 집계 값이 임계값보다 작음 | 성공 트레이스 수가 1,000 미만이면 실패 |
집계 값이 요구되는 범위 안에 머물면 컨트롤은 통과해요.
흔히 쓰는 런타임 컨트롤
- 신뢰성(Reliability) — 오류율이 합의된 한도 아래에 머물도록 요구해요.
- 지연 시간(Latency) — 평균 또는 백분위 지연 시간이 SLA 아래에 머물도록 요구해요.
- 비용(Cost) — 토큰 비용이 일일 예산 아래에 머물도록 요구해요.
- 트래픽(Traffic) — 트레이스, 스팬, 스레드, 지표, 어노테이션 볼륨이 최소치 이상을 유지하도록 요구해요.
- 채택(Adoption) — 고유 최종 사용자 수가 목표치 이상을 유지하도록 요구해요.
- 품질(Quality) — 평가 통과율, 지표 점수, 인간 평가가 목표치 이상을 유지하도록 요구해요.
필터를 사용해 하나의 요구사항을 프로덕션 환경, 애플리케이션 버전, 고객 세그먼트, 또는 관련 트래픽의 다른 조각으로 범위를 좁힐 수 있어요.