Skip to content

Commit 6eaf0cf

Browse files
richmrichm
committed
several documentation updates
This cleans up the formatting of some of the `description` fields so that the asciidoc version preserves the formatting. There are several other minor formatting changes. Most of the previously undocumented fields now have at least some minimal documentation. This simplifies the code that ensures utf-8 correctness. This should work with both python2 and python3.
1 parent 4d3bb80 commit 6eaf0cf

File tree

9 files changed

+144
-120
lines changed

9 files changed

+144
-120
lines changed

‎namespaces/_default_.yml‎

Lines changed: 22 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,16 @@ field_defaults:
88
_default_:
99
type: group
1010
name: "Default"
11-
description: >
12-
Contains common fields and generic pattern-matched field descriptions; this
13-
is what populates the actual mappings of _default_ in the template's mapping
14-
section.
11+
description: |
12+
The top level fields are common to every application, and may be present in every record.
13+
For the Elasticsearch template, this is what populates the actual mappings
14+
of _default_ in the template's mapping section.
1515
fields:
1616
- name: "@timestamp"
1717
type: date
1818
format: yyyy-MM-dd HH:mm:ss,SSSZ||yyyy-MM-dd'T'HH:mm:ss.SSSSSSZ||yyyy-MM-dd'T'HH:mm:ssZ||dateOptionalTime
1919
example: 2015-01-24T14:06:05.071Z
20-
description: >
20+
description: |
2121
UTC value marking when the log payload was created, or when log payload was first collected if the creation time is not known;
2222
this is the log processing pipeline’s “best effort” determination of when the log payload was generated
2323
FYI: the “@” prefix convention to note a field as being reserved for a particular use; in this case, most tools by default look for “@timestamp” with ElasticSearch
@@ -39,8 +39,10 @@ _default_:
3939
- name: hostname
4040
type: string
4141
description: >
42-
FQDN of the entity generating the original payload
43-
This field is a best effort attempt to derive this context; sometimes the entity generating it knows it; other times that entity has a restricted namespace itself, and the collector or normalizer knows that
42+
FQDN of the entity generating the original payload. This field is a
43+
best effort attempt to derive this context; sometimes the entity
44+
generating it knows it; other times that entity has a restricted
45+
namespace itself, and the collector or normalizer knows that.
4446
4547
- name: ipaddr4
4648
type: ip
@@ -61,19 +63,21 @@ _default_:
6163
- name: level
6264
type: string
6365
example: info
64-
description: >
66+
description: |
6567
Logging level as provided by: rsyslog(severitytext property), python's
6668
logging module, etc.
67-
Possible values are as listed here: http://sourceware.org/git/?p=glibc.git;a=blob;f=misc/sys/syslog.h;h=ee01478c4b19a954426a96448577c5a76e6647c0;hb=HEAD#l74 plus trace
68-
That is: alert crit debug emerg err info notice trace warning
69+
Possible values are as listed here: http://sourceware.org/git/?p=glibc.git;a=blob;f=misc/sys/syslog.h;h=ee01478c4b19a954426a96448577c5a76e6647c0;hb=HEAD#l74 plus `trace` and `unknown`
70+
That is: alert crit debug emerg err info notice trace unknown warning
6971
Note that `trace` isn't in the syslog.h list but many applications use it
70-
`trace` should be considered the highest (most verbose) level, higher than `debug`
72+
`unknown` is only used when the logging system gets a value it doesn't understand
73+
`unknown` is the highest level
74+
`trace` should be considered as higher (more verbose) than `debug`
7175
`error` should be converted to `err`
7276
`panic` should be converted to `emerg`
7377
`warn` should be converted to `warning`
7478
Numeric values from syslog/journal PRIORITY can usually be mapped using the priority values as listed here:
7579
http://sourceware.org/git/?p=glibc.git;a=blob;f=misc/sys/syslog.h;h=ee01478c4b19a954426a96448577c5a76e6647c0;hb=HEAD#l51
76-
That is, 0 -> emerg, 1 -> alert, ..., 7 -> debug
80+
That is, 0 -> emerg, 1 -> alert, ..., 7 -> debug, 8 -> trace, 9 -> unknown
7781
Log levels/priorities from other logging systems should be mapped to the nearest match
7882
For example, from python logging: https://docs.python.org/2.7/library/logging.html#logging-levels
7983
CRITICAL -> crit, ERROR -> err, ...., DEBUG -> debug
@@ -140,8 +144,9 @@ _default_:
140144
example: my-cool-project-in-lab04
141145
doc_values: false
142146
index: not_analyzed
143-
description: >
144-
format [a-zA-Z][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]
147+
description: |
148+
format: [a-zA-Z][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]
149+
145150
Associate this record with the namespace with this name.
146151
This value will not be stored. It is only used to associate the
147152
record with the appropriate namespace for access control and
@@ -155,8 +160,9 @@ _default_:
155160
- name: namespace_uuid
156161
type: string
157162
example: 82f13a8e-882a-4344-b103-f0a6f30fd218
158-
description: >
159-
format [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}
163+
description: |
164+
format: [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}
165+
160166
The uuid associated with the namespace_name.
161167
This value will not be stored. It is only used to associate the
162168
record with the appropriate namespace for access control and

