콘텐츠로 이동

전체 행 인덱스


전체 행 인덱스란 무엇인가

전체 행 인덱스는 로그 전체 텍스트 검색 방식입니다. 활성화하면 시스템이 로그의 모든 비즈니스 필드를 전체 텍스트 인덱스에 포함합니다. 조회 시 필드 이름을 미리 지정할 필요 없이 임의의 비즈니스 필드 값을 입력하면 해당 값이 포함된 로그를 검색할 수 있습니다.

예를 들어, 한 로그에 다음 필드가 포함되어 있습니다.

{
  "service": "order-api",
  "trace_id": "8d4f2a",
  "order_id": "O-1001",
  "amount": 128.5
}

전체 행 인덱스를 활성화한 후 8d4f2a, O-1001 또는 128.5를 직접 검색하면 해당 로그를 찾을 수 있습니다.

전체 행 인덱스는 다음 상황에 적합합니다.

  • 로그가 이미 여러 구조화된 필드로 추출되어 더 이상 하나의 message에 의존하지 않는 경우
  • trace_id, 주문 번호, 사용자 ID 등 다양한 비즈니스 필드에서 빠르게 검색해야 하는 경우
  • 동일한 로그 인덱스에 여러 로그 구조가 포함되어 모든 로그에 대해 통일된 검색 필드를 미리 정할 수 없는 경우
  • 필드 기반 조회 기능을 유지하면서 여러 비즈니스 필드에 걸친 전체 텍스트 검색을 지원하려는 경우

message 전용 인덱스와의 차이점

비교 항목 message 전용 인덱스 전체 행 인덱스
전체 텍스트 검색 범위 message 필드만 message를 포함한 모든 비즈니스 필드
원본 로그 보존 필요 여부 message 보존 필요 필수 아님. 보존 가능하며, 필드 추출 후 삭제 가능
적합한 데이터 일반 텍스트 로그, 비구조화 로그 JSON 로그, Pipeline으로 추출한 구조화된 로그
전체 텍스트 인덱스 필드 message variant

전체 행 인덱스는 전체 텍스트 검색 범위만 변경하며 필드 필터링을 대체하지 않습니다. 추출된 필드는 계속해서 service:order-api와 같은 필드 조건으로 정확한 필터링, 집계 또는 분석을 수행할 수 있습니다.

동작 원리

시스템은 variant를 통해 전체 행 인덱스의 비즈니스 필드를 통합적으로 담당하며, variant에 대해서만 전체 텍스트 인덱스를 생성합니다.

message가 없는 경우:
비즈니스 필드 → variant → 전체 텍스트 인덱스

message가 있는 경우:
message + 기타 비즈니스 필드 → variant → 전체 텍스트 인덱스

구체적인 규칙은 다음과 같습니다.

  • 전체 행 인덱스는 로그의 비즈니스 필드를 포함하며 시스템 필드는 포함하지 않습니다.
  • 로그에 message가 없어도 다른 비즈니스 필드는 전체 텍스트 검색에 참여할 수 있습니다.
  • 로그에 message가 있으면 시스템은 해당 필드를 삭제하지 않고 일반 비즈니스 필드로 variant에 기록합니다.
  • 시스템은 message와 variant에 대해 전체 텍스트 인덱스 두 개를 동시에 만들지 않습니다.
  • 동일한 로그 인덱스에 message가 있는 로그와 없는 로그를 함께 저장할 수 있습니다.

message의 존재 여부는 로그 원본 내용과 DataKit, Pipeline의 실제 처리 결과에 따라 결정됩니다. 전체 행 인덱스를 활성화한다고 해서 반드시 message를 삭제해야 하는 것은 아닙니다.

전체 행 인덱스 사용 또는 전환

새 로그 인덱스를 만들 때 시스템은 기본적으로 전체 행 인덱스를 사용하므로 별도로 활성화할 필요가 없습니다.

기존 인덱스에서 message 필드 내 JSON Path에 대해 쿼리 가속을 구성한 경우, 전환하기 전에 관련 구성을 기록해 두고 전환 후 해당 JSON Path 쿼리 가속을 다시 구성하세요. 구체적인 방법은 JSON Path 내장 필드 쿼리 가속을 참조하세요.

아직 message 전용 인덱스 필드를 사용하는 기존 로그 인덱스는 다음 작업을 수행할 수 있습니다.

  1. 로그 > 인덱스로 이동합니다.
  2. 대상 로그 인덱스를 편집합니다.
  3. 고급 옵션을 펼칩니다.
  4. 전체 텍스트 인덱스 필드에서 전체 행 인덱스를 선택합니다.
  5. 영향 범위를 확인하고 구성을 저장합니다.
