diff --git a/.gitignore b/.gitignore index a3cabe1d6a..c1a7608dcd 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,6 @@ build # experimental exclusions experimental/generated/elasticsearch/6 experimental/generated/docs + +# patches are vital to cross-barch testing but don't want in GitHub +*.patch diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index 23c0ecabd4..be936302d8 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -18,6 +18,8 @@ Thanks, you're awesome :-) --> #### Improvements +* Fix ecs GitHub repo link source branch #1393 + #### Deprecated ### Tooling and Artifact Changes diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 9e5dc1c837..81a633951f 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -5,7 +5,7 @@ include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[] include::{asciidoc-dir}/../../shared/attributes.asciidoc[] -:ecs_github_repo_link: https://github.com/elastic/ecs/blob/master +:ecs_github_repo_link: https://github.com/elastic/ecs/blob/{source_branch} [[ecs-reference]] == Overview @@ -66,4 +66,4 @@ include::using.asciidoc[] include::fields.asciidoc[] include::field-values.asciidoc[] include::migrating.asciidoc[] -include::additional.asciidoc[] +include::additional.asciidoc[] \ No newline at end of file diff --git a/scripts/generator.py b/scripts/generator.py index 5a1dc24724..4b6d738503 100644 --- a/scripts/generator.py +++ b/scripts/generator.py @@ -21,8 +21,8 @@ def main(): args = argument_parser() - ecs_version = read_version(args.ref) - print('Running generator. ECS version ' + ecs_version) + ecs_generated_version = read_version(args.ref) + print('Running generator. ECS version ' + ecs_generated_version) # default location to save files out_dir = 'generated' @@ -43,7 +43,8 @@ def main(): # Detect usage of experimental changes to tweak artifact version label if args.include and loader.EXPERIMENTAL_SCHEMA_DIR in args.include: - ecs_version += "+exp" + ecs_generated_version += "+exp" + print('Experimental ECS version ' + ecs_generated_version) fields = loader.load_schemas(ref=args.ref, included_files=args.include) if args.oss: @@ -56,14 +57,15 @@ def main(): if args.intermediate_only: exit() - csv_generator.generate(flat, ecs_version, out_dir) - es_template.generate(nested, ecs_version, out_dir, args.mapping_settings) - es_template.generate_legacy(flat, ecs_version, out_dir, args.template_settings, args.mapping_settings) - beats.generate(nested, ecs_version, out_dir) + csv_generator.generate(flat, ecs_generated_version, out_dir) + es_template.generate(nested, ecs_generated_version, out_dir, args.mapping_settings) + es_template.generate_legacy(flat, ecs_generated_version, out_dir, args.template_settings, args.mapping_settings) + beats.generate(nested, ecs_generated_version, out_dir) if args.include or args.subset: exit() - asciidoc_fields.generate(nested, ecs_version, docs_dir) + ecs_helpers.make_dirs(docs_dir) + asciidoc_fields.generate(nested, ecs_generated_version, docs_dir) def argument_parser(): diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py index 04fd1fcacf..840a0ad262 100644 --- a/scripts/generators/asciidoc_fields.py +++ b/scripts/generators/asciidoc_fields.py @@ -6,8 +6,9 @@ from generators import ecs_helpers -def generate(nested, ecs_version, out_dir): - save_asciidoc(path.join(out_dir, 'fields.asciidoc'), page_field_index(nested, ecs_version)) +def generate(nested, ecs_generated_version, out_dir): + save_asciidoc(path.join(out_dir, 'index.asciidoc'), page_index(ecs_generated_version)) + save_asciidoc(path.join(out_dir, 'fields.asciidoc'), page_field_index(nested, ecs_generated_version)) save_asciidoc(path.join(out_dir, 'field-details.asciidoc'), page_field_details(nested)) save_asciidoc(path.join(out_dir, 'field-values.asciidoc'), page_field_values(nested)) @@ -125,13 +126,21 @@ def save_asciidoc(f, text): # Rendering schemas +# Index + + +@templated('index.j2') +def page_index(ecs_generated_version): + return dict(ecs_generated_version=ecs_generated_version) + + # Field Index @templated('fields.j2') -def page_field_index(nested, ecs_version): +def page_field_index(nested, ecs_generated_version): fieldsets = ecs_helpers.dict_sorted_by_keys(nested, ['group', 'name']) - return dict(ecs_version=ecs_version, fieldsets=fieldsets) + return dict(ecs_generated_version=ecs_generated_version, fieldsets=fieldsets) # Field Details Page diff --git a/scripts/templates/fields.j2 b/scripts/templates/fields.j2 index 72dad35f60..c10af92506 100644 --- a/scripts/templates/fields.j2 +++ b/scripts/templates/fields.j2 @@ -2,7 +2,7 @@ [[ecs-field-reference]] == {ecs} Field Reference -This is the documentation of ECS version {{ ecs_version }}. +This is the documentation of ECS version {{ ecs_generated_version }}. ECS defines multiple groups of related fields. They are called "field sets". The <> field set is the only one whose fields are defined diff --git a/scripts/templates/index.j2 b/scripts/templates/index.j2 new file mode 100644 index 0000000000..a354b5c325 --- /dev/null +++ b/scripts/templates/index.j2 @@ -0,0 +1,69 @@ += Elastic Common Schema (ECS) Reference +:doctype: book +:ecs: ECS + +include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[] +include::{asciidoc-dir}/../../shared/attributes.asciidoc[] + +:ecs_github_repo_link: https://github.com/elastic/ecs/blob/{source_branch} + +[[ecs-reference]] +== Overview + +This is the documentation of ECS version {{ ecs_generated_version }}. + +[float] +=== What is ECS? + +The Elastic Common Schema (ECS) is an open source specification, +developed with support from 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. + +ECS specifies field names and Elasticsearch datatypes for each field, +and provides descriptions and example usage. +ECS also groups fields into ECS levels, which are used to signal how much a field +is expected to be present. You can learn more about ECS levels in <>. +Finally, ECS also provides a set of naming guidelines for adding custom fields. + +The goal of ECS is to enable and encourage users of Elasticsearch to normalize their event data, +so that they can better analyze, visualize, and correlate the data represented in their events. +ECS has been scoped to accommodate a wide variety of events, spanning: + +- *Event sources*: whether the source of your event is an Elastic product, + a third- party product, or a custom application built by your organization. +- *Ingestion architectures*: whether the ingestion path for your events includes Beats processors, + Logstash, Elasticsearch ingest node, all of the above, or none of the above. +- *Consumers*: whether consumed by API, Kibana queries, dashboards, apps, or other means. + +[float] +=== New to ECS? + +If you're new to ECS and looking for an introduction to its benefits and examples of the +core concepts, <> is a great place to start. + +[float] +=== My events don't map with ECS + +ECS is a permissive schema. If your events have additional data that cannot be +mapped to ECS, you can simply add them to your events, using custom field names. + + +[float] +=== Maturity + +ECS improvements are released following https://semver.org/[Semantic Versioning]. +Major ECS releases are planned to be aligned with major Elastic Stack releases. + +Any feedback on the general structure, missing fields, or existing fields is appreciated. +For contributions please read the +https://github.com/elastic/ecs/blob/master/CONTRIBUTING.md[Contribution +Guidelines]. + + + +include::using.asciidoc[] +include::fields.asciidoc[] +include::field-values.asciidoc[] +include::migrating.asciidoc[] +include::additional.asciidoc[]