‎namespaces/aushape.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@ namespace:
33
name: aushape
44
type: group
55
description: >
6-
Audit events converted with aushape
7-
For more information please see
6+
Audit events converted with aushape. For more information please see
87
https://github.com/Scribery/aushape
98
fields:
109
- name: serial

‎namespaces/kubernetes.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,5 +48,15 @@ namespace:
4848
description: >
4949
Kubernetes node name
5050
51+
- name: master_url
52+
type: string
53+
description: >
54+
Kubernetes Master URL
55+
56+
- name: annotations
57+
type: group
58+
description: >
59+
Annotations associated with the OpenShift object
60+
5161
doc_sections:
5262
- ["pod_log", "Openshift logging metadata"]

‎namespaces/systemd.yml‎

Lines changed: 41 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,12 @@ namespace:
33
name: systemd
44
type: group
55
description: >
6-
Contains common fields specific to systemd journal.
7-
For more information please see
6+
Contains common fields specific to systemd journal. For more information
7+
please see
88
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html
9+
Applications may write their own fields to the journal. These will be
10+
available under the `systemd.u` namespace. `RESULT` and `UNIT` are two
11+
such fields.
912
fields:
1013
- name: k
1114
type: group
@@ -15,182 +18,183 @@ namespace:
1518
- name: KERNEL_DEVICE
1619
type: string
1720
description: >
18-
TODO
21+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_KERNEL_DEVICE=
1922
2023
- name: KERNEL_SUBSYSTEM
2124
type: string
2225
description: >
23-
TODO
26+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_KERNEL_SUBSYSTEM=
2427
2528
- name: UDEV_DEVLINK
2629
type: string
2730
description: >
28-
TODO
31+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_UDEV_DEVLINK=
2932
3033
- name: UDEV_DEVNODE
3134
type: string
3235
description: >
33-
TODO
36+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_UDEV_DEVNODE=
3437
3538
- name: UDEV_SYSNAME
3639
type: string
3740
description: >
38-
TODO
41+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_UDEV_SYSNAME=
3942
4043
- name: t
4144
type: group
4245
description: >
43-
TODO.
46+
trusted journal fields, fields that are implicitly added by the journal and cannot be altered by client code.
4447
fields:
4548
- name: AUDIT_LOGINUID
4649
type: string
4750
description: >
48-
TODO
51+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_AUDIT_SESSION=
4952
5053
- name: BOOT_ID
5154
type: string
5255
description: >
53-
TODO
56+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_BOOT_ID=
5457
5558
- name: AUDIT_SESSION
5659
type: string
5760
description: >
58-
TODO
61+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_AUDIT_SESSION=
5962
6063
- name: CAP_EFFECTIVE
6164
type: string
6265
description: >
63-
TODO
66+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_CAP_EFFECTIVE=
6467
6568
- name: CMDLINE
6669
type: string
6770
description: >
68-
TODO
71+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_COMM=
6972
norms:
7073
enabled: false
7174