주의

message 전용 인덱스에서 전체 행 인덱스로 전환하는 것은 단방향 작업입니다. 저장한 후에는 다시 message 전용 인덱스로 전환할 수 없으므로 작업 전에 관련 쿼리 및 데이터 사용 방식을 확인하세요.

전제 조건

현재 워크스페이스에서 전체 행 인덱스를 지원해야 합니다. 페이지에 이 옵션이 표시되지 않으면 워크스페이스 버전과 관련 기능 권한을 확인하세요.

전체 행 인덱스로 조회

구성 완료 후 로그가 기록되면 로그 > 탐색기로 이동하여 해당 로그 인덱스를 선택합니다.

탐색기는 텍스트 검색, 필드 필터링, 조합 검색, JSON 검색, DQL 쿼리 등을 지원합니다. 전체 검색 문법과 사용 방법은 탐색기 검색을 참조하세요.

전체 텍스트 검색

검색창에 비즈니스 필드 값을 입력하면 필드 이름을 지정하지 않고 모든 비즈니스 필드에서 검색할 수 있습니다.

위의 주문 로그를 예로 들면 다음과 같습니다.

  • O-1001을 입력하면 order_id를 매칭할 수 있습니다.
  • 8d4f2a를 입력하면 trace_id를 매칭할 수 있습니다.
  • order-api를 입력하면 service를 매칭할 수 있습니다.
  • 로그에 message가 보존된 경우 message의 내용도 검색할 수 있습니다.

텍스트 검색은 입력 내용을 토큰화합니다. 완전하고 연속된 내용을 매칭해야 하는 경우 검색 내용을 영문 반각 큰따옴표로 묶으면 됩니다. 자세한 내용은 텍스트 검색을 참조하세요.

필드 필터링

필드 이름을 이미 알고 있다면 필드 조건을 사용해 조회 범위를 좁힐 수 있습니다. 예를 들어:

service:order-api

전체 텍스트 검색은 '내용이 어떤 필드에 있는지 확실하지 않은' 상황에 적합하고, 필드 필터링은 필드 이름을 알고 정확한 필터링이나 집계 분석이 필요한 상황에 적합합니다. 두 가지를 함께 사용할 수 있습니다. 필드 필터링의 전체 문법은 필터링을 참조하세요.

조회 시 유의 사항

  • 전체 행 전체 텍스트 검색은 비즈니스 필드만 매칭하며 시스템 필드는 매칭하지 않습니다.
  • 로그에 message가 없으면 탐색기는 현재 로그의 비즈니스 필드를 조합해 로그 내용을 표시합니다.
  • 시스템 필드는 전체 행 인덱스 로그 내용의 일부로 포함되지 않습니다.
  • 비즈니스 필드가 아직 원본 로그에서 추출되지 않았다면 전체 행 인덱스는 현재 실제로 존재하는 필드만 검색할 수 있습니다. 따라서 JSON 또는 일반 텍스트 로그의 경우 아래 방법으로 필요한 필드를 먼저 추출하세요.

로그 필드 추출

전체 행 인덱스는 로그에 이미 존재하는 비즈니스 필드를 인덱싱하지만 message의 내용을 자동으로 이해하거나 분해하지는 않습니다. 원본 로그가 여전히 하나의 JSON 또는 일반 텍스트로 되어 있다면 DataKit 또는 Pipeline을 통해 내용을 구조화된 필드로 추출할 수 있습니다.

필드 추출이 완료된 후 원본 message를 보존할지 여부는 실제 필요에 따라 결정됩니다.

  • 전체 원문을 확인해야 하거나 기존 사용 방식을 유지해야 하는 경우 message를 보존할 수 있습니다.
  • 충분한 구조화된 필드가 있고 원문을 더 이상 저장할 필요가 없으면 message를 삭제할 수 있습니다.
  • message 보존 여부와 관계없이 추출된 비즈니스 필드는 전체 행 전체 텍스트 인덱스에 참여할 수 있습니다.

DataKit으로 JSON 필드 추출

각 줄이 표준 JSON 객체이며 모든 최상위 필드를 직접 추출하려는 로그에 적합합니다. DataKit 2.9.0 이상 버전에서 json_as_fields를 활성화할 수 있습니다.

활성화하면 DataKit은 문자 디코딩, ANSI 정리, 여러 줄 병합을 수행한 후 JSON 루트 객체의 최상위 속성을 로그 필드로 변환하고 이어서 Pipeline을 실행합니다.

호스트 로그 수집

logging.conf를 편집합니다.

