For the complete documentation index, see llms.txt. This page is also available as Markdown.

로그 스키마 참조

이 가이드에서는 온보딩 시 YAML 기반 스키마를 구축할 때 사용되는 일반적인 필드를 확인할 수 있습니다 사용자 지정 로그 유형조회 테이블 스키마.

이 페이지 전체에서 필수 필드는 굵게 표시됩니다.

LogSchema 필드

각 로그 스키마에는 다음 필드가 포함됩니다:

  • 필드 ([]FieldSchema)

    • 각 항목의 필드 로그 이벤트.

  • 파서 (ParserSpec)

    • 비 JSON 로그를 JSON으로 변환하거나 사용자 지정 변환을 수행할 수 있는 파서

CI/CD 스키마 필드

또한 CI/CD 워크플로를 사용해 정의된 스키마에는 다음 필드가 포함될 수 있습니다:

  • 스키마 (문자열)

    • 스키마의 이름

  • 설명 (문자열)

    • UI에 표시될 짧은 설명

  • 참조 URL (문자열)

    • 로그 구조를 지정하는 외부 문서로 연결되는 링크입니다. 보통 타사의 문서 링크입니다.

  • fieldDiscoveryEnabled (불리언)

    • 다음 여부를 나타냅니다 필드 검색 이 스키마에 대해 활성화될지 여부를 나타냅니다.

CI/CD 파이프라인을 통해 스키마를 관리하는 방법에 대한 정보는 사용자 지정 로그 페이지를 참조하세요 Panther Analysis Tool(PAT)을 사용하여.

예시

아래 예제에는 위에서 언급한 CI/CD 필드가 포함되어 있습니다.

ParserSpec

ParserSpec는 비 JSON 입력을 JSON으로 변환하는 데 사용할 파서를 지정합니다. 다음 필드 중 하나만 지정할 수 있습니다:

  • fastmatch (FastmatchParser{}): 사용 fastmatch 파서

  • regex (RegexParser{}): 사용 regex 파서

  • csv (CSVParser{}): 사용 csv 파서

    • 참고: columns 필드는 동일한 로그 소스에 여러 CSV 스키마가 있을 때 필요합니다.

    • 다음에서 자세히 알아보세요 CSV 로그 파서.

  • script: 사용 script 파서

아래 탭에서 fastmatch, regex, 그리고 csv 의 필드를 확인하세요.

파서 fastmatch 필드

  • match ([]string): 로그 라인과 일치시킬 하나 이상의 패턴입니다. 이 필드는 비워둘 수 없습니다.

  • emptyValues ([]string): null.

  • expandFields (map[string]string): 텍스트 템플릿 확장을 통해 주입될 추가 필드입니다.

  • trimSpace (bool): 각 값 주변의 공백을 제거합니다.

FieldSchema

하나의 FieldSchema 필드와 그 값을 정의합니다. 필드는 다음과 같이 정의됩니다:

  • 이름 (문자열)

    • 필드의 이름입니다.

  • 필수 (불리언)

    • 필드가 필수인지 여부입니다.

  • 설명 (문자열)

    • 필드를 설명하는 일부 텍스트입니다.

  • 복사 (객체)

    • 존재하는 경우 필드의 값은 참조된 객체.

  • 이름 변경 (객체)

    • 존재하는 경우 필드의 이름이 변경됩니다.

  • 연결 (객체)

    • 존재하는 경우 필드의 값은 다른 두 개 이상의 필드 값이 결합된 값이 됩니다.

  • 분할 (객체)

    • 존재하는 경우 필드의 값은 구분 기호를 기준으로 나누어 다른 문자열 필드에서 추출됩니다.

  • 마스킹 (객체)

    • 존재하는 경우 필드의 값은 마스킹됩니다.

그 값은 다음의 필드를 사용하여 정의됩니다. ValueSchema.

ValueSchema

하나의 ValueSchema 값과 그 처리 방법을 정의합니다. 각 ValueSchema 에는 type 필드가 있으며 다음 값 중 하나가 될 수 있습니다:

유형 값

설명

문자열

문자열 값

int

범위 내의 32비트 정수 -2147483648, 2147483647

smallint

범위 내의 16비트 정수 -32768, 32767

bigint

범위 내의 64비트 정수 -9223372036854775808, 9223372036854775807

float

64비트 부동소수점 수

불리언

불리언 값 true / false

