용어를 외우는 목적은 UI 메뉴를 찾는 것이 아니라 어느 데이터와 어느 운영 경계를 말하는지 정확히 구분하는 것이다
| 용어 | 뜻 | 함께 구분할 것 |
|---|
| observation | 시작·끝 또는 순간을 가진 application operation 한 개 | trace는 observation 묶음 |
| root observation | 부모 없이 한 trace의 전체 input/output과 duration을 대표 | v4에서 trace-level input/output은 deprecated |
| trace | 같은 trace_id를 공유하는 observation의 논리적 tree | 보통 한 turn 또는 agent run |
| session | 여러 trace를 대화·장기 workflow로 묶는 session_id 그룹 | 끝을 알 수 없는 긴 trace가 아님 |
| span | 일반 duration operation | model call 전용 generation과 구분 |
| generation | 생성 LLM 호출과 model·usage·cost를 담는 observation | agent/tool/retriever와 구분 |
| embedding | embedding model 호출 observation | 일반 retriever 전체와 구분 |
| agent | 다음 행동과 workflow를 결정하는 observation | 실제 model 호출은 child generation |
| tool | 외부 function/API 행동 observation | 결정을 내리는 agent와 구분 |
| retriever | 문서·vector DB·검색에서 context를 가져오는 observation | rerank나 transform span과 구분 |
| event | duration 없는 순간 사건 | 긴 작업을 event 여러 개로 쪼개지 않음 |
| trace-wide attribute | user·session·tag·release처럼 관련 observation에 전파되는 문맥 | root에만 두면 v4 child filter에서 빠질 수 있음 |
| 용어 | 뜻 | 운영 포인트 |
|---|
| instrumentation | application 실행을 observation으로 기록하는 code/integration | 질문에 필요한 tree부터 설계 |
| OpenTelemetry | telemetry API·context·export의 개방 표준 | Langfuse SDK도 OTel 기반 |
| OTLP | OTel data 전송 protocol | Langfuse는 OTLP/HTTP endpoint 제공 |
| context propagation | parent trace/span 문맥을 child·async 작업으로 전달 | 끊기면 여러 trace로 갈라짐 |
| attribute propagation | user/session/metadata를 관련 child observation에 복사 | v4의 direct filter에 필요 |
| batch | 여러 event를 time/size 기준으로 묶어 전송 | HTTP overhead 감소 |
| flush | client queue를 즉시 보내도록 기다림 | short-lived process 종료 경계 |
| producer | SDK/OTel로 trace를 보내는 application | server와 version inventory 분리 |
| ingest | Web API가 event를 받아 durable pipeline에 넣는 구간 | 2xx는 ClickHouse 저장 완료가 아님 |
| data freshness | ingest부터 query visible까지 걸린 시간 | queue·Worker SLO |
| correlation id | app log·Langfuse·LiteLLM·OTel을 잇는 id | secret/API key와 구분 |
| 용어 | 뜻 | 운영 포인트 |
|---|
| prompt version | 저장할 때 생기는 immutable prompt 역사 | 수정 대신 새 version |
| label | 특정 version을 가리키는 움직이는 pointer | production, staging, custom label |
latest | 가장 최근 생성 version을 자동으로 가리키는 label | production 배포 label로 쓰지 않음 |
| compile | template variable과 message placeholder를 runtime 값으로 치환 | variable schema contract |
| prompt link | generation과 사용한 prompt name/version 연결 | version별 score·cost 분석 |
| cache TTL | SDK cache가 prompt를 fresh로 보는 시간 | Pod 사이 짧은 version 공존 |
| stale-while-revalidate | stale prompt를 즉시 쓰면서 background 갱신 | availability와 즉시 반영 tradeoff |
| fallback prompt | cold cache와 Langfuse 장애 때 사용할 code 내 기본값 | drift와 test 필요 |
| 용어 | 뜻 | 운영 포인트 |
|---|
| score | 대상에 붙는 numeric·categorical·boolean·text 평가 결과 | rubric/source/version이 필요 |
| score config | score name·type·범위 같은 일관된 정의 | annotation·dashboard 계약 |
| rubric | score 단계와 boundary example을 설명한 채점 기준 | evaluator version 관리 |
| LLM-as-a-Judge | LLM이 다른 output을 rubric으로 평가 | 사람 calibration·sampling·비용 |
| code evaluator | deterministic code로 schema·rule을 검사 | 가능한 검사는 judge보다 먼저 |
| annotation queue | 사람이 trace·observation·session을 구조적으로 검토 | agreement와 domain ownership |
| online evaluation | production observation을 지속 평가 | drift와 새로운 edge case 발견 |
| offline evaluation | 고정 dataset에서 변경 후보를 평가 | 배포 전 release gate |
| dataset | 반복 평가할 item 모음 | production failure의 회귀 계약 |
| dataset item | input·expected output·metadata를 가진 사례 | provenance와 PII policy |
| task | item 하나에 application variant를 실행하는 함수 | production path와 차이 기록 |
| evaluator | task output을 score로 바꾸는 함수 | 같은 run 비교에서 version 고정 |
| experiment run | task를 dataset 전체에 실행한 output·score 묶음 | baseline/candidate 비교 |
| calibration | 자동 score를 human label과 맞춰 보는 과정 | judge bias·threshold 조정 |
| 용어 | 뜻 | 저장/운영 역할 |
|---|
| Langfuse Web | UI·public ingest·prompt/API를 제공하는 container | northbound traffic |
| Langfuse Worker | queue event를 비동기 처리하는 container | S3 read·mask/enrich·CH insert |
| Postgres | transaction 중심 database | user·project·prompt·dataset·eval config |
| ClickHouse | columnar OLAP database | observation·score와 분석 query |
| Redis/Valkey | memory data store | BullMQ queue와 API key·prompt cache |
| S3 event bucket | raw ingestion event 저장 | Redis에는 reference만 전달 |
| S3 media bucket | image·audio attachment 저장 | 단순 lifecycle delete 주의 |
| queue depth | 기다리는 job 수 | arrival/consume rate와 함께 봄 |
| oldest job age | 가장 오래 기다린 job의 시간 | 실제 freshness 영향 |
| poison event | 반복 실패하는 잘못된 payload/job | retry storm·dead-letter 정책 |
| 용어 | 뜻 | 운영 포인트 |
|---|
| v4 observation-first | operation 행을 직접 query하는 새 data model | trace는 root와 trace_id로 표현 |
events_full | v4의 immutable full-fidelity ClickHouse table | 전체 observation payload |
events_core | table/chart query용 경량 projection | materialized view로 생성 |
events_only | 새 events table만 쓰는 v4 mode | 새 설치와 최종 cutover |
| dual write | old/new table 모두 쓰는 migration mode | rollback safety·storage 증가 |
| historic backfill | old data를 events table로 background 복사 | 약 3배 disk headroom 계획 |
| retention rollover | retention 한 주기 dual write 후 old history를 포기 | backfill 회피 |
| point of commitment | old write를 멈추고 v4-only가 되는 지점 | 이후 v3 rollback은 data gap |
| RPO | 허용 가능한 data loss 시간 | 저장소마다 다를 수 있음 |
| RTO | 복구 목표 시간 | Web뿐 아니라 query와 prompt 포함 |
| 용어 | 뜻 | 운영 포인트 |
|---|
| project public/secret key | SDK/API를 project에 인증하는 Basic Auth pair | browser 노출 금지·rotation |
| client-side masking | network 전 app에서 민감정보 제거 | 가장 강한 data boundary |
| server-side masking | Worker callback으로 중앙 masking | self-hosted EE·raw S3 순서 주의 |
| fail-open | masking callback 실패에도 원문 처리 | availability 우선, privacy 위험 |
| fail-closed | masking 실패 event를 drop | privacy 우선, observability loss |
SALT | API key hash에 쓰는 secret | DB와 함께 복구 |
NEXTAUTH_SECRET | console JWT 보호 secret | session/auth 복구 |
ENCRYPTION_KEY | 저장 LLM/integration credential 암호화 key | backup 없으면 복호화 불가 |
| public trace | membership 없이 URL로 보는 의도적 공개 | production 기본 금지·검토 |
14. 마무리Observation부터 production 개선 loop와 self-hosting 복구까지 한 장의 checklist로 묶는다.