Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

9.8 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

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에서 변환 필요.

같은 주제 다른 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: (미작성)

9.8 KiB Raw Permalink Blame History