Observability 개요와 공통 설정

tags와 metadata는 비교 축을, score는 품질 결과를 기록합니다. 실행 중 자동 평가는 Runtime Evaluator Framework로 구성하고, 이미 계산한 값은 저수준 record_score()로 기록합니다. 두 방식 모두 같은 trace·observation·score 계약을 사용합니다.

비교 가능한 실행 기록

한 번의 trace보다 중요한 것은 다음 배포에서도 뜻이 달라지지 않는 분류와 점수입니다. 비교 목적에 따라 다음 층을 조합합니다. 첫 번째 층의 evaluationSuite와 evaluationCase는 반복 평가에서만 쓰는 선택 사항입니다.

반복 평가 요청 metadata    (선택) evaluationSuite=contract-v1, evaluationCase=refund-policy
                           "어떤 평가 묶음·케이스인가" → 필요할 때만 비교의 행
        ↓
Trace (서버 공통 설정)     tags=[workflow:contract-approval] metadata={serviceRole, workflowVariant}
                           "어떤 워크플로우, 어떤 구성인가" → 집합 좁히기·비교의 열
        ↓
Observation (직접 계측)    Evaluator contract-check, metadata={stage: validation, policyVariant: contract-v3}
                           "trace 안 어느 단계, 무슨 기술 작업, 어떤 평가 기준인가"
        ↓
Score (직접 기록)          policy_compliance=0.96
                           "품질을 어떤 잣대로 쟀고 결과는 무엇인가"

요청 metadata를 보내면 서버 공통 metadata와 함께 루트 trace에 표시됩니다. 생략해도 추적과 Runtime Evaluator 실행에는 영향을 주지 않습니다. 위 도식은 observe()와 record_score()로 단계를 직접 평가하는 경로입니다. 저장 위치보다 누가 어떤 주기로 값을 정하는지에 초점을 맞췄습니다. 같은 키가 겹치면 안정적인 배포 축을 지키기 위해 서버의 ObservabilityConfig.metadata가 우선합니다.

반복 평가에서는 tag로 실행 집합을 좁힌 뒤 요청 metadata(행) × 구성 metadata(열)로 묶습니다. 일반 호출은 이 행 차원을 생략할 수 있습니다. 어떤 방식이든 score 이름과 policyVariant가 같은 값끼리만 비교하세요. workflowVariant는 피평가 대상의 버전이고 policyVariant는 평가 기준의 버전입니다. 둘 중 하나가 바뀌면 별도 비교 열이나 집합으로 분리해야 이전 점수와 섞이지 않습니다.

Runtime 평가와 직접 기록

Runtime Evaluator는 evaluator를 실행하고 평가 과정과 Numeric score를 함께 기록합니다. 반면 record_score()는 개발자가 넘긴 값을 저장할 뿐, evaluator를 고르거나 실행하지 않습니다. 두 방식은 같은 비교 축을 쓸 수 있지만 책임과 기록 위치가 다릅니다.

방식	평가 과정 기록	score가 붙는 곳	적합한 경우
Runtime Evaluator	SDK가 `evaluation:<evaluator-name>` evaluator observation을 생성	원래 평가 대상	Agent·Orchestrator의 `completed` 출력이나 지정한 Flow 노드 출력을 실행 중 0~1 Numeric으로 평가
`record_score()` (`observe()`는 선택)	필수 아님. 평가 과정을 따로 남길 때만 개발자가 observation을 생성	현재 또는 명시적으로 지정한 trace·observation	단계별·사후 평가, 이미 계산한 값, BOOLEAN·CATEGORICAL·TEXT 기록

Runtime Evaluator에서 원래 평가 대상은 연결 방식에 따라 정해집니다.

Flow 노드에 연결하면 해당 노드 observation
Agent·Orchestrator의 최종 응답에 연결하면 trace
evaluate(..., observation=...)로 대상을 지정하면 해당 observation

evaluation observation의 부모는 실행 시점의 활성 observation입니다. 대상이 열려 있는 Flow 노드에서는 대상의 하위에 생깁니다. 이미 종료된 observation을 명시적으로 평가하면 대상의 자식이 아닐 수 있지만 evaluatedObservationId가 관계를 보존합니다.

Flow 노드 자동 평가 예시

평가 대상 observation  business-validate-document, metadata={stage: validation}
        ├─ 평가 과정    Evaluator evaluation:policy_compliance
        │                metadata={policyVariant: contract-v3, threshold: 0.8}
        └─ score        policy_compliance=0.96  ← 평가 대상 observation에 연결

Runtime Evaluator에서는 evaluator 이름과 Numeric score 이름이 같습니다. stage는 평가 대상 observation에 두며 evaluation observation으로 자동 복사되지 않습니다. SDK는 evaluation observation에 policyVariant, threshold, 평가 대상 ID를 기록하고, score metadata에는 policyVariant, threshold, passStatus를 기록합니다. score는 위에서 정한 원래 대상에 연결됩니다. 자세한 규칙은 Runtime Evaluator Framework를 참고하세요.

문서 구성

하려는 일	문서
공통 태그와 메타데이터 설정	현재 문서
기술 작업과 서비스 역할·업무 단계 구분	Observation 설계
completed 출력을 실행 중 자동 평가	Runtime Evaluator Framework
trace 또는 observation에 평가값 기록	Score 기록
같은 실행·단계끼리 비교	Langfuse 필터와 비교
네트워크 없이 기록 계약 검증	계약 테스트와 운영

필드 선택