timestamp

타임스탬프 값

array

각 요소가 같은 유형인 JSON 배열

객체

다음의 JSON 객체 알려진

json

유효한 모든 JSON 값(JSON 객체, 배열, 숫자, 문자열, 불리언)

하나의 ValueSchema 은 다음의 값에 따라 달라집니다. type.

Type

필드

Value

설명

객체

필드 (필수)

다음의 배열 FieldSpec 객체로서 객체의 필드를 설명합니다.

array

요소 (필수)

하나의 ValueSchema 배열의 요소를 설명합니다.

timestamp

timeFormats (필수)

[]String

타임스탬프를 파싱할 때 사용할 형식을 지정하는 배열입니다(참조 타임스탬프)

timestamp

isEventTime

Boolean

Panther가 이 타임스탬프를 로그 이벤트 타임스탬프.

문자열

지표

[]String

Panther가 이 값에서 지표를 추출하도록 지시합니다(참조 지표)

문자열

검증

참고 검증

문자열 값에 대한 검증 규칙

타임스탬프

타임스탬프는 type 필드를 timestamp 로 설정하고 timeFormats 필드에.

Panther는 항상 timestamp 값을 협정 세계시(UTC)로 저장합니다. 이는 다음을 의미합니다:

  • 다음의 timestamp 필드 값이 UTC가 아닌 다른 시간대를 나타내는 경우( UTC 오프셋이 있는 경우) Panther가 이를 UTC로 변환합니다.

    • 예를 들어 들어오는 timestamp 필드에 다음 값이 있었다면 2025-07-02T00:15:30-08:00 (여기서 -08:00 오프셋은 태평양 표준시[PST]를 의미합니다) Panther는 이를 2025-07-02 08:15:30.000000000 로 저장합니다

  • 다음의 timestamp (UTC로 변환됨).

허용되는 timeFormats 값은 아래를 참조하세요:

timeFormats 값
예시
설명

rfc3339

2022-04-04T17:09:17Z

가장 일반적인 타임스탬프 형식입니다.

unix_auto

1649097448 (초) 1649097491531 (밀리초) 1649097442000000 (마이크로초) 1649097442000000000 (나노초)

UNIX epoch 시각 이후 경과한 시간으로 표현된 타임스탬프입니다. 초, 밀리초, 마이크로초, 나노초를 처리할 수 있습니다.

unix

1649097448

UNIX epoch 시각 이후 초 단위로 표현된 타임스탬프입니다. 소수점 이하 초를 처리할 수 있습니다.

unix_ms

1649097491531

UNIX epoch 시각 이후 밀리초 단위로 표현된 타임스탬프입니다.

unix_us

1649097442000000

UNIX epoch 시각 이후 마이크로초 단위로 표현된 타임스탬프입니다.

unix_ns

1649097442000000000

UNIX epoch 시각 이후 나노초 단위로 표현된 타임스탬프입니다. 과학적 표기법의 부동소수점도 지원됩니다.

사용자 지정 형식 정의

다음을 사용하여 사용자 지정 형식을 정의할 수도 있습니다. strftime 표기법을 사용합니다. 예:

Panther의 strftime 형식은 %N 코드를 사용하여 나노초를 파싱하는 것을 지원합니다. 예:

%H:%M:%S.%N 를 파싱하는 데 사용할 수 있습니다 11:12:13.123456789

여러 시간 형식 사용

여러 시간 형식이 정의되면 성공적으로 파싱될 때까지 각 형식이 순차적으로 시도됩니다:

타임스탬프 값은 isEventTime: true 로 표시하여 Panther가 이 타임스탬프를 p_event_time 필드로 사용하도록 지시할 수 있습니다. isEventTime 여러 필드에 p_event_time 를 설정할 수 있습니다. 이는 이벤트 시간 정보가 들어 있는 선택적 필드 또는 상호 배타적인 필드가 로그에 있을 때 유용합니다. 모든 로그 이벤트에는 하나의

와 함께 작업하기 timeFormats 스키마 테스트에서

다음과 함께 실행할 스키마 테스트를 작성할 때 pantherlog test 명령:

  • 스키마 필드에 단일 timeFormats 값이 있으면, 이전 버전과의 호환성을 위해 구성은 동일한 형식을 유지합니다.

  • 스키마 필드에 여러 timeFormats 값이 있으면 타임스탬프 필드 값을 결과 페이로드 형식으로 정의해야 합니다 YYYY-MM-DD HH:MM:SS.fffffffff.

