전체 인덱스¶

전체 인덱스란?¶

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

예를 들어, 로그에 다음 필드가 포함된 경우를 살펴보겠습니다.

{
  "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를 삭제해야 하는 것은 아닙니다.

전체 인덱스 활성화¶

로그 > 인덱스로 이동합니다.
새 로그 인덱스를 생성하거나 대상 로그 인덱스를 편집합니다.
고급 옵션을 확장합니다.
전체 텍스트 인덱스 필드에서 전체 인덱스를 선택합니다.
구성을 저장합니다.

전제 조건

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

전체 인덱스를 사용한 쿼리¶

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

탐색기는 텍스트 검색, 필드 필터링, 조합 검색, 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바이트입니다.
로그당 최대 1024개의 field(태그 제외)가 보존됩니다.
JSON 필드는 수집기의 동일한 이름의 태그 또는 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가 전체 텍스트 인덱스에 참여합니다.

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

아니요. 전체 인덱스는 비즈니스 필드만 포함하며 시스템 필드는 포함하지 않습니다. 시스템 필드는 필드 필터링 등을 통해 쿼리할 수 있습니다.