LLM observability
AI Agent용 안내: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/llm-observability/index.md, 전체 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.
Ankole은 OpenTelemetry Protocol(OTLP) HTTP/protobuf 형식으로 OpenTelemetry 트레이스를 내보낼 수 있으며, 기본 상태는 비활성화되어 있습니다. observability.traces.provider 설정은 Turn 루트 span과 AIGateway LLM span에 어떤 벤더 전용 속성을 덧붙일지 결정합니다. 이는 AIGateway 모델 Provider나 전송 계층 설정이 아니며, 다른 OpenTelemetry span을 필터링하지도 않습니다. 값에 따라 langfuse는 Langfuse v4 에이전트 및 생성(generation) 속성을, langsmith는 LangSmith 호환 속성을, opentelemetry는 범용 OpenTelemetry·gen_ai.*·Ankole 속성을 기록합니다.
트레이스 내보내기를 켜면 모델 입력과 출력은 물론 도구 인수와 실행 결과까지 함께 전송될 수 있습니다. 이때 Ankole은 자격 증명, 요청 헤더, 일반 호출자 메타데이터, 암호화된 추론·도구 필드, 내부 __ankole_* 필드를 제거하며, 인라인 data: 미디어는 바이트 수로 치환하고 1 MiB를 넘는 입출력 페이로드는 생략합니다. 그렇더라도 수신 시스템(receiver)은 적절한 접근 제어와 보관 정책을 갖춘 신뢰할 수 있는 환경이어야 합니다.
디스패치된 각 Agent Turn은 하나의 트레이스로 기록됩니다. 루트 span인 turn <event-type>은 Langfuse에서 에이전트 observation으로 표시되며, 민감 정보가 제거된 트리거 이벤트와 최종 응답을 담습니다. Main Agent의 도구 span과 AIGateway 응답 span은 이 루트 span의 하위에 연결되고, Background Job에서는 codex.turn과 Codex 도구 span도 함께 포함됩니다. 반면 Turn 컨텍스트 없이 직접 호출한 AIGateway 요청은 ai_gateway.response를 루트 span으로 사용합니다. 또한 Agent Computer는 인증된 Runtime Fabric RPC 경로를 통해 protobuf OTLP 배치를 전달하므로, 수신 시스템의 자격 증명은 항상 control plane 내부에만 머뭅니다.
Langfuse 구성
아래 절차는 Langfuse OpenTelemetry guide와 Langfuse v4 migration checklist를 기준으로 합니다.
-
Langfuse 프로젝트의 Settings → API Keys에서 Public Key(
pk-lf-...)와 Secret Key(sk-lf-...)를 발급받습니다. -
Console → AppConfigure → LLM observability를 열고 Trace Provider에서 Langfuse를 선택합니다.
-
리전에 맞는 기본 엔드포인트를 입력합니다. EU는
https://cloud.langfuse.com/api/public/otel, US는https://us.cloud.langfuse.com/api/public/otel, Japan은https://jp.cloud.langfuse.com/api/public/otel, HIPAA는https://hipaa.cloud.langfuse.com/api/public/otel이며, 자체 호스팅(Self-hosted) Langfuse 3.22.0 이상은https://<langfuse-host>/api/public/otel을 사용합니다. -
다음 명령으로 줄바꿈 없는 Basic Auth 인코딩 문자열을 생성합니다.
printf '%s' 'pk-lf-...:sk-lf-...' | base64 | tr -d '\n' -
인증 헤더 행을 두 개 추가합니다. 첫 번째 행에는 이름
Authorization과 값Basic <base64-value>를 입력하고, 두 번째 행에는 이름x-langfuse-ingestion-version과 값4를 입력합니다. -
Trace export를 켜고 설정을 저장한 뒤 control plane을 다시 시작합니다.
-
일반 Agent 메시지를 하나 보내거나 Background Job을 하나 실행해 동작을 확인합니다. Langfuse에
turn <event-type>에이전트 루트 observation이 나타나며, Main Agent 트레이스 아래에는tool <name>과ai_gateway.response하위 항목이, 각 응답 아래에는chat <model>generation이 기록됩니다. Background Job에는codex.turn과 Codex 도구 span도 함께 표시됩니다. 직접 호출한 AIGateway 요청은ai_gateway.response루트로 기록되며, Provider의 네이티브 압축(compaction) 호출은 독립된compact <model>generation으로 표시됩니다.
엔드포인트 주소 끝에 /v1/traces를 직접 붙이지 마십시오. Ankole이 자동으로 /v1/traces 경로를 붙여 application/x-protobuf 형식으로 전송합니다(Langfuse의 해당 엔드포인트는 OTLP/gRPC를 받지 않습니다). x-langfuse-ingestion-version: 4 헤더를 지정하면 v4 실시간 수집 경로가 적용되며, 입력한 헤더 값은 PostgreSQL에 암호화되어 저장됩니다.
Langfuse는 트리거 주체를 기준으로 트레이스를 묶어 보여주며, Ankole은 다음 규칙에 따라 user.id를 기록합니다.
- 신뢰된 사용자(human)가 보낸 다이렉트 메시지 Turn에는
principal:<principal_uid>를 기록합니다. - 그룹 Turn이나 원본 Conversation이 있는 이벤트 Turn에는
channel:<conversation_uuid>를 기록합니다. - 원본 Conversation이 없더라도 신뢰된 사용자 트리거가 있는 Turn에는
principal:<principal_uid>를 기록합니다. - 신뢰된 사용자와 원본 Conversation이 모두 없는 Turn에서는
user.id를 생략합니다.
Turn 바깥에서 직접 호출한 AIGateway 요청에는 principal:<authenticated_subject_uid>가 사용됩니다. 실행 주체인 Agent 정보는 ankole.principal.uid, ankole.principal.type 및 필터링 가능한 트레이스 메타데이터에 기록되며, Langfuse의 세션 단위는 Main Agent 대화 또는 Background Job의 Codex 세션에 해당하는 conversation으로 매핑됩니다.
여기서 channel: 접두사는 관측 전송 계약의 일부이며, 뒤따르는 값은 외부 채팅 플랫폼의 채널 ID가 아니라 Ankole의 공개 Conversation UUID입니다.
선택 사항으로 control plane에 ANKOLE_ENV와 ANKOLE_VERSION을 설정하면, 각 트레이스에 Langfuse 환경 이름(소문자 영숫자와 -, _ 조합, 최대 40자)과 릴리스 버전이 함께 태깅됩니다.
LangSmith 구성
아래 절차는 LangSmith OpenTelemetry guide와 LangSmith announcement를 기준으로 합니다.
- Console → AppConfigure → LLM observability를 열고 Trace Provider에서 LangSmith를 선택합니다.
- 리전에 맞는 기본 엔드포인트를 입력합니다. GCP US는
https://api.smith.langchain.com/otel, GCP EU는https://eu.api.smith.langchain.com/otel, GCP APAC는https://apac.api.smith.langchain.com/otel, AWS US는https://aws.api.smith.langchain.com/otel이며, 자체 호스팅 환경은https://<langsmith-api-host>/api/v1/otel을 사용합니다. x-api-key를 추가합니다. Agent-based workspace에서는 등록된 Agent의Langsmith-Agent-Id와Langsmith-Agent-Environment(local,development,staging,production중 하나)를 모두 설정합니다. Project-based workspace(자체 호스팅 포함)는 두 헤더 대신Langsmith-Project: <project-name>을 사용합니다. 두 방식의 헤더를 함께 보내면 안 됩니다.- Trace export를 켜고 설정을 저장한 뒤 control plane을 다시 시작합니다.
AIGateway Response가 특정 conversation에 속해 있으면, langsmith 프로바이더는 해당 conversation ID를 LangSmith 공식 속성인 langsmith.trace.session_id에 기록하는 동시에 session.id와 gen_ai.conversation.id에도 함께 남깁니다.
다른 OTLP/HTTP receiver
아래 수신 시스템에는 observability.traces.provider=opentelemetry를 사용하십시오. 기본 엔드포인트 끝에 /v1/traces를 붙이지 마시고, 입력 폼에서는 표의 Headers 열에 적힌 항목을 각각 인증 헤더 행으로 추가하십시오.
| Receiver | Endpoint | Headers |
|---|---|---|
| OpenTelemetry Collector | http://<collector-host>:4318 |
별도 인증이 필요 없으면 {} |
| VictoriaTraces single-node | http://<victoria-traces>:10428/insert/opentelemetry |
신뢰할 수 있는 내부망이고 인증 프록시가 없으면 {} |
| VictoriaTraces cluster | http://<vtinsert>:10481/insert/opentelemetry |
신뢰할 수 있는 내부망이고 인증 프록시가 없으면 {} |
| Honeycomb US / EU | https://api.honeycomb.io / https://api.eu1.honeycomb.io |
{"x-honeycomb-team":"<api-key>"} |
| Grafana Cloud | 스택의 OpenTelemetry 연결 타일에서 기본 엔드포인트 복사 | {"Authorization":"Basic <base64(instance-id:access-policy-token)>"} |
VictoriaTraces에 최종 전송되는 경로는 /insert/opentelemetry/v1/traces가 됩니다. VictoriaTraces 자체에는 테넌트 인가 기능이 없으므로, 신뢰할 수 없는 네트워크 구간에서는 vmauth 같은 인증 프록시를 앞단에 두십시오. 자세한 내용은 VictoriaTraces OTLP documentation을 참조하십시오.
Honeycomb Classic 환경에서는 x-honeycomb-dataset 헤더도 필요합니다. Grafana Cloud 토큰에는 traces:write 권한이 필요합니다. 자세한 설정 방법은 Honeycomb OTLP documentation과 Grafana Cloud OTLP documentation을 확인하십시오. Trace Provider 선택에 따른 벤더 속성 보강은 Turn 루트 span과 AIGateway LLM span에만 적용되며, Worker 도구 span과 그 밖의 control plane span은 벤더 중립적인 속성 그대로 동일한 수신 시스템에 함께 전송됩니다.
트레이스 설정은 control plane이 시작될 때 한 번만 읽어들입니다. 내보내기는 best effort이며 실패해도 Agent Turn이나 AIGateway 응답에 영향을 주지 않습니다. 실패한 배치를 영속 outbox에 저장해 재전송하지는 않습니다. 내보내기를 끄려면 observability.traces.enabled를 false로 바꾼 뒤 control plane을 재시작하십시오. 이때 OTEL_TRACES_EXPORTER나 OTEL_EXPORTER_OTLP_* 환경 변수로 Ankole을 설정하지 마십시오. Ankole은 OpenTelemetry가 기동되기 전, 그리고 AppConfigure의 엔드포인트와 헤더를 적용하기 전에 해당 환경 변수들을 모두 제거하며 오직 AppConfigure 설정으로만 exporter를 관리합니다.