7275
- name: COMM
7376
type: string
7477
description: >
75-
TODO
78+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_COMM=
7679
7780
- name: EXE
7881
type: string
7982
description: >
80-
TODO
83+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_COMM=
8184
norms:
8285
enabled: false
8386

8487
- name: GID
8588
type: string
8689
description: >
87-
TODO
90+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_PID=
8891
8992
- name: HOSTNAME
9093
type: string
9194
description: >
92-
TODO
95+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_HOSTNAME=
9396
9497
- name: MACHINE_ID
9598
type: string
9699
description: >
97-
TODO
100+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_MACHINE_ID=
98101
99102
- name: PID
100103
type: string
101104
description: >
102-
TODO
105+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_PID=
103106
104107
- name: SELINUX_CONTEXT
105108
type: string
106109
description: >
107-
TODO
110+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SELINUX_CONTEXT=
108111
109112
- name: SOURCE_REALTIME_TIMESTAMP
110113
type: string
111114
description: >
112-
TODO
115+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SOURCE_REALTIME_TIMESTAMP=
116+
This is converted to RFC 3339 NS format
113117
114118
- name: SYSTEMD_CGROUP
115119
type: string
116120
description: >
117-
TODO
121+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=
118122
119123
- name: SYSTEMD_OWNER_UID
120124
type: string
121125
description: >
122-
TODO
126+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=
123127
124128
- name: SYSTEMD_SESSION
125129
type: string
126130
description: >
127-
TODO
131+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=
128132
129133
- name: SYSTEMD_SLICE
130134
type: string
131135
description: >
132-
TODO
136+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=
133137
134138
- name: SYSTEMD_UNIT
135139
type: string
136140
description: >
137-
TODO
141+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=
138142
139143
- name: SYSTEMD_USER_UNIT
140144
type: string
141145
description: >
142-
TODO
146+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=
143147
144148
- name: TRANSPORT
145149
type: string
146150
description: >
147-
TODO
151+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_TRANSPORT=
148152
149153
- name: UID
150154
type: string
151155
description: >
152-
TODO
156+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_PID=
153157
154158
- name: u
155159
type: group
156160
description: >
157-
TODO.
161+
fields that are directly passed from clients and stored in the journal.
158162
fields:
159163
- name: CODE_FILE
160164
type: string
161165
norms:
162166
enabled: false
163167
description: >
164-
TODO
168+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=
165169
166170
- name: CODE_FUNCTION
167171
type: string
168172
description: >
169-
TODO
173+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=
170174
171175
- name: CODE_LINE
172176
type: string
173177
description: >
174-
TODO
178+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=
175179
176180
- name: ERRNO
177181
type: string
178182
description: >
179-
TODO
183+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=
180184
181185
- name: MESSAGE_ID
182186
type: string
183187
description: >
184-
TODO
188+
https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=
185189
186190
- name: RESULT
187191
type: string
188192
norms:
189193
enabled: false
190194
description: >
191-
TODO
195+
For private use only.
192196
193197
- name: UNIT
194198
type: string
195199
description: >
196-
TODO
200+
For private use only.

‎namespaces/tlog.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@ namespace:
33
name: tlog
44
type: group
55
description: >
6-
Tlog terminal I/O recording messages
7-
For more information please see
6+
Tlog terminal I/O recording messages. For more information please see
87
https://github.com/Scribery/tlog
98
fields:
109
- name: ver

0 commit comments

Comments
 (0)