[[inputs.logging]]
  logfiles = ["/var/log/order/*.json"]
  source = "order"
  service = "order-api"
  json_as_fields = true

구성을 저장한 후 DataKit 재시작을 수행합니다.

Kubernetes 컨테이너 로그 수집

Pod Annotation을 통해 지정된 컨테이너에서 JSON 필드 모드를 활성화할 수 있습니다.

metadata:
  annotations:
    datakit/order-api.logs: >-
      [{"source":"order","service":"order-api","json_as_fields":true}]

여기서 order-api는 컨테이너 이름입니다. 컨테이너 환경 변수 DATAKIT_LOGS_CONFIG에서도 동일한 JSON 구성을 사용할 수 있습니다.

컨테이너 구성 제한

json_as_fields는 현재 컨테이너 환경 변수 및 Pod Annotation/Label의 JSON 로그 구성만 지원하며 ClusterLoggingConfig CRD는 아직 지원하지 않습니다.

Log Streaming

logstreaming.conf에서 활성화합니다.

[inputs.logstreaming]
  json_as_fields = true

json_as_fields는 수집기 구성이며 HTTP URL 매개변수가 아닙니다. 이 구성은 influxdb, firelens, firehose 유형에는 적용되지 않습니다.

추출 결과

원본 로그:

{"timestamp":"2026-08-18T10:00:00+08:00","level":"INFO","service":"order-api","trace_id":"8d4f2a","order_id":"O-1001","amount":128.5,"labels":{"channel":"web"}}

변환에 성공하면:

  • timestamp, level, service, trace_id, order_id, amount가 독립 필드가 됩니다.
  • labels 객체는 압축된 JSON 문자열로 저장됩니다.
  • DataKit은 원본 JSON 전체를 저장하는 message를 별도로 생성하지 않습니다.
  • 원본 JSON에 message가 포함된 경우 해당 필드는 정상적으로 유지됩니다.

주요 필드 변환 규칙은 다음과 같습니다.

  • 최상위 문자열, 불리언, 정수, 소수는 타입이 유지됩니다. 객체와 배열은 압축된 JSON 문자열로 저장되고 null은 무시됩니다.
  • 유효하지 않은 JSON이거나, 루트 노드가 객체가 아니거나, 유효한 필드가 없는 경우 원본 message로 폴백됩니다.
  • 필드 이름의 .은 _로 변환되고, 줄바꿈 문자는 공백으로 변환되며, 필드 이름은 최대 256바이트입니다.
  • 각 로그에는 tag를 제외하고 최대 1024개의 field가 유지됩니다.
  • JSON 필드는 수집기의 동일한 이름의 tag 또는 field를 덮어씁니다.
  • JSON의 time, source, date, storage_index는 각각 json_time, json_source, json_date, json_storage_index로 이름이 변경됩니다.

전체 규칙은 JSON 필드 모드를 참조하세요.

Pipeline으로 필드 추출

다음과 같은 경우에 적합합니다.

  • 일부 필드만 추출해야 하는 경우
  • 필드 이름을 변경하거나 변환해야 하는 경우
  • 로그가 표준 JSON이 아닌 경우
  • 기존 Pipeline 처리 프로세스를 계속 사용해야 하는 경우

모든 최상위 스칼라 필드 추출

DataKit 2.2.0 이상 버전에서는 json_all()을 사용할 수 있습니다.

# 원본 데이터:
# {"service":"order-api","status":"info","trace_id":"8d4f2a","order_id":"O-1001","amount":128.5}

json_all(_, key_patterns=["*"])

처리 후 service, status, trace_id, order_id, amount 등 독립 필드가 생성됩니다.

json_all()은 최상위 문자열, 숫자, 불리언만 추출하며 객체나 배열을 재귀적으로 펼치지 않고 null도 저장하지 않습니다. include_keys와 key_patterns가 모두 설정되지 않으면 어떤 필드도 추출되지 않습니다. 모든 최상위 스칼라 필드를 추출하려면 key_patterns=["*"]를 명시적으로 설정해야 합니다.

지정한 필드만 추출

json(_, service)
json(_, level, status)
json(_, trace_id)
json(_, order_id)
json(_, amount)

이 방식으로 전체 행 인덱스에 포함될 필드 범위를 제어할 수 있으며, 서로 다른 로그의 필드를 동일한 이름으로 통일할 수도 있습니다.

객체나 배열은 json_all()로 추출되지 않습니다. 이러한 내용을 유지해야 하는 경우 json()으로 필드를 지정해 추출할 수 있으며, 추출 결과는 JSON 문자열로 저장됩니다.

필드 추출 후 message 삭제