ObservabilityConfig.metadata는 서비스 공통 값으로 로컬 하위 observation에 전파됩니다. 단계별 로컬 metadata는 해당 observation에서만 공통 값을 덮어씁니다. 호출자의 요청 metadata가 기록되는 위치까지 포함한 규칙은 하위 observation의 값을 참고하세요.

아래 필드는 모두 선택 사항입니다. 필요한 비교 축만 추가하세요.

질문	필드	예시
어떤 실행 집합인가?	`tags`	`document-review`, `channel:web`, `variant:v3`
반복 평가 결과를 어떤 묶음·케이스로 나눌 것인가?	반복 평가 요청 `metadata.evaluationSuite`, `metadata.evaluationCase`	`contract-v1`, `refund-policy`
배포 서비스의 역할은 무엇인가?	루트 `metadata.serviceRole`	`serviceRole=document-verifier`
어떤 워크플로우 구성인가?	루트 `metadata.workflowVariant`	`workflowVariant=v3`
현재 observation은 어느 업무 단계인가?	로컬 `metadata.stage`	`stage=validation`
어떤 기술 작업인가?	`observation_type`	`agent`, `evaluator`, `guardrail`, `generation`
품질을 어떤 잣대로 쟀고 결과는 무엇인가?	`score`	`decision_accuracy=0.94`

Metadata 키 관례

키	문서에서 쓰는 뜻	권장 범위
`evaluationSuite`	함께 실행한 평가 케이스 묶음	반복 평가 요청의 선택 metadata
`evaluationCase`	반복 비교할 질문·시나리오 식별자	반복 평가 요청의 선택 metadata
`serviceRole`	배포 서비스의 역할	루트 metadata
`workflowVariant`	비교할 워크플로우·구성 버전	루트 metadata
`stage`	현재 observation의 업무 단계	로컬 metadata
`policyVariant`	evaluator의 기준·프롬프트·모델을 식별하는 버전	evaluator observation의 로컬 metadata

evaluationSuite, evaluationCase, serviceRole, workflowVariant, stage는 문서에서 권장하는 선택적 이름이며 SDK 예약어가 아닙니다. 특히 evaluationSuite와 evaluationCase는 일반 호출에 필요하지 않습니다. 생성된 반복 평가 실행기처럼 케이스별 비교가 필요할 때만 요청 metadata에 넣으세요. 개발자는 다른 metadata 키도 자유롭게 추가할 수 있습니다. Runtime Evaluator는 evaluator observation과 score metadata에 policyVariant를 자동으로 기록합니다. 수동 evaluator를 계측할 때도 같은 의미로 로컬 metadata에 지정하세요. 반복 비교에 쓰는 키와 값은 배포가 달라도 같은 뜻을 유지해야 합니다.

channel:web의 콜론도 필수 문법이 아니라 선택적인 key:value 이름 규칙입니다.

모든 프로젝트의 공통 설정

CLI가 생성하는 Agent, Flow, Orchestrator 템플릿에는 같은 함수가 들어갑니다. 값을 비워 두면 기존 실행에 영향을 주지 않습니다.

from llamon_agent.observability import ObservabilityConfig


def build_observability() -> ObservabilityConfig:
    """프로젝트 전체에 적용할 추적 속성을 반환합니다."""
    return ObservabilityConfig(
        # 비교 집합은 짧고 안정적인 이름으로 둡니다.
        tags=["document-review", "workflow:contract-approval"],
        # 서비스 역할과 비교할 구성 버전은 루트 metadata에 기록합니다.
        metadata={"serviceRole": "document-verifier", "workflowVariant": "v3"},
    )

Agent와 Flow는 create_server()에 연결합니다.

app = await create_server(
    card=build_card(settings),
    agent=agent_or_graph,
    settings=settings,
    # 모든 하위 observation에 공통 설정을 적용합니다.
    observability=build_observability(),
)

Orchestrator도 같은 이름과 의미를 사용합니다.

app = await build_orchestrator_app(
    card=build_card(settings),
    run_turn=make_run_turn,
    settings=settings,
    # 모든 하위 observation에 공통 설정을 적용합니다.
    observability=build_observability(),
)

하위 observation의 값

ObservabilityConfig의 tags와 metadata는 서비스 프로세스의 루트 호출에서 시작해 로컬 하위 observation과 event에 전파됩니다. 특정 단계의 로컬 metadata에 같은 키가 있으면 그 observation에서만 공통 값을 덮어씁니다. 호출자가 보낸 요청 metadata는 서비스 invoke observation과 루트 trace의 요청 차원으로 기록합니다.

Langfuse v4에서는 전파된 tags가 각 observation에 적용되고, trace에는 모든 observation의 tag 집합이 모입니다. SDK는 ObservabilityConfig.tags를 로컬 하위 observation에 전파하지만 노드별 tags API는 제공하지 않습니다. 개별 단계는 안정적인 name, type과 로컬 metadata로 구분하세요.

원격 A2A 경계

부모의 tags와 metadata는 원격 자식의 JSON-RPC payload나 baggage로 자동 전달되지 않습니다. 분산 추적에서는 traceparent와 tracestate만 이어집니다. 각 배포 서비스에 자체 build_observability() 기준 설정을 두세요.

Orchestrator와 문서 검증 서비스를 같은 비교 집합으로 묶으려면 두 서비스에 같은 워크플로우 tag를 선언하고 serviceRole은 실제 역할에 맞게 다르게 둡니다.

# 문서 검증 서비스
return ObservabilityConfig(
    tags=["document-review", "workflow:contract-approval"],
    metadata={"serviceRole": "document-verifier", "workflowVariant": "v3"},
)

서비스 역할, 업무 단계와 기술 작업을 나누는 기준은 Observation 설계에서 이어집니다.