llm-wiki/raw/official-docs/log-ecs-schema-elastic-official.md

---
title: Elastic Common Schema (ECS) — Field Reference
source_type: official-doc
url: https://www.elastic.co/guide/en/ecs/current/ecs-reference.html
archive_url:
status: raw
confidence: high
tags: [ca-log-management, ecs-schema, structured-logging, observability, official-doc]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-log-management-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Elastic Common Schema (ECS) — Field Reference

> Layer: `raw/official-docs/` — Elastic ECS 공식 reference 의 핵심 field 정의 verbatim 발췌.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-log-management-contract]] | ca-tmpl 자체 JSON log schema 의 대안 평가 — ECS 표준 field 와의 매핑 가능성 확인 |
| [[raw/project-notes/ca-skeleton-operational-contract]] | Group G-A (Log management) 대안 2 의 baseline 자료 |

## 컨텍스트

ca-tmpl이 채택한 자체 JSON log schema(`timestamp`, `level`, `traceId`, `requestId`, `correlationId`, `operation`, `error.code`, `error.category`, `error.retryable`, `dependency.name`)의 대안으로, 업계에서 가장 널리 쓰이는 **표준 schema**인 ECS와 직접 비교.

## 출처 / Source

- 원본 URL: https://www.elastic.co/guide/en/ecs/current/ecs-reference.html
- 보조 URL (field reference 페이지): https://www.elastic.co/guide/en/ecs/current/ecs-base.html , https://www.elastic.co/guide/en/ecs/current/ecs-tracing.html , https://www.elastic.co/guide/en/ecs/current/ecs-event.html
- 아카이브 URL: (미수집)
- 저자 / 조직: Elastic
- 발행일: rolling docs (current = 9.x 계열)
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§ECS Reference — intro] "The Elastic Common Schema (ECS) is an open source specification, developed with support of the Elastic user community. ECS defines a common set of fields to be used when storing event data in Elasticsearch, such as logs and metrics."

> [§Base Fields — @timestamp] "Date/time when the event originated. This is the date/time extracted from the event, typically representing when the event was generated by the source."

> [§Tracing Fields — trace.id] "Unique identifier of the trace. A trace groups multiple events like transactions that belong together."

> [§Tracing Fields — span.id] "Unique identifier of the span within the scope of its trace. A span represents an operation within a transaction, such as a request to another service, or a database query."

> [§Event Fields — event.category] "This is one of four ECS Categorization Fields, and indicates the second level in the ECS category hierarchy." Allowed Values: `api, authentication, configuration, database, driver, email, file, host, iam, intrusion_detection, library, malware, network, package, process, registry, session, threat, vulnerability, web`

> [§Event Fields — event.outcome] "simply denotes whether the event represents a success or a failure from the perspective of the entity that produced the event." Allowed Values: `failure, success, unknown`

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| LOG-ECS-C1 | ECS는 Elasticsearch에 event data(logs/metrics)를 저장할 때 사용하는 **open source 공통 field 사양** | [§ECS Reference — intro] "The Elastic Common Schema (ECS) is an open source specification ... ECS defines a common set of fields to be used when storing event data in Elasticsearch, such as logs and metrics." | `official-vendor-doc` | Elasticsearch / Elastic stack 에 event data 적재 | ECS 가 비-Elastic sink (Loki, Datadog 등)의 공식 표준이라는 뜻은 아님 |
| LOG-ECS-C2 | ECS `@timestamp` 는 event 가 **source 에서 생성된 시점**의 date/time 으로 정의됨 (수신 시점 아님) | [§Base Fields — @timestamp] "Date/time when the event originated. This is the date/time extracted from the event, typically representing when the event was generated by the source." | `official-vendor-doc` | ECS-compliant event field 작성 | ingest pipeline 이 항상 source timestamp 를 보존한다는 뜻은 아님 — 누락 시 수신 시 채워질 수 있음 |
| LOG-ECS-C3 | ECS `trace.id` 는 "trace 의 고유 식별자" 로 정의되며 trace 는 함께 묶이는 transaction 같은 여러 event 의 group | [§Tracing Fields — trace.id] "Unique identifier of the trace. A trace groups multiple events like transactions that belong together." | `official-vendor-doc` | distributed tracing 과 log 의 상관관계 | W3C Trace Context 와 정확히 일치하는 wire format 이라는 뜻은 본 인용에 명시 없음 |
| LOG-ECS-C4 | ECS `span.id` 는 trace 범위 내에서 span 의 고유 식별자. span 은 transaction 안의 단일 operation (e.g., 외부 서비스 호출, DB 쿼리) | [§Tracing Fields — span.id] "Unique identifier of the span within the scope of its trace. A span represents an operation within a transaction, such as a request to another service, or a database query." | `official-vendor-doc` | ECS tracing field set | span hierarchy / parent_span_id 의 정확한 모델은 본 인용 범위 밖 |
| LOG-ECS-C5 | ECS `event.category` 는 categorization hierarchy 의 2번째 level 로 정의되고 array 타입. 허용 값에 `authentication, database, network, web` 등 포함 | [§Event Fields — event.category] "This is one of four ECS Categorization Fields, and indicates the second level in the ECS category hierarchy." + Allowed Values: `api, authentication, configuration, database, driver, email, file, host, iam, intrusion_detection, library, malware, network, package, process, registry, session, threat, vulnerability, web` | `official-vendor-doc` | event 분류 및 Kibana SIEM 카테고리 매핑 | ca-tmpl 의 `error.category` (e.g., retryable/non-retryable) 가 ECS event.category 와 매핑 가능하다는 뜻은 아님 — 다른 semantics |
| LOG-ECS-C6 | ECS `event.outcome` 은 categorization hierarchy 최하위. 허용 값은 `failure, success, unknown` 3가지 | [§Event Fields — event.outcome] "simply denotes whether the event represents a success or a failure from the perspective of the entity that produced the event." + Allowed Values: `failure, success, unknown` | `official-vendor-doc` | event 결과 분류 | partial-success 같은 4번째 상태가 표준에 포함된다는 뜻은 아님 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `LOG-ECS-C1`: ECS 가 Elastic 공식 open source spec 임
  - `LOG-ECS-C2`~`C6`: 특정 ECS field (`@timestamp`, `trace.id`, `span.id`, `event.category`, `event.outcome`) 의 공식 정의 및 일부 허용 값