Pipeline으로 필드를 추출할 때 원본 로그는 기본적으로 message에 계속 저장됩니다. 구조화된 필드가 이미 표시 및 조회 요구를 충족한다면 필드 추출 완료 후 drop_origin_data()를 호출해 원본 내용을 더 이상 저장하지 않을 수 있습니다.

json_all(_, key_patterns=["*"])
drop_origin_data()

지정한 필드를 추출한 후 삭제할 수도 있습니다.

json(_, service)
json(_, level, status)
json(_, trace_id)
json(_, order_id)
json(_, amount)
drop_origin_data()

JSON에 message가 포함되어 있고 해당 필드도 추출된 경우 필요에 따라 유지하거나 삭제할 수 있습니다. 명확히 필요하지 않을 때는 다음을 사용합니다.

json_all(_, key_patterns=["*"])
drop_origin_data()
drop_key(message)

세 함수는 역할이 다릅니다.

  • drop_origin_data(): 초기화 시 저장된 원본 텍스트를 더 이상 출력하지 않습니다. 로그 전체는 계속 업로드됩니다.
  • drop_key(message): 이미 추출된 message 필드를 삭제합니다.
  • drop(): 로그 전체를 버립니다. 로그가 업로드되지 않으며 message를 삭제하는 데 사용할 수 없습니다.
drop()으로 message를 삭제하지 마세요

drop()은 현재 로그를 버릴 대상으로 표시합니다. Pipeline 실행이 끝나면 로그 전체가 업로드되지 않습니다.

더 자세한 문법은 json(), json_all(), drop_origin_data() 및 drop_key()를 참조하세요.

로컬에서 Pipeline 검증

Pipeline 스크립트를 저장한 후 DataKit이 설치된 호스트에서 다음을 실행할 수 있습니다.

datakit pipeline -P full_line_json.p \
  -T '{"service":"order-api","status":"info","trace_id":"8d4f2a","order_id":"O-1001","amount":128.5}'

출력이 다음 기대 사항에 부합하는지 확인하세요.

  • 조회해야 하는 필드가 모두 추출되었는지 확인합니다.
  • drop_origin_data()를 구성했다면 원본 message가 삭제되었는지 확인합니다.
  • 로그가 drop: true로 표시되지 않았는지 확인합니다.
  • status와 로그 시간 등의 필드가 비즈니스 기대에 부합하는지 확인합니다.

자주 묻는 질문

전체 행 인덱스는 반드시 message를 삭제해야 하나요?

아닙니다. message가 있으면 시스템은 이를 일반 비즈니스 필드로 variant에 기록하며 message에 대해 별도의 전체 텍스트 인덱스를 만들지 않습니다. message를 삭제할지는 원본 내용 보존 및 표시 요구에 따라 결정하면 됩니다.

전체 행 인덱스를 활성화한 뒤에도 message 안의 JSON 필드가 검색되지 않는 이유는 무엇인가요?

JSON 전체가 여전히 message의 문자열 내용에 불과하면 그 속성은 독립적인 비즈니스 필드가 아닙니다. message의 텍스트를 검색할 수는 있지만 해당 속성을 직접 필드 필터링이나 집계에 사용할 수는 없습니다. DataKit 또는 Pipeline으로 필요한 필드를 먼저 추출하는 것이 좋습니다.

message가 없으면 로그 탐색기는 내용을 어떻게 표시하나요?

로그에 message가 없으면 로그 탐색기는 현재 로그의 비즈니스 필드를 조합해 로그 내용을 표시합니다. 시스템 필드는 로그 내용의 일부로 포함되지 않습니다.

동일한 인덱스에 message가 있는 로그와 없는 로그를 함께 저장할 수 있나요?

가능합니다. 두 유형의 로그 모두 동일한 규칙에 따라 비즈니스 필드를 variant에 기록하며 variant가 전체 텍스트 인덱스에 참여합니다.

전체 행 인덱스로 시스템 필드를 검색할 수 있나요?

검색할 수 없습니다. 전체 행 인덱스는 비즈니스 필드만 포함하며 시스템 필드는 포함하지 않습니다. 시스템 필드는 필드 필터링 등으로 계속 조회할 수 있습니다.

전체 행 인덱스로 전환한 뒤 message 인덱스로 복원할 수 있나요?

복원할 수 없습니다. message 전용 인덱스에서 전체 행 인덱스로 전환하는 것은 단방향 작업이므로 저장 후에는 되돌릴 수 없습니다. 기존 message 인덱스는 전환하지 않으면 기존 방식대로 계속 사용할 수 있습니다.

문서 평가

이 페이지가 도움이 되었나요?