> For the complete documentation index, see [llms.txt](https://docs.panther.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.panther.com/ko/data-onboarding/custom-log-types/reference.md).

# 로그 스키마 참조

이 가이드에서는 온보딩 시 YAML 기반 스키마를 빌드할 때 사용하는 일반적인 필드를 찾을 수 있습니다 [사용자 정의 로그 유형](https://docs.panther.com/data-onboarding/custom-log-types) 그리고 [조회 테이블](https://docs.panther.com/enrichment/lookup-tables) 스키마.

{% hint style="info" %}
이 페이지 전반의 필수 필드는 **굵게**.
{% endhint %}

## LogSchema 필드

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

* **`필드`** ([`[]FieldSchema`](#fieldschema))
  * 각각의 필드는 *로그 이벤트*.
* `파서` ([`ParserSpec`](#parserspec))
  * 비 JSON 로그를 JSON으로 변환하고/또는 사용자 정의 변환을 수행할 수 있는 파서

### CI/CD 스키마 필드

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

* **`스키마`** (`문자열`)
  * 스키마 이름
* `설명` (`문자열`)
  * UI에 표시될 짧은 설명
* `참조 URL` (`문자열`)
  * 로그 구조를 지정하는 외부 문서로 연결되는 링크입니다. 보통 제3자 문서로 연결됩니다.
* `fieldDiscoveryEnabled` (`불리언`)
  * 다음 여부를 나타냅니다 [필드 검색](/ko/data-onboarding/custom-log-types.md#enabling-field-discovery) 이 스키마에 대해 활성화될지 여부.

{% hint style="info" %}
에서 Custom Logs 페이지를 참조하세요 [CI/CD 파이프라인을 통해 스키마를 관리하는 방법에 대한 정보](/ko/data-onboarding/custom-log-types.md#uploading-log-schemas-with-the-panther-analysis-tool)[ ](/ko/data-onboarding/custom-log-types.md#uploading-log-schemas-with-the-panther-analysis-tool)Panther Analysis Tool(PAT) 사용.
{% endhint %}

### 예시

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

```yaml
schema: Custom.MySchema
description: (선택 사항) 스키마가 무엇을 위한 것인지 알 수 있도록 하는 간단한 설명.
referenceURL: (선택 사항) 이 스키마가 대상으로 하는 로그에 대한 문서 링크.
fieldDiscoveryEnabled: true
파서:
  csv:
    delimiter: ','
    hasHeader: true
fields:
- 이름: action
  type: string
  required: true
- 이름: time
  type: timestamp
  timeFormats:
    - unix
```

### ParserSpec

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

* `fastmatch` (`FastmatchParser{}`): 사용 `fastmatch` 파서
  * 자세한 내용은 [Fastmatch 로그 파서](/ko/data-onboarding/custom-log-types/fastmatch-parser.md).
* `regex` (`RegexParser{}`): 사용 `regex` 파서
  * 자세한 내용은 [정규식 로그 파서](/ko/data-onboarding/custom-log-types/regex-parser.md).
* `csv` (`CSVParser{}`): 사용 `csv` 파서
  * 참고: `열` 필드는 동일한 로그 소스에 여러 CSV 스키마가 있을 때 필요합니다.
  * 자세한 내용은 [CSV 로그 파서](/ko/data-onboarding/custom-log-types/csv-parser.md).
* `script`): 사용 `script` 파서
  * 자세한 내용은 [스크립트 로그 파서](/ko/data-onboarding/custom-log-types/script-parser.md).

다음의 필드를 참조하세요 `fastmatch`, `regex`, 그리고 `csv` 아래 탭에서.

{% tabs %}
{% tab title="fastmatch" %}
**파서 `fastmatch` 필드**

* **`match`** (`[]string`): 로그 줄과 일치시킬 하나 이상의 패턴입니다. 이 필드는 비워둘 수 없습니다.
* `emptyValues` (`[]string`): 다음으로 간주할 값 `null`.
* `expandFields` (`map[string]string`): 텍스트 템플릿 확장을 통해 주입될 추가 필드입니다.
* `trimSpace` (`불리언`): 각 값 주변의 공백을 제거합니다.
  {% endtab %}

{% tab title="regex" %}
**파서 `regex` 필드**

* **`match`** (`[]string`): 로그 줄과 일치시킬 패턴입니다(문서 목적상 부분으로 나눌 수 있습니다). 이 필드는 비워둘 수 없습니다.
* `patternDefinitions` (`map[string]string`): match 패턴에서 사용할 추가 명명된 패턴입니다.
* `emptyValues` (`[]string`): 다음으로 간주할 값 `null`.
* `expandFields` (`map[string]string`): 텍스트 템플릿 확장을 통해 주입될 추가 필드입니다.
* `trimSpace` (`불리언`): 각 값 주변의 공백을 제거합니다.
  {% endtab %}

{% tab title="csv" %}
**파서 `csv` 필드**

* **`delimiter`** (`문자열`): 필드 구분자로 사용할 문자입니다.
* `hasHeader` (`불리언`): 첫 번째 행을 사용하여 열 이름을 유추합니다(단, `열` 도 함께 설정된 경우에는 헤더를 건너뛸 뿐입니다).
* `열` (`[]string`, `필수(hasHeader 없음)`, `비어 있지 않음`): CSV 파일의 각 열 이름입니다. 설정하지 않으면 첫 번째 행이 헤더로 사용됩니다.
* `emptyValues` (`[]string`): 다음으로 간주할 값 `null`.
* `trimSpace` (`불리언`): 각 값 주변의 공백을 제거합니다.
* `expandFields` (`map[string]string`): 텍스트 템플릿 확장을 통해 주입될 추가 필드입니다.
  {% endtab %}

{% tab title="script" %}
**파서 `script` 필드**

* **`함수`** (`문자열`): [Starlark](https://bazel.build/rules/language) 이벤트마다 실행할 함수
  {% endtab %}
  {% endtabs %}

### FieldSchema

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

* **`이름`** (`문자열`)
  * 필드의 이름입니다.
* `필수` (`불리언`)
  * 필드가 필수인지 여부입니다.
* `설명` (`문자열`)
  * 필드를 설명하는 텍스트입니다.
* [`복사`](/ko/data-onboarding/custom-log-types/transformations.md#copy) (`객체`)
  * 존재하는 경우, 필드 값은 참조된 `객체`.
* [`이름 변경`](/ko/data-onboarding/custom-log-types/transformations.md#rename) (`객체`)
  * 존재하는 경우, 필드의 이름이 변경됩니다.
* [`연결`](/ko/data-onboarding/custom-log-types/transformations.md#concat) (`객체`)
  * 존재하는 경우, 필드 값은 두 개 이상의 다른 필드 값의 조합이 됩니다.
* [`분할`](/ko/data-onboarding/custom-log-types/transformations.md#split) (`객체`)
  * 존재하는 경우, 필드 값은 구분자를 기준으로 다른 문자열 필드에서 분할하여 추출됩니다.
* [`마스킹`](/ko/data-onboarding/custom-log-types/transformations.md#mask) (`객체`)
  * 존재하는 경우, 필드 값이 마스킹됩니다.

그 값은 다음의 필드를 사용하여 정의됩니다: [`ValueSchema`](#valueschema).

### ValueSchema

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

<table data-header-hidden><thead><tr><th width="268">값 유형</th><th>설명</th></tr></thead><tbody><tr><td>유형 값</td><td>설명</td></tr><tr><td><code>문자열</code></td><td>문자열 값</td></tr><tr><td><code>int</code></td><td>범위 내의 32비트 정수 <code>-2147483648</code>, <code>2147483647</code></td></tr><tr><td><code>smallint</code></td><td>범위 내의 16비트 정수 <code>-32768</code>, <code>32767</code></td></tr><tr><td><code>bigint</code></td><td>범위 내의 64비트 정수 <code>-9223372036854775808</code>, <code>9223372036854775807</code></td></tr><tr><td><code>float</code></td><td>64비트 부동 소수점 수</td></tr><tr><td><code>불리언</code></td><td>불리언 값 <code>true</code> / <code>false</code></td></tr><tr><td><code>timestamp</code></td><td>타임스탬프 값</td></tr><tr><td><code>배열</code></td><td>각 요소가 동일한 유형인 JSON 배열</td></tr><tr><td><code>객체</code></td><td>다음의 JSON 객체 <em>알려진</em> 키</td></tr><tr><td><code>json</code></td><td>유효한 모든 JSON 값(JSON 객체, 배열, 숫자, 문자열, 불리언)</td></tr></tbody></table>

다음의 필드들은 `ValueSchema` 의 값에 따라 달라집니다 `type`.

<table data-header-hidden><thead><tr><th width="171">Type</th><th width="192">필드</th><th width="162">값</th><th>설명</th></tr></thead><tbody><tr><td>Type</td><td>필드</td><td>값</td><td>설명</td></tr><tr><td><code>객체</code></td><td><strong><code>필드</code></strong> (필수)</td><td><a href="#fieldschema"><code>[]FieldSpec</code></a></td><td>다음의 배열 <code>FieldSpec</code> 객체의 필드를 설명하는 객체들입니다.</td></tr><tr><td><code>배열</code></td><td><strong><code>요소</code></strong> (필수)</td><td><a href="#valueschema"><code>ValueSchema</code></a></td><td>하나의 <code>ValueSchema</code> 배열의 요소를 설명합니다.</td></tr><tr><td><code>timestamp</code></td><td><strong><code>timeFormats</code></strong> (필수)</td><td><code>[]String</code></td><td>타임스탬프를 파싱할 때 사용할 형식을 지정하는 배열입니다( <a href="#timestamps">타임스탬프</a>)</td></tr><tr><td><code>timestamp</code></td><td><code>isEventTime</code></td><td><code>불리언</code></td><td>Panther가 이 타임스탬프를 다음으로 사용하도록 지정하는 플래그입니다 <em>로그 이벤트 타임스탬프</em>.</td></tr><tr><td><code>문자열</code></td><td><code>indicators</code></td><td><code>[]String</code></td><td>Panther가 이 값에서 인디케이터를 추출하도록 지시합니다( <a href="#indicators">인디케이터</a>)</td></tr><tr><td><code>문자열</code></td><td><code>validate</code></td><td>참조 <a href="#validate">검증</a></td><td>문자열 값에 대한 검증 규칙</td></tr></tbody></table>

### 타임스탬프

타임스탬프는 다음을 설정하여 정의합니다 `type` 필드를 `timestamp` 로 설정하고, 다음을 사용하여 타임스탬프 형식을 지정합니다 `timeFormats` 필드에 붙여넣습니다.

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

* 만약 `timestamp` 필드 값이 UTC 이외의 시간대를 나타내는 경우( [UTC 오프셋](https://en.wikipedia.org/wiki/UTC_offset)), Panther가 이를 UTC로 변환합니다.
  * 예를 들어, 들어오는 `timestamp` 필드의 값이 `2025-07-02T00:15:30-08:00` (여기서 `-08:00` 오프셋은 태평양 표준시\[PST]를 의미합니다), Panther는 이를 다음으로 저장합니다 `2025-07-02 08:15:30.000000000` (UTC로 변환됨).
* 만약 `timestamp` 필드 값이 시간대를 나타내지 않으면, Panther는 이를 UTC로 간주하고 그대로 저장합니다.

다음의 허용되는 `timeFormats` 값을 참조하세요:

<table><thead><tr><th width="154.00000000000003">timeFormats 값</th><th width="276">예시</th><th>설명</th></tr></thead><tbody><tr><td><code>rfc3339</code></td><td><code>2022-04-04T17:09:17Z</code></td><td>가장 일반적인 타임스탬프 형식입니다.</td></tr><tr><td><code>unix_auto</code></td><td><code>1649097448</code> (초)<br><br><code>1649097491531</code> (밀리초)<br><br><code>1649097442000000</code> (마이크로초)<br><br><code>1649097442000000000</code> (나노초)</td><td>UNIX 에포크 이후 경과한 시간으로 표현된 타임스탬프입니다. 초, 밀리초, 마이크로초, 나노초를 처리할 수 있습니다.</td></tr><tr><td><code>unix</code></td><td><code>1649097448</code></td><td>UNIX 에포크 이후 초 단위로 표현된 타임스탬프입니다. 소수점 이하의 초를 처리할 수 있습니다.</td></tr><tr><td><code>unix_ms</code></td><td><code>1649097491531</code></td><td>UNIX 에포크 이후 밀리초 단위로 표현된 타임스탬프입니다.</td></tr><tr><td><code>unix_us</code></td><td><code>1649097442000000</code></td><td>UNIX 에포크 이후 마이크로초 단위로 표현된 타임스탬프입니다.</td></tr><tr><td><code>unix_ns</code></td><td><code>1649097442000000000</code></td><td>UNIX 에포크 이후 나노초 단위로 표현된 타임스탬프입니다. 과학적 부동소수점 표기법이 지원됩니다.</td></tr></tbody></table>

{% hint style="warning" %}
해당 `timeFormats` 필드는 사용자 정의 로그 스키마에서 여러 타임스탬프 형식을 지원하기 위해 Panther v1.46에서 도입되었습니다. 그러나 `timeFormat` 는 v1.46 이전에 설정된 로그 소스에 대해 여전히 지원되지만, `timeFormats` 모든 새 스키마에는 이를 사용하세요.
{% endhint %}

#### 사용자 정의 형식 정의

다음을 사용하여 사용자 정의 형식을 정의할 수도 있습니다 [strftime](https://strftime.org) 표기법을 사용합니다. 예:

```yaml
# 필드는 "2020-09-14 14:29:21" 같은 사용자 정의 타임스탬프 형식을 사용하는 타임스탬프입니다
- name: ts
  type: timestamp
  timeFormats:
    - "%Y-%m-%d %H:%M:%S" # 올바른 YAML 구문을 위해 따옴표가 필요합니다
```

Panther의 strftime 형식은 다음을 사용한 파싱을 지원합니다 `%N` 코드로 나노초를 파싱합니다. 예:

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

#### 여러 타임 형식 사용

여러 타임 형식이 정의되면, 파싱에 성공할 때까지 각 형식을 순차적으로 시도합니다:

```yaml
- name: ts
  type: timestamp
  timeFormats:
    - rfc3339
    - unix
```

타임스탬프 값은 다음으로 표시할 수 있습니다 `isEventTime: true` Panther가 이 타임스탬프를 다음으로 사용하도록 지정합니다 `p_event_time` 필드입니다. 다음을 설정할 수도 있습니다 `isEventTime` 을 여러 필드에 설정할 수 있습니다. 이는 로그에 이벤트 시간 정보를 담는 선택적 또는 상호 배타적인 필드가 있는 경우 유용할 수 있습니다. 각 로그 이벤트마다 단 하나의 `p_event_time` 만 존재할 수 있으므로, 우선순위는 스키마의 필드 순서로 정의됩니다.

#### 다음과 함께 작업하기 `timeFormats` 스키마 테스트에서

다음과 함께 실행할 스키마 테스트를 작성할 때 [`pantherlog test` 명령](/ko/panther/pantherlog.md#test-run-tests-for-a-schema):

* 스키마 필드에 단일 `timeFormats` 값이 있는 경우, 하위 호환성을 위해 구성은 동일한 형식을 유지합니다.
* 스키마 필드에 여러 `timeFormats` 값이 있는 경우, 타임스탬프 필드 값을 다음 형식으로 정의해야 합니다 `결과` 페이로드 형식 `YYYY-MM-DD HH:MM:SS.fffffffff`.

단일 `timeFormats` 값의 예:

```yaml
- name: singleFormatTimestamp
  type: timestamp
  timeFormats:
    - unix
```

```yaml
input: >
  {
    "singleFormatTimestamp": "1666613239"
  }
result: >
  {
    "singleFormatTimestamp": "1666613239"
  }
```

여러 `timeFormats` 값의 예:

```yaml
- name: multipleFormatTimestamp
  type: timestamp
  timeFormats:
    - unix
    - rfc3339
```

```yaml
input: >
  {
    "multipleFormatTimestamp": "1666613239"
  }
result: >
  {
    "multipleFormatTimestamp": "2022-10-24 12:07:19.459326000"
  }
```

### 인디케이터

다음 값의 `문자열` type은 "인디케이터"로 사용할 수 있습니다. 필드를 인디케이터로 표시하려면 `indicators` 필드를 인디케이터 스캐너 이름의 배열로 설정합니다(여러 개를 사용할 수 있음). 그러면 Panther가 이 필드 값을 관련된 `p_any_` 필드에 붙여넣습니다.

다음에서 사용할 수 있는 유효한 값 목록은 `indicators` 필드를 참조하세요 [표준 필드](/ko/search/panther-fields.md#indicator-fields).

예:

```yaml
# 값을 IP 주소로 스캔하여 `p_any_ip_addresses`에 저장합니다
- 이름: remote_ip
  type: string
  indicators: [ ip ]

# 값을 도메인 이름 및/또는 IP 주소로 스캔합니다.
# 결과를 `p_any_domain_names` 및/또는 `p_any_ip_addresses`에 저장합니다
- name: target_url
  type: string
  indicators: [ url ]
```

### 검증

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

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

#### `허용` 그리고 `거부` 검증

다음의 값을 검증할 수 있습니다 `문자열` 유형은 allowlist 또는 denylist를 선언하여 검증할 수 있습니다. 다음의 값과 일치(또는 불일치)하는 필드 값을 가진 로그만 `허용`/`거부` 이 스키마로 파싱됩니다. 즉, 공통적으로 겹치는 필드를 가지지만 해당 필드 값이 다른 여러 로그 유형을 가질 수 있습니다.

```yaml
# 'login' 및 'logout' event_type 값만 이 로그 유형과 일치하도록 허용합니다
- 이름: event_type
  type: string
  검증:
    allow: [ "login", "logout"]
    
# 로그에 'login' 및 'logout' 이외의 event_type 값이 있으면 일치합니다
- 이름: event_type
  type: string
  검증:
    deny: [ "login", "logout"]
    
# 문자열 배열 요소와도 함께 사용할 수 있습니다    
# 값이 'info' 또는 'low'인 severities 필드가 있는 로그와 일치합니다 
- name: severities
  type: array
  element:
    type: string
    검증:
      allow: ["info", "low"]
```

#### `allowContains` 그리고 `denyContains` 검증

문자열 값에 특정 부분 문자열이 포함되어 있는지 또는 포함되어 있지 않은지를 다음을 사용해 검증할 수 있습니다 `allowContains` 그리고 `denyContains`. 이는 정확한 값이 아니라 부분 문자열 내용에 따라 로그 유형을 일치시켜야 할 때 유용합니다.

```yaml
# message 값에 'error' 또는 'fail'이 포함된 로그와만 일치합니다
- name: message
  type: string
  검증:
    allowContains: ["error", "fail"]
    
# message 값에 'password' 또는 'secret'이 포함되어 있지 않은 로그와 일치합니다
- name: message
  type: string
  검증:
    denyContains: ["password", "secret"]
    
# 문자열 배열 요소와도 함께 사용할 수 있습니다
# 'critical' 또는 'warning'이 포함된 tags 값을 가진 로그와 일치합니다
- name: tags
  type: array
  element:
    type: string
    검증:
      allowContains: ["critical", "warning"]
```

#### `IP` 그리고 `CIDR` 형식 검증

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

`IP` 그리고 `CIDR` 검증은 다음과 함께 결합할 수 있습니다 `허용`, `거부`, `allowContains`, 또는 `denyContains` 규칙과 함께 사용할 수 있지만, 그렇게 하면 다소 중복됩니다. 예를 들어, 두 개의 IP 주소를 허용하는 경우 `IP` 검증을 추가하면 목록의 IP 주소가 유효하지 않을 때 검증에 오탐이 포함되지 않도록 보장할 뿐입니다.

```yaml
# 유효한 IPv4 IP 주소(예: 100.100.100.100)를 허용합니다
- name: address
  type: string
  검증:
    ip: "ipv4"
    
# 유효한 ipv6 CIDR 범위를 허용합니다 
# 예: 2001:0db8:85a3:0000:0000:0000:0000:0000/64
- name: address
  type: string
  검증:
    cidr: "ipv6"
    
# 유효한 ipv4 또는 ipv6 주소를 모두 허용합니다
- name: address
  type: string
  검증:
    ip: "any"
    
# addresses 배열의 모든 요소는 유효한 ipv4 ID 주소여야 합니다
- name: addresses
  type: array
  element:
    type: string
    검증:
      ip: "ipv4"
```

## IDE에서 JSON 스키마 사용하기

코드 편집기 또는 통합 개발 환경(IDE)이 지원한다면 [JSON 스키마](https://json-schema.org/), 이를 사용하도록 구성할 수 있습니다 [이 스키마 파일](https://panther-community-us-east-1.s3.amazonaws.com/latest/logschema/schema.json) Panther 스키마에 사용하고 [이 스키마 테스트 파일](https://panther-community-us-east-1.s3.amazonaws.com/latest/logschema/schema-tests.json) 스키마 테스트에 사용합니다. 이렇게 하면 Panther 스키마와 해당 테스트를 개발하는 동안 제안과 오류 메시지를 받을 수 있습니다.

### JetBrains 사용자 지정 JSON 스키마

다음을 참조하세요 [JetBrains 문서](https://www.jetbrains.com/help/phpstorm/json.html#ws_json_schema_add_custom) JetBrains IDE가 사용자 지정 JSON 스키마를 사용하도록 구성하는 방법은 해당 안내를 참조하세요.

### VSCode 사용자 지정 JSON 스키마

다음을 참조하세요 [VSCode 문서](https://code.visualstudio.com/Docs/languages/json#_json-schemas-and-settings) VSCode가 JSON 스키마를 사용하도록 구성하는 방법은 해당 안내를 참조하세요.

## 스트림 유형

Panther Console에서 다음과 같은 작업을 수행하는 동안 [Data Transport용 S3 버킷을 구성하거나 ](/ko/data-onboarding/data-transports/aws/s3.md)또는 [원시 로그에서 사용자 지정 스키마를 추론하는 등](/ko/data-onboarding/custom-log-types.md#infer-a-schema-from-raw-data), 로그 스트림 유형을 선택해야 합니다.

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

<table><thead><tr><th width="144">스트림 유형</th><th width="205">설명</th><th>예시 로그 이벤트</th></tr></thead><tbody><tr><td>자동</td><td>Panther가 적절한 스트림 유형을 자동으로 감지합니다.</td><td>해당 없음</td></tr><tr><td>줄</td><td>이벤트는 줄바꿈 문자로 구분됩니다.</td><td><pre class="language-json"><code class="lang-json">"10.0.0.1","user-1@example.com","France"
"10.0.0.2","user-2@example.com","France"
"10.0.0.3","user-3@example.com","France"
</code></pre></td></tr><tr><td>JSON</td><td>이벤트는 JSON 형식입니다.</td><td><pre class="language-json"><code class="lang-json">{ 
    "ip": "10.0.0.1", 
    "un": "user-1@example.com", 
    "country": "France" 
}
또는
{ "ip": "10.0.0.1", "un": "user-1@example.com", "country": "France" }{ "ip": "10.0.0.2", "un": "user-2@example.com", "country": "France" }{ "ip": "10.0.0.3", "un": "user-3@example.com", "country": "France" }
또는
{ "ip": "10.0.0.1", "un": "user-1@example.com", "country": "France" }
{ "ip": "10.0.0.2", "un": "user-2@example.com", "country": "France" }
{ "ip": "10.0.0.3", "un": "user-3@example.com", "country": "France"}또는
</code></pre></td></tr><tr><td>JSON 배열</td><td><p>이벤트는 JSON 객체 배열 안에 있습니다.<br></p><p>또는<br><br>이벤트는 JSON 객체 배열 안에 있으며, 이는 최상위 객체의 키에 대한 값입니다. 이를 "enveloped array"라고 할 수 있습니다.</p></td><td><pre class="language-json"><code class="lang-json">[
	{ "ip": "10.0.0.1", "username": "user-1@example.com", "country": "France" },
	{ "ip": "10.0.0.2", "username": "user-2@example.com", "country": "France" },
	{ "ip": "10.0.0.3", "username": "user-3@example.com", "country": "France" }
]
또는
{ "events": [
        { "ip": "10.0.0.1", "username": "user-1@example.com", "country": "France" },
	{ "ip": "10.0.0.2", "username": "user-2@example.com", "country": "France" },
	{ "ip": "10.0.0.3", "username": "user-3@example.com", "country": "France" }
    ] 
}
</code></pre></td></tr><tr><td>CloudWatch Logs</td><td>이벤트는 CloudWatch Logs에서 왔습니다.</td><td><pre class="language-json"><code class="lang-json">{
  "owner": "111111111111",
  "logGroup": "services/foo/logs",
  "logStream": "111111111111_CloudTrail/logs_us-east-1",
  "messageType": "DATA_MESSAGE",
  "logEvents": [
      {
          "id": "31953106606966983378809025079804211143289615424298221568",
          "timestamp": 1432826855000,
          "message": "{\"ip\": \"10.0.0.1\", \"user\": \"user-1@example.com\", \"country\": \"France\"}"
      },
      {
          "id": "31953106606966983378809025079804211143289615424298221569",
          "timestamp": 1432826855000,
          "message": "{\"ip\": \"10.0.0.2\", \"user\": \"user-2@example.com\", \"country\": \"France\"}"
      },
      {
          "id": "31953106606966983378809025079804211143289615424298221570",
          "timestamp": 1432826855000,
          "message": "{\"ip\": \"10.0.0.3\", \"user\": \"user-3@example.com\", \"country\": \"France\"}"
      }
  ]
}
</code></pre></td></tr><tr><td>XML</td><td>이벤트는 XML 형식입니다. 이벤트는 최상위 수준에 위치하거나 <a href="#xml-root-element-support">루트 요소에 포함됩니다</a>. Panther에서 XML이 어떻게 파싱되는지 자세히 알아보세요 <a href="#xml-stream-type">XML 스트림 유형</a>.</td><td><pre class="language-xml"><code class="lang-xml">&#x3C;log>
    &#x3C;id>1&#x3C;/id>
    &#x3C;data>첫 번째 로그&#x3C;/data>
&#x3C;/log>
&#x3C;log>
    &#x3C;id>2&#x3C;/id>
    &#x3C;data>두 번째 로그&#x3C;/data>
&#x3C;/log>
또는
&#x3C;logs>
    &#x3C;log>
        &#x3C;id>1&#x3C;/id>
        &#x3C;data>첫 번째 로그&#x3C;/data>
    &#x3C;/log>
    &#x3C;log>
        &#x3C;id>2&#x3C;/id>
        &#x3C;data>두 번째 로그&#x3C;/data>
    &#x3C;/log>
&#x3C;/logs>
</code></pre></td></tr></tbody></table>

### JSON 배열 스트림 유형

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

{% hint style="warning" %}
Panther Console에서 로그 집합을 대상으로 스키마를 테스트할 때는 JSON Array의 "enveloped array" 옵션이 지원되지 않습니다.
{% endhint %}

<figure><img src="/files/a1717ece155da98f1ac496adc37b342dc794f143" alt="" width="563"><figcaption></figcaption></figure>

### CloudWatch Logs 스트림 유형

CloudWatch Logs 스트림 유형에서는 선택적으로 [**envelope 필드 보존**](/ko/data-onboarding/data-transports/aws/cloudwatch.md#envelope-field-retention) 상위 수준의 envelope 메타데이터(예: `owner`, `logGroup`, 그리고 `logStream`)를 다음에 보존할 수 있습니다: `p_header` 각 처리된 이벤트의 필드에

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

```json
{
  "owner": "111111111111",
  "logGroup": "services/foo/logs",
  "logStream": "111111111111_CloudTrail/logs_us-east-1",
  "messageType": "DATA_MESSAGE",
  "logEvents": [
    {
      "id": "31953106606966983378809025079804211143289615424298221568",
      "timestamp": 1432826855000,
      "message": "{\"ip\": \"10.0.0.1\", \"username\": \"user-1@example.com\", \"country\": \"France\"}"
    },
    {
      "id": "31953106606966983378809025079804211143289615424298221569",
      "timestamp": 1432826855000,
      "message": "{\"ip\": \"10.0.0.2\", \"username\": \"user-2@example.com\", \"country\": \"France\"}"
    }
  ]
}
```

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

```json
{
  "ip": "10.0.0.1",
  "username": "user-1@example.com",
  "country": "France",
  "p_header": {
    "owner": "111111111111",
    "logGroup": "services/foo/logs",
    "logStream": "111111111111_CloudTrail/logs_us-east-1"
  }
}
```

참조 [봉투 필드 보존](/ko/data-onboarding/data-transports/aws/cloudwatch.md#envelope-field-retention) 이를 활성화하는 방법은 안내를 참조하세요.

### XML 스트림 유형

XML 로그 이벤트를 파싱할 때 Panther는 XML 요소를 JSON 객체로 변환합니다. 큰 틀에서 요소 이름은 키가 되고 텍스트 내용은 값이 됩니다. [XML 로그용 사용자 지정 스키마를 만드는 방법은 여기에서 자세히 알아보세요](/ko/data-onboarding/custom-log-types.md#writing-schemas).

#### **XML 루트 요소 지원**

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

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

1. 스트림 유형으로 다음을 선택하세요 **XML**.
2. 다음을 설정하세요 **XML 이벤트가 루트 요소 안에 포함되어 있나요?** 토글을 **예**.
3. 다음의 **XML 루트 요소** 필드에 루트 요소 이름을 입력합니다(예: `logs`, `events`, `data`).

   <figure><img src="/files/fcf1e48320b3c567ae5eb643a77ad552a2326678" alt="Various form fields are circled: A radio button labeled &#x22;XML,&#x22; a toggle set to &#x22;Yes,&#x22; a text field labeled &#x22;XML Root Element,&#x22; etc."><figcaption></figcaption></figure>

#### **XML 처리 규칙**

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

* 각 최상위 XML 요소는 별도의 이벤트로 처리됩니다. 단, [루트 요소가 지정된 경우는 예외입니다](#xml-root-element-support), 이 경우 Panther는 해당 요소 내부에서 이벤트를 추출합니다.
  * 중첩 요소는 중첩 객체 안에 포함됩니다.
* 요소 이름은 필드 이름이 됩니다.
  * 같은 중첩 수준의 여러 요소가 같은 이름을 가지면, 공통 요소 이름이 키가 되고 요소 내용(즉, 텍스트 내용, 속성, 중첩 필드 등)의 배열이 값인 배열 필드가 생성됩니다.
* 텍스트 내용은 필드 값이 됩니다.
  * 요소에 텍스트 내용만 있고(속성이나 중첩 요소가 없고), 텍스트 내용이 필드 값으로 직접 파싱됩니다.
  * 요소에 1) 텍스트 내용과 2) 하나 이상의 속성 또는 중첩 요소가 모두 있으면, 텍스트 내용은 다음의 값으로 저장됩니다 `text` 키.
  * 요소가 비어 있으면(즉, 텍스트 내용이 없으면), 값이 다음으로 설정됩니다 `null`.
  * 텍스트 내용이 하나 이상의 요소로 나뉘어 있으면 각 부분 사이에 공백을 넣어 연결됩니다.
* 요소 속성(예: `<User role="admin">`)는 텍스트 내용과 함께 공유 중첩 객체에 키/값 쌍으로 추가됩니다.
  * 속성 이름이 중첩 요소 이름(결과 중첩 객체에서 필드 이름이 되며, 속성 이름과 같아집니다)과 충돌하면, 속성 이름에 `_attr` 접미사가 붙습니다. 속성 이름이 `text` 이고 요소에 텍스트 내용이 있으면(이로 인해 중첩된 `text` 키가 생성됨), 속성 필드는 `text_attr`.
  * 해당 `xmlns` 속성(XML 네임스페이스를 선언함)은 자동으로 건너뜁니다.

예시 XML 입력:

```xml
<logs> 
    <log>
        <id>1</id>
        <data>첫 번째 로그</data>
        <user></user>
    </log>
    <log>
        <id>2</id>
        <data level="info">두 번째 로그</data>
    </log>
    <log>
        <id>3</id>
        <data>
            요소 앞의 텍스트
            <source>app</source>
            요소 뒤의 텍스트
        </data>
    </log>
    <log>
        <data>네 번째 로그
            <severity text="sev">높음</severity>
        </data>
    </log>
    <log>
        <data id="123" name="John">
            <name>John1</name>
            <name>John2</name>
        </data>
    </log>
</logs>
```

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

```json
{"id":"1","data":"첫 번째 로그","user":null}
{"id":"2","data":{"text":"두 번째 로그","level":"info"}}
{"id":"3","data":{"text":"요소 앞의 텍스트 요소 뒤의 텍스트","source":"app"}}
{"data":{"text":"네 번째 로그","severity":{"text_attr":"sev","text":"높음"}}}
{"data":{"id":"123","name_attr":"John","name":["John1","John2"]}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.panther.com/ko/data-onboarding/custom-log-types/reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
