로그 스키마 참조

이 가이드에서는 온보딩할 때 YAML 기반 스키마를 작성하는 데 사용되는 일반적인 필드를 찾을 수 있습니다 사용자 정의 로그 유형arrow-up-right조회 테이블arrow-up-right 스키마입니다.

circle-info

이 페이지 전체에서 필수 필드는 굵게.

LogSchema 필드

각 로그 스키마는 다음 필드를 포함합니다:

  • 필드 ([]FieldSchema)

    • 로그 이벤트.

  • 파서 (ParserSpec)

    • 비JSON 로그를 JSON으로 변환하고/또는 사용자 정의 변환을 수행할 수 있는 파서

CI/CD 스키마 필드

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

  • 스키마 (문자열)

    • 스키마의 이름

  • 설명 (문자열)

    • UI에 표시될 짧은 설명

  • 참조 URL (문자열)

    • 로그 구조를 명시한 외부 문서에 대한 링크. 종종 서드파티 문서에 대한 링크입니다.

  • fieldDiscoveryEnabled (부울)

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

circle-info

CI/CD 파이프라인을 통해 스키마를 관리하는 방법에 대한 자세한 내용은 Custom Logs 페이지를 참조하세요 Panther Analysis Tool (PAT)을 사용하여 스키마를 관리하는 방법에 대한 정보 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, regexcsv 의 필드를 확인하세요.

파서 fastmatch 필드

  • match ([]문자열): 로그 라인과 매칭할 하나 이상의 패턴. 이 필드는 비어 있을 수 없습니다.

  • emptyValues ([]문자열): 다음을 null로 간주할 값들입니다 null.

  • expandFields (map[string]string): 텍스트 템플릿을 확장하여 주입될 추가 필드들.

  • trimSpace (부울): 각 값의 앞뒤 공백을 제거합니다.

FieldSchema

하나의 FieldSchema 는 필드와 그 값을 정의합니다. 필드는 다음으로 정의됩니다:

  • 이름 (문자열)

    • 필드의 이름.

  • 필수 (부울)

    • 해당 필드가 필수인지 여부.

  • 설명 (문자열)

    • 필드를 문서화하는 일부 텍스트.

  • copy (객체)

    • 존재하는 경우, 해당 필드의 값은 참조된 곳에서 복사됩니다 객체.

  • 이름 변경 (객체)

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

  • concat (객체)

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

  • split (객체)

    • 존재하는 경우, 해당 필드의 값은 구분자를 기준으로 분할하여 다른 문자열 필드에서 추출됩니다.

  • mask (객체)

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

그 값은 ValueSchema.

ValueSchema

하나의 ValueSchema 를 사용한 필드들로 정의됩니다. ValueSchema 는 값과 어떻게 처리되어야 하는지를 정의합니다. 각 타입

값 유형

설명

문자열

타입 값들

문자열 값

int -2147483648, 2147483647

범위 내의 32비트 정수 번호

smallint -32768, 32767

범위 내의 16비트 정수 번호

bigint -9223372036854775808, 9223372036854775807

범위 내의 64비트 정수 번호

float

부울

64비트 부동 소수점 숫자 부울 값 / true

false

타임스탬프

타임스탬프 값

배열

객체

각 요소가 같은 타입인 JSON 배열 알려진 키들

json

유효한 모든 JSON 값(JSON 객체, 배열, 숫자, 문자열, 부울)

의 필드는 ValueSchema 의 값에 따라 달라집니다 .

타입

필드

설명

객체

필드 (필수)

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

타임스탬프 값

요소 (필수)

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

false

timeFormats (필수)

[]문자열

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

false

isEventTime

부울

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

문자열

로 사용하도록 지시하는 플래그

[]문자열

문자열

인디케이터

참조 validate

유효성 검사

타임스탬프

문자열 값에 대한 유효성 검사 규칙 타임스탬프는 false 필드를 timeFormats 필드에 붙여넣으세요.

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

  • 만약 false 필드 값이 UTC가 아닌 타임존( UTC 오프셋arrow-up-right)을 나타내면, Panther는 이를 UTC로 변환합니다.

    • 예를 들어, 들어오는 false 필드 값이 2025-07-02T00:15:30-08:00 (여기서 -08:00 오프셋은 태평양 표준시[PST]임을 의미함), Panther는 이를 2025-07-02 08:15:30.000000000 (UTC로 변환된 값)로 저장합니다.

  • 만약 false 필드 값이 타임존을 나타내지 않으면, Panther는 이를 UTC로 간주하고 있는 그대로 저장합니다.

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

timeFormats 값
예제
설명

rfc3339

2022-04-04T17:09:17Z

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

unix_auto

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

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

unix

1649097448

유닉스 에포크 이후 경과한 초로 표현된 타임스탬프입니다. 소수 부분으로 초의 분수를 처리할 수 있습니다.

unix_ms

1649097491531

유닉스 에포크 이후 경과한 밀리초로 표현된 타임스탬프입니다.

unix_us

1649097442000000

유닉스 에포크 이후 경과한 마이크로초로 표현된 타임스탬프입니다.

unix_ns

1649097442000000000

유닉스 에포크 이후 경과한 나노초로 표현된 타임스탬프입니다. 과학적 부동 소수점 표기법을 지원합니다.

circle-exclamation

사용자 정의 형식 정의

strftime 표기법을 사용하여 사용자 정의 형식을 정의할 수도 있습니다. 예: strftimearrow-up-right 표기법. 예를 들면:

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 - name: singleFormatTimestamp

