Contributing to Elastic Common Schema (ECS)
All information related to ECS is versioned in the elastic/ecs repository. All changes to ECS happen through Pull Requests submitted through Git.
You need these tools to contribute to ECS:
Steps to contribute
Here are the steps for contributing to ECS.
- Set up your git environment.
- Create your own fork of the ECS repo.
- Clone your fork to your machine.
- Create a local branch to hold your changes.
git checkout -b branch-name, where
branch-nameis the name you want to give your local branch
- Do your work.
- Make changes to the
.ymlfiles under the
- Make changes to the
maketo update generated files.
- Note that the README.md file is generated, and should not be edited directly. Source files are in the /docs directory.
- Commit your changes locally.
git commit -a -m "your message"
- Push your changes to your own github.com fork.
git push --set-upstream origin branch-name
- In this command,
originis an alias that references your fork.
- Request feedback and permission to merge your changes.
- Create a Pull Request against the ECS repo.
- (Look for the
Compare & pull requestbutton on your branch in github.com.)
- Next steps
- Wait for reviews on your PR.
- Incorporate review comments and push updates if needed.
- Thank you for your contribution!
Important: Be sure to push changes only to your own fork. Changes must be approved before they are merged into the main repository.
Other ways to contribute
You can contribute even if you are not an experienced Git user. You'll need a github.com account.
- Go to the ECS repo: https://github.com/elastic/ecs
Issuesin the nav bar under the repo name.
New issue. Provide as many details as possible to help reviewers and other contributors understand your proposal.
- Add your text, and click
Submit new issue.
fields.yml files describe the Elastic Common Schema in a structured way. We can use these files to generate an Elasticsearch index template, a Kibana index pattern, or documentation output.
The file structure is documented in schemas/README.md.
It looks similar to this:
- name: agent title: Agent group: 2 description: > The agent fields contain the data about the software entity, if any, that collects, detects, or observes events on a host, or takes measurements on a host. Examples include Beats. Agents may also run on observers. ECS agent.* fields shall be populated with details of the agent running on the host or observer where the event happened or the measurement was taken. footnote: > Examples: In the case of Beats for logs, the agent.name is filebeat. For APM, it is the agent running in the app/service. The agent information does not change if data is sent through queuing systems like Kafka, Redis, or processing systems such as Logstash or APM Server. type: group fields: - name: version level: core type: keyword description: > Version of the agent. example: 6.0.0-rc2
Each prefix has its own file. The fields for each prefix are stored in the file.
description describe the prefix.
footnote adds more information following the field table.
level is for sorting in the documentation output.
fields section, the
name of the field is the first entry.
type is the Elasticsearch field type.
description adds details about the field.
example adds an sample value.
Guidelines for implementing ECS
Look at our Guidelines and Best Practices on the ECS documentation website.