Elastic Common Schema
Elastic Common Schema (ECS) defines common fields for logs, metrics, security telemetry, and observability data so events from different sources can be queried and correlated consistently.
This skill is generated from the latest supported ECS release in this repository: v9.5.0 / 9.5.0.
Use the YAML files as the authoritative reference for exact field names, fieldsets, types, levels, allowed values, normalization hints, reuse metadata, and OpenTelemetry relations.
Use the Markdown docs only for conceptual guidance, mapping examples, and implementation conventions.
If a field, fieldset, allowed value, or relation is not present in the YAML data, say that it is not documented here.
Data files
- Use fields.yaml to find a dotted ECS field and then load the referenced
fields/<field>.yaml file.
- Use fieldsets.yaml to choose a fieldset and then load the referenced
fieldsets/<fieldset>.yaml file.
- Use categorization.yaml for
event.kind, event.category, event.type, event.outcome, allowed values, and expected category/type combinations.
- Use otel.yaml as the compact ECS-keyed crosswalk for OpenTelemetry relations.
- Use source.md for release provenance, source artifacts, copied docs, referenced upstream docs, and counts.
Complementary docs
- Start with Implementation patterns, Design principles, and Conventions for general modeling questions.
- Use categorization.yaml and Using categorization fields when assigning
event.* categorization values.
- Use Mapping network events for
source/destination versus client/server decisions.
- Use Custom fields when ECS has no suitable field.
- Use ECS and OpenTelemetry together with otel.yaml for OTel alignment questions.
- Use focused usage docs for cloud, service, threat, and user mapping scenarios.
Mapping rules
- Populate required fields first:
@timestamp and ecs.version.
- Prefer documented ECS fields over custom fields when the field semantics match.
- Preserve source-specific detail in custom fields when ECS has no matching field; use
labels for small keyword metadata when appropriate.
- For categorization, use only allowed values from categorization.yaml; leave categorization fields empty when no allowed value fits.
- Treat
event.category and event.type as arrays and use multiple values only when the event reasonably belongs to multiple categories or types.
- Use fieldset reuse metadata in fieldsets.yaml to distinguish role-specific locations such as
user.target, process.parent, cloud.origin, and service.target.
- For network events, use
source/destination for packet or flow direction and also populate client/server when the endpoint roles are known.
- Copy pivot values into
related.* when the docs or field semantics call for cross-field searching.
Question routing
- What does field X mean? Start with fields.yaml, then load the selected field YAML.
- What fields exist under fieldset X? Start with fieldsets.yaml, then load the selected fieldset YAML.
- Which
event.category or event.type should I use? Start with categorization.yaml, then read Using categorization fields for examples.
- How should I map a network event? Read Mapping network events, then inspect the relevant fieldsets.
- How do I model users, cloud resources, services, or threat indicators? Read the matching usage doc under
docs/usage/, then inspect the relevant fieldset YAML.
- How does ECS relate to OpenTelemetry? Use otel.yaml for the compact field crosswalk and ECS and OpenTelemetry for conceptual guidance.
- What if ECS has no matching field? Read Custom fields.
- What raw upstream source backs this skill? Use source.md.
1---2name: tenzir-ecs3description: Answer questions and produce mappings for Elastic Common Schema (ECS): Elastic/Elasticsearch fields, fieldsets, data types, allowed values, categorization (`event.kind`, `event.category`, `event.type`, `event.outcome`), custom fields, field reuse, normalization, and OpenTelemetry/OTel/OTLP/SemConv alignment. Use when mapping logs, security telemetry, SIEM detections, network flows, IAM/user activity, cloud/service context, threat intel, or observability metrics/traces into ECS, Elastic Security, Elastic Observability, or Elasticsearch mappings/templates.4---56# Elastic Common Schema78Elastic Common Schema (ECS) defines common fields for logs, metrics, security telemetry, and observability data so events from different sources can be queried and correlated consistently.910This skill is generated from the latest supported ECS release in this repository: `v9.5.0` / `9.5.0`.11Use the YAML files as the authoritative reference for exact field names, fieldsets, types, levels, allowed values, normalization hints, reuse metadata, and OpenTelemetry relations.12Use the Markdown docs only for conceptual guidance, mapping examples, and implementation conventions.13If a field, fieldset, allowed value, or relation is not present in the YAML data, say that it is not documented here.1415## Data files1617- Use [fields.yaml](fields.yaml) to find a dotted ECS field and then load the referenced `fields/<field>.yaml` file.18- Use [fieldsets.yaml](fieldsets.yaml) to choose a fieldset and then load the referenced `fieldsets/<fieldset>.yaml` file.19- Use [categorization.yaml](categorization.yaml) for `event.kind`, `event.category`, `event.type`, `event.outcome`, allowed values, and expected category/type combinations.20- Use [otel.yaml](otel.yaml) as the compact ECS-keyed crosswalk for OpenTelemetry relations.21- Use [source.md](source.md) for release provenance, source artifacts, copied docs, referenced upstream docs, and counts.2223## Complementary docs2425- Start with [Implementation patterns](docs/implementation-patterns.md), [Design principles](docs/design-principles.md), and [Conventions](docs/conventions.md) for general modeling questions.26- Use [categorization.yaml](categorization.yaml) and [Using categorization fields](docs/categorization-usage.md) when assigning `event.*` categorization values.27- Use [Mapping network events](docs/mapping-network-events.md) for `source`/`destination` versus `client`/`server` decisions.28- Use [Custom fields](docs/custom-fields.md) when ECS has no suitable field.29- Use [ECS and OpenTelemetry](docs/opentelemetry.md) together with [otel.yaml](otel.yaml) for OTel alignment questions.30- Use focused usage docs for [cloud](docs/usage/cloud.md), [service](docs/usage/service.md), [threat](docs/usage/threat.md), and [user](docs/usage/user.md) mapping scenarios.3132## Mapping rules3334- Populate required fields first: `@timestamp` and `ecs.version`.35- Prefer documented ECS fields over custom fields when the field semantics match.36- Preserve source-specific detail in custom fields when ECS has no matching field; use `labels` for small keyword metadata when appropriate.37- For categorization, use only allowed values from [categorization.yaml](categorization.yaml); leave categorization fields empty when no allowed value fits.38- Treat `event.category` and `event.type` as arrays and use multiple values only when the event reasonably belongs to multiple categories or types.39- Use fieldset reuse metadata in [fieldsets.yaml](fieldsets.yaml) to distinguish role-specific locations such as `user.target`, `process.parent`, `cloud.origin`, and `service.target`.40- For network events, use `source`/`destination` for packet or flow direction and also populate `client`/`server` when the endpoint roles are known.41- Copy pivot values into `related.*` when the docs or field semantics call for cross-field searching.4243## Question routing4445- **What does field X mean?** Start with [fields.yaml](fields.yaml), then load the selected field YAML.46- **What fields exist under fieldset X?** Start with [fieldsets.yaml](fieldsets.yaml), then load the selected fieldset YAML.47- **Which `event.category` or `event.type` should I use?** Start with [categorization.yaml](categorization.yaml), then read [Using categorization fields](docs/categorization-usage.md) for examples.48- **How should I map a network event?** Read [Mapping network events](docs/mapping-network-events.md), then inspect the relevant fieldsets.49- **How do I model users, cloud resources, services, or threat indicators?** Read the matching usage doc under `docs/usage/`, then inspect the relevant fieldset YAML.50- **How does ECS relate to OpenTelemetry?** Use [otel.yaml](otel.yaml) for the compact field crosswalk and [ECS and OpenTelemetry](docs/opentelemetry.md) for conceptual guidance.51- **What if ECS has no matching field?** Read [Custom fields](docs/custom-fields.md).52- **What raw upstream source backs this skill?** Use [source.md](source.md).
tenzir