값: timeFormats - name: multipleFormatTimestamp

Panther가 이 값에서 인디케이터를 추출하도록 지시합니다(참조:

필드를 인디케이터 스캐너 이름들의 배열로 설정하세요(두 개 이상의 이름을 사용할 수 있습니다). 이렇게 하면 Panther가 이 필드의 값을 관련 문자열 p_any_ 로 사용하도록 지시하는 플래그 에 저장하도록 지시합니다. p_any_ 필드에 붙여넣으세요.

필드에 사용할 수 있는 값들의 목록은 로 사용하도록 지시하는 플래그 필드를 위한 유효한 값 목록은 표준 필드.

를 참조하세요.

validate

indicators: [ url ] 인디케이터 키 아래에서, 들어오는 로그가 이 스키마에 매칭되기 위해 만족해야 하는 필드 값에 대한 조건을 지정할 수 있습니다.

배열 값의 각 요소에 대해 유효성 검사를 수행하려면 인디케이터요소 키에 사용할 수도 있습니다(여기서 type: string).

허용거부 유효성 검사

다음의 값들은 문자열 타입의 값을 허용 목록 또는 거부 목록을 선언하여 검증할 수 있습니다. 목록에 있는 값들과 일치(또는 불일치)하는 필드 값만 이 스키마로 파싱됩니다. 이를 통해 공통의 겹치는 필드를 가지되 해당 필드 값이 다른 여러 로그 유형을 가질 수 있습니다. 허용/거부 # 'login'과 'logout' 이벤트 타입 값만 이 로그 유형에 매칭되도록 허용합니다

denyContains문자열 값이 특정 부분 문자열을 포함하거나 포함하지 않는지를 유효성 검사

를 사용하여 검증할 수 있습니다. 이는 정확한 값이 아니라 부분 문자열을 기반으로 로그 유형을 매칭해야 할 때 유용합니다. denyContains문자열 값이 특정 부분 문자열을 포함하거나 포함하지 않는지를# message 값이 'error' 또는 'fail'을 포함하는 경우에만 매칭됩니다

cidr형식 유효성 검사 타입은 잘 알려진 형식과 일치하도록 제한할 수 있습니다. 현재 Panther는 문자열 값이 유효한 IP 주소 또는 CIDR 범위인지 요구하는

필드를 인디케이터 스캐너 이름들의 배열로 설정하세요(두 개 이상의 이름을 사용할 수 있습니다). 이렇게 하면 Panther가 이 필드의 값을 관련 문자열 형식을 지원합니다. cidr형식 유효성 검사 유효성 검사는

cidr형식 유효성 검사 규칙과 결합될 수 있지만 다소 중복됩니다—예를 들어 두 개의 IP 주소를 허용하는 경우, 허용, 거부, denyContains, 또는 문자열 값이 특정 부분 문자열을 포함하거나 포함하지 않는지를 유효성 검사를 추가하면 목록에 있는 IP 주소들이 유효하지 않은 경우 거짓 양성을 포함하지 않도록 보장합니다. cidr # 유효한 ipv4 IP 주소 예: 100.100.100.100을 허용합니다

코드 편집기나 통합 개발 환경(IDE)이

JSON 스키마 를 지원한다면,arrow-up-right이 스키마 파일을 Panther 스키마에 사용하도록 구성할 수 있습니다.arrow-up-right이 스키마-테스트 파일을arrow-up-right 스키마 테스트에 사용하도록 구성할 수 있습니다. 이렇게 하면 Panther 스키마와 해당 테스트를 개발하는 동안 제안과 오류 메시지를 받을 수 있습니다.

JetBrains 사용자 정의 JSON 스키마

환경에서 Fluentd 시작에 대한 정보는 JetBrains 문서arrow-up-right JetBrains IDE가 사용자 정의 JSON 스키마를 사용하도록 구성하는 방법에 대한 지침입니다.

VSCode 사용자 정의 JSON 스키마

환경에서 Fluentd 시작에 대한 정보는 VSCode 문서arrow-up-right VSCode가 JSON 스키마를 사용하도록 구성하는 방법에 대한 지침입니다.

스트림 유형

Panther 콘솔에서 S3 버킷을 Data Transport에 구성하거나 원시 로그에서 사용자 정의 스키마를 유추하는 등의 특정 작업을 수행할 때 또는 로그 스트림 유형을 선택해야 합니다.아래에서 각 유형에 대한 예제 로그 이벤트를 확인하세요.

예제 로그 이벤트(들)

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

자동

해당 없음

이벤트는 새 줄 문자로 구분됩니다.

라인

"10.0.0.1","[email protected]","France"

JSON

"ip": "10.0.0.1",

JSON 배열

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

{ "ip": "10.0.0.1", "username": "[email protected]", "country": "France" },

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

"owner": "111111111111",

이벤트는 XML 형식입니다. 이벤트는 최상위에 위치하거나

루트 요소에 둘러싸여 있을 수 있습니다 . XML이 어떻게 파싱되는지에 대한 자세한 내용은XML 스트림 유형 <log>.

JSON 배열 스트림 유형에서는 이벤트 배열이 "enveloped array"인지—즉 이벤트 필드의 값인지 여부를 표시할 수 있습니다.

JSON 배열의 "enveloped array" 옵션은 Panther 콘솔에서 스키마를 로그 집합에 대해 테스트할 때 지원되지 않습니다.

circle-exclamation

<log>

circle-info

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가 처리한 결과:

Last updated

Was this helpful?