단일 timeFormats 값의 예:

여러 timeFormats 값의 예:

지표

다음의 값 문자열 유형은 "지표"로 사용할 수 있습니다. 필드를 지표로 표시하려면 지표 필드를 지표 스캐너 이름의 배열로 설정하세요(하나 이상 사용할 수 있음). 그러면 Panther가 이 필드의 값을 관련된 p_any_ 필드에.

다음에 사용할 수 있는 유효한 값 목록은 지표 필드를 참조하세요 표준 필드.

예를 들면:

검증

아래의 검증 키에서 들어오는 로그가 이 스키마와 일치하려면 충족해야 하는 필드 값 조건을 지정할 수 있습니다.

다음을 사용하는 것도 가능합니다. 검증요소 키에서(여기서 type: string) 배열 값의 각 요소에 대해 검증을 수행할 수 있습니다.

허용거부 검증

허용 목록 또는 거부 목록을 선언하여 문자열 유형의 값을 검증할 수 있습니다. 필드 값이 허용/거부 의 값과 일치하거나 일치하지 않는 로그만 이 스키마로 파싱됩니다. 즉, 공통의 겹치는 필드를 가지지만 해당 필드 값은 다른 여러 로그 유형을 둘 수 있습니다.

allowContainsdenyContains 검증

다음을 사용하여 문자열 값이 특정 하위 문자열을 포함하거나 포함하지 않는지 검증할 수 있습니다. allowContainsdenyContains이는 정확한 값이 아니라 부분 문자열 내용을 기준으로 로그 유형을 일치시켜야 할 때 유용합니다.

ipcidr 형식 검증

다음의 값 문자열 type은 잘 알려진 형식과 일치하도록 제한할 수 있습니다. 현재 Panther는 ipcidr 형식을 지원하여 문자열 값이 유효한 IP 주소 또는 CIDR 범위가 되도록 요구합니다.

ipcidr 검증은 허용, 거부, allowContains, 또는 denyContains 규칙과 결합할 수 있지만, 그렇게 하면 다소 중복됩니다. 예를 들어 두 개의 IP 주소를 허용하는 경우 ip 검증을 추가하면 목록의 IP 주소가 유효하지 않은 경우 검증에 거짓 양성이 포함되지 않도록 할 수 있을 뿐입니다.

IDE에서 JSON Schema 사용하기

코드 편집기 또는 통합 개발 환경(IDE)이 JSON Schema를 지원한다면, 이를 이 스키마 파일 을 Panther 스키마에, 그리고 이 schema-tests 파일 을 스키마 테스트에 사용하도록 설정할 수 있습니다. 이렇게 하면 Panther 스키마와 테스트를 개발하는 동안 제안과 오류 메시지를 받을 수 있습니다.

JetBrains 사용자 지정 JSON Schema

다음을 참조하세요 JetBrains 문서 에서 JetBrains IDE가 사용자 지정 JSON Schema를 사용하도록 설정하는 방법을 확인하세요.

VSCode 사용자 지정 JSON Schema

다음을 참조하세요 VSCode 문서 에서 VSCode가 JSON Schema를 사용하도록 설정하는 방법을 확인하세요.

스트림 유형

Panther Console에서 다음과 같은 특정 작업을 수행할 때 데이터 전송을 위해 S3 버킷 구성 또는 원시 로그에서 사용자 지정 스키마 추론과 같은 작업을 수행할 때 로그 스트림 유형을 선택해야 합니다.

아래에서 각 유형에 대한 예시 로그 이벤트를 확인하세요.

스트림 유형
설명
예시 로그 이벤트

자동

Panther가 적절한 스트림 유형을 자동으로 감지합니다.

해당 없음

이벤트는 개행 문자로 구분됩니다.

JSON

이벤트는 JSON 형식입니다.

JSON 배열

이벤트는 JSON 객체 배열 안에 있습니다.

또는 이벤트는 최상위 객체의 키에 대한 값인 JSON 객체 배열 안에 있습니다. 이를 "enveloped array"라고 부를 수 있습니다.

CloudWatch Logs

이벤트는 CloudWatch Logs에서 왔습니다.

XML

이벤트는 XML 형식입니다. 이벤트는 최상위에 위치하거나 루트 요소 안에 포함됩니다. XML이 XML 스트림 유형.

