필터 검색 바

필터 검색 바 (Filter search bar)

level:ERROR type:TOOL environment:production latency:>2 name:*checkout*

필터 검색 바는 사이드바에서 필터를 조합하는 대신 한 줄의 텍스트를 입력해 Observations·Traces 테이블을 필터링·검색할 수 있게 해줘요. 쿼리를 사이드바가 만드는 것과 같은 필터로 파싱하고, 타이핑하며 필드와 값을 자동완성하며, 전체 쿼리를 URL로 직렬화해 정확한 뷰를 링크로 공유할 수 있게 해줘요.

출처: 문서

본문

level:ERROR type:TOOL environment:production latency:>2 name:*checkout*

필터 검색 바는 Langfuse v4 데이터 모델에서 실행돼요. Langfuse Cloud에서는 Langfuse v4 preview를 켜야 사용할 수 있고, 셀프호스팅 배포에서는 Langfuse v4로 업그레이드한 후 사용할 수 있어요.

바는 기존 필터 사이드바와 시간 범위 선택기 옆에서 실행돼요. 바와 사이드바는 같은 필터 상태에 대한 두 편집기이므로, 타이핑한 것은 사이드바 필터로 나타나고 그 반대도 마찬가지예요. 필드 이름을 타입하면 자동완성이 연산자와 관찰된 값을 제안하고, Enter를 누르면 적용돼요.

테이블을 원하는 행들로 좁힌 뒤에는 페이지를 떠나지 않고 그 쿼리를 차트로 만들 수 있고, 테이블 위의 Pulse 스트립이 같은 필터링된 쿼리를 시간 경과에 따른 이상치로 그려줘요.

쿼리 문법 (Query syntax)

쿼리는 field:value 필터의 목록이며 암시적 AND로 결합돼요.

필드와 값 (Fields and values)

level:ERROR, environment:production, user:alice. 필드 이름을 타입하면 바가 그 필드에서 관찰한 값을 제안하므로 암기할 필요가 없어요.

연산자 (Operators)

latency:>2, cost:>=0.01, startTime:>2026-06-01 — >, >=, <, <=는 숫자·날짜시간 필드에서 동작해요.

와일드카드와 정확 일치 (Wildcards and exact match)

텍스트 필드에서 *를 와일드카드로 사용해요:

name:*checkout* — 포함
name:checkout* — 시작
name:*checkout — 끝
name:checkout — 느슨한 용어, 기본은 포함
name:=checkout — 정확 일치

부정 (Negation)

필터에 -를 접두사로 붙여 제외해요: -environment:production.

Any-of와 all-of (Any-of and all-of)

level:(ERROR OR WARNING) — 한 필드의 두 값 중 하나와 일치
tags:(billing AND urgent) — 모든 값과 일치 (배열 필드)

메타데이터와 점수 (Metadata and scores)

중첩 필드에 dot 경로 사용:

metadata.region:eu
scores.accuracy:>0.8
scores.is_hallucination:false
scores.helpfulness:positive

scores.*는 레벨과 무관하게 이름으로 score와 일치하므로, 단일 네임스페이스가 observation·trace·session·experiment 레벨 점수를 모두 다뤄요. 점수 필터는 숫자, 범주형, 불리언 값을 지원해요.

공백이나 특수 문자가 있는 키는 접두사 뒤에 따옴표를 붙이세요: scores."Answer Relevance":>=0.9, metadata."my key":eu.

널 검사 (Null checks)

has:endTime는 필드가 설정된 행과, -has:endTime은 null인 행과 일치해요.

전체 텍스트 검색 (Full-text search)

refund failed

느슨한 단어나 구는 id, name, input, output을 가로질러 검색해요.

input: 또는 output:으로 단일 페이로드로 범위를 좁혀요 (예: output:"refund failed"). 일치는 대소문자 무시·단어 기반이에요: 용어는 전체 단어와 일치해요 — error는 error와 일치하지만 errors와는 일치하지 않아요 — 그리고 다중 단어 용어는 연속 구로 일치해요. 바는 Full-Text Search에 문서화된 것과 같은 v4 ClickHouse 전체 텍스트 검색으로 검색해요.

필드 별칭 (Field aliases)

Alias	Field
env	environment
user	user id
session	session id
model	model name
prompt	prompt name
cost	total cost
tokens	total tokens
tags	trace tags
status	status message
ttf	time to first token
tps	tokens per second
dataset	experiment dataset
experiment	experiment name

대부분의 필드는 짧은 별칭을 허용해 덜 타이핑할 수 있어요. 정식 필드 이름도 항상 동작해요.

Ask AI

프로젝트의 필드 이름을 아직 모른다면 Ask AI를 클릭해 원하는 필터를 평범한 언어로 설명하면, 바가 편집 가능한 알약(editable pills)으로 쿼리를 만들어줘요.

Ask AI는 베타이며 기본적으로 꺼져 있고, 조직 소유자나 관리자가 활성화할 때까지 비활성화돼요. 셀프호스팅 배포에서는 Assistant와 같은 인스턴스 Langfuse AI 모델을 사용해요.

Ask AI는 프로젝트 인식형이에요: 요청이 테이블에 이미 로드된 열·값·메타데이터 키의 컴팩트한 클라이언트 측 스냅샷을 담아, 자연어가 일반적인 추측이 아니라 프로젝트의 실제 스키마에 매핑돼요. 예를 들어 "enterprise customers in the membership-support queue"는 trace가 쓰는 실제 metadata.* 키로 해석돼요.

바 옆에 항상 사용 가능한 버튼이에요.
빈 바에서는 처음부터 쿼리를 만들고, 기존 필터가 있으면 요청에 따라 필터를 다듬어요 (추가·변경·제거).
문법이 지원하는 필터만 만들 수 있고, 발명한 열은 쿼리가 적용되기 전에 버려져요.
결과는 사이드바와 같은 경로로 적용되므로 무손실이고 브라우저 뒤로가기 버튼으로 되돌릴 수 있어요.

전체 쿼리가 URL로 직렬화되므로, 링크를 보내면 정확한 필터링된 뷰를 재현해요. 바가 사이드바와 같은 필터 표현으로 컴파일하므로 기존 Saved Views는 변경 없이 계속 동작해요.

예약 토큰 (Reserved tokens)

일부 연산자형 토큰은 아직 지원되지 않으며 텍스트로 취급되는 대신 플래그가 표시돼요: !, 그리고 소문자 단어 and, or, not. 제외는 -field:value, 여러 값 일치는 field:(A OR B)를 사용하세요. 예약어를 리터럴 텍스트로 검색하려면 따옴표를 붙이세요 ("or").

불완전한 필터 (Incomplete filters)

값이 없는 느슨한 필드 이름(예: type, level, env 단독)은 아직 완전한 표현이 아니에요. 바는 그것을 유효하지 않은 것으로 표시하고 완성하기 전까지 쿼리에 적용하지 않아요 (예: type:TOOL). 이런 단어를 리터럴 텍스트로 검색하려면 따옴표로 감싸세요 ("type").

필터 사이드바는 각 패싯 값 옆에 카운트를 보여줘요. 그 카운트는 선택한 시간 범위뿐 아니라 이미 활성화된 필터에 대해 계산되므로, 테이블이 실제로 반환하는 것과 일치해요. environment:production으로 좁히면 Level 패싯이 프로덕션 내에서 다시 카운트되어, 거기서 고르는 값은 결과가 없는 채로 돌아오지 않아요.

GitHub Discussions

더 알아보기 (Learn more)

출처 문서: 필터 검색 바 (Filter search bar)

필터 검색 바