IMPORTANT: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
current release documentation.
Naming Conventions
editNaming Conventions
editWhen creating events, use the following conventions for field names and abbreviations.
Field Names
editUse the following naming conventions for field names:
- All fields must be lower case.
- Use snake case (underscores) for combining words.
-
Group related fields into subdocuments by using dot (.) notation. Groups typically have common prefixes. For example, if you have fields called
CPULoad
andCPUSystem
in a service, you would convert them intocpu.load
andcpu.system
in the event. -
Avoid repeating the namespace in field names. If a word or abbreviation appears in the namespace, it’s not needed in the field name. For example, instead of
cpu.cpu_load
, usecpu.load
. - Use units suffix when the metric matches one of the known units.
- Use standardised names and avoid using abbreviations that aren’t commonly known.
-
Organise the documents from general to specific to allow for namespacing. The type, such as
.pct
, should always be last. For example,system.core.user.pct
. -
If two fields are the same, but with different units, remove the less granular one. For example, include
timeout.sec
, but don’t includetimeout.min
. If a less granular value is required, you can calculate it later. -
If a field name matches the namespace used for nested fields, add
.value
to the field name. For example, instead of:workers workers.busy workers.idle
Use:
workers.value workers.busy workers.idle
- Do not use dots (.) in individual field names. Dots are reserved for grouping related fields into subdocuments.
-
Use singular and plural names properly to reflect the field content. For example, use
requests_per_sec
rather thanrequest_per_sec
.
Units
editThese are well-known suffixes to represent units of stored values, use them as a dotted suffix when
possible. For example system.memory.used.bytes
or system.diskio.read.count
:
Suffix | Units |
---|---|
count |
item count |
pct |
percentage |
day |
days |
sec |
seconds |
ms |
millisecond |
us |
microseconds |
ns |
nanoseconds |
bytes |
bytes |
mb |
megabytes |
Standardised Names
editHere is a list of standardised names and units that are used across all Beats:
Use… | Instead of… |
---|---|
avg |
average |
connection |
conn |
max |
maximum |
min |
minimum |
request |
req |
msg |
message |