JSON 배열 스트림 유형

JSON 배열 스트림 유형을 사용하면 이벤트 배열이 "enveloped array"인지, 즉 이벤트 필드의 값인지 여부를 지정할 수 있습니다.

CloudWatch Logs 스트림 유형

CloudWatch Logs 스트림 유형에서는 선택적으로 envelope 필드 보존 을 활성화하여 owner, logGroup, 그리고 logStream) p_header 필드와 같은 최상위 envelope 메타데이터를 각 처리된 이벤트에 보존할 수 있습니다.

CloudWatch Logs 구독은 다음과 같은 envelope로 이벤트를 전달합니다.

envelope 필드 보존이 활성화되면 각 처리된 이벤트의 p_header 필드에 envelope 메타데이터가 포함됩니다:

참고 Envelope field retention 이를 활성화하는 방법은 안내를 참조하세요.

XML 스트림 유형

XML 로그 이벤트를 파싱할 때 Panther는 XML 요소를 JSON 객체로 변환합니다. 높은 수준에서 요소 이름은 키가 되고 텍스트 내용은 값이 됩니다. XML 로그용 사용자 지정 스키마를 만드는 방법에 대해 자세히 알아보려면 여기에서 확인하세요.

XML 루트 요소 지원

Panther는 로그 이벤트가 루트 요소 안에 포함된 XML 파일을 파싱할 수 있습니다(이벤트가 최상위 요소인 파일도 지원함). 루트 요소를 지정하면 Panther는 그 안에 포함된 개별 이벤트를 추출하여 각 하위 요소를 별도의 로그 이벤트로 처리합니다.

루트 요소 안에 포함된 이벤트를 파싱하려면 Panther에서 스트림 유형을 선택할 때:

  1. 스트림 유형으로 XML.

  2. 다음을 설정하세요 XML 이벤트가 루트 요소 안에 포함되어 있나요? 토글을 .

  3. 다음 XML 루트 요소 필드에 루트 요소 이름을 입력하세요(예: logs, events, data).

    Various form fields are circled: A radio button labeled "XML," a toggle set to "Yes," a text field labeled "XML Root Element," etc.

XML 처리 규칙

더 자세히 설명하면, Panther가 XML 파일을 처리하는 방식은 다음과 같습니다:

  • 모든 최상위 XML 요소는 별도의 이벤트로 처리됩니다. 단, 루트 요소가 지정된 경우에는 Panther가 해당 요소 내부에서 이벤트를 추출합니다.

    • 중첩 요소는 중첩 객체로 감싸집니다.

  • 요소 이름은 필드 이름이 됩니다.

    • 같은 중첩 수준에 있는 여러 요소의 이름이 같으면, 공유 요소 이름이 키가 되고 요소 내용(즉, 텍스트 내용, 속성, 중첩 필드 등)의 배열이 값인 배열 필드가 생성됩니다.

  • 텍스트 내용은 필드 값이 됩니다.

    • 요소에 텍스트 내용만 있고 속성이나 중첩 요소가 없으면, 텍스트 내용은 필드 값으로 직접 파싱됩니다.

    • 요소에 1) 텍스트 내용과 2) 하나 이상의 속성 또는 중첩 요소가 모두 있으면, 텍스트 내용은 text 키의 값으로 저장됩니다.

    • 요소가 비어 있으면(즉, 텍스트 내용이 없으면) 값은 null.

    • 텍스트 내용이 하나 이상의 요소에 의해 나뉘어 있으면 각 부분은 공백으로 이어 붙여집니다.

  • 요소 속성(예: <User role="admin">)은 텍스트 내용과 함께 공유 중첩 객체의 키/값 쌍으로 추가됩니다.

    • 속성 이름이 중첩 요소 이름과 충돌하면(해당 이름과 같은 필드 이름이 결과 중첩 객체에 생성됨), 속성 이름에는 _attr 접미사가 붙습니다. 속성 이름이 text 이고 요소에 텍스트 내용이 있으면(이 경우 중첩 text 키가 생성됨), 속성 필드는 text_attr.

    • 다음 xmlns 속성(XML 네임스페이스 선언)은 자동으로 건너뜁니다.

예시 XML 입력:

Panther는 다음과 같이 처리합니다:

마지막 업데이트

도움이 되었나요?