- **이 자료가 증명하지 않는 것**:
  - OpenTelemetry log spec 과의 정확한 매핑 관계 (별도 OTel doc 필요)
  - ECS 가 ca-tmpl 의 `error.retryable`, `correlationId`, `requestId` 와 의미적으로 매핑 가능한지 (ECS 는 이 custom field 들을 표준화하지 않음)
  - ECS schema 채택 시 Kibana 자동 매핑이 모든 dashboard 에서 동작하는지
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 logback encoder 가 ECS `@timestamp` 형식 (`2016-05-23T08:05:34.853Z` ISO 8601) 을 emit 하는지 검증
  - ca-tmpl 의 `traceId` (camelCase) 를 ECS `trace.id` (dot notation) 로 rename 했을 때 기존 alert/dashboard 영향
  - Elastic stack 외 sink (예: Loki, Datadog) 에서 ECS field 가 first-class 로 indexing 되는지

## 메모 / Notes (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

- **field naming convention:** dot notation (`event.category`, `trace.id`, `service.name`). nested object. ca-tmpl JSON log는 일부 flat (`traceId`) + 일부 dot (`error.code`, `dependency.name`)으로 혼합.
- **공통 필드 (ca-tmpl 매핑):**
  - ECS `@timestamp` ↔ ca-tmpl `timestamp` (이름만 다름).
  - ECS `log.level` ↔ ca-tmpl `level`.
  - ECS `service.name` ↔ ca-tmpl `app`.
  - ECS `trace.id` ↔ ca-tmpl `traceId` (case 다름).
  - ECS `span.id` ↔ ca-tmpl `spanId` (tracing branch).
  - ECS `error.code` / `error.message` ↔ ca-tmpl `error.code`.
  - ECS `event.action` ↔ ca-tmpl `operation`.
- **차이:** ECS는 `error.category`, `error.retryable`, `correlationId`, `requestId`를 표준 field로 정의하지 않음 (custom field로 추가 가능). ECS는 `event.outcome=success|failure|unknown` 사용.
- **장점:** 업계 표준 → Kibana/Elastic Agent/Beats가 자동 매핑. tool vendor lock-in 적음. OpenTelemetry log spec도 ECS와 일부 정렬됨.
- **단점:** field 수 매우 많음(수백 개). ca-tmpl처럼 "필수 8-10개"의 minimal core를 강제하기 어렵고, 도입 시 schema explosion 위험. naming 강제로 application 내부 도메인 용어와 충돌 가능.
- **ca-tmpl과의 차이:**
  - ca-tmpl은 자체 schema. ECS와 매핑 가능하지만 100% 호환은 아님.
  - ca-tmpl 채택 이유 추정: 한정된 field set + business-specific (`retryable`, `correlationId`)을 명시적으로 강제하기 위함.
  - 만약 Elastic stack을 prod sink로 도입하면, ECS mapping table을 logback encoder/Filebeat ingest pipeline에서 변환 필요.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/log-otel-log-data-model-spec]] (OTel log signal spec, ECS 와 일부 정렬)
- 같은 주제 company-tech-blog: (없음 — 본 alternative group 의 ECS 슬롯)
- 적용 branch / contract:
  - [[raw/branch-notes/feature-log-management-contract]]
  - canonical contract: [[raw/project-notes/ca-skeleton-operational-contract]] §8 Structured Log Contract
- 대안 그룹: Group G-A — Log management (대안 2 — ECS schema vs ca-tmpl 자체 schema)
- 인용하는 wiki: (미작성)