Skip to content

Commit c3567a9

Browse files
bmorelli25felixbarny
bmorelli25
and
felixbarny
authored
docs: set up shared content (#40)
Co-authored-by: Felix Barnsteiner <[email protected]>
1 parent 8c72f7a commit c3567a9

File tree

4 files changed

+136
-39
lines changed

4 files changed

+136
-39
lines changed

‎docs/index.asciidoc

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,11 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
33

44
ifdef::env-github[]
55
NOTE: For the best reading experience,
6-
please view this documentation at https://www.elastic.co/guide/en/ecs-logging/java/current/index.html[elastic.co]
6+
please view this documentation at https://www.elastic.co/guide/en/ecs-logging/current/index.html[elastic.co]
77
endif::[]
88

99
= ECS Logging Reference
1010

1111
ifndef::env-github[]
1212
include::./intro.asciidoc[Introduction]
13-
include::./setup.asciidoc[Set up]
1413
endif::[]

‎docs/intro.asciidoc

Lines changed: 110 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,19 @@ They make it easy to format your logs into ECS-compatible JSON. For example:
2424
{"@timestamp":"2019-08-06T14:08:40.199Z", "log.level":"DEBUG", "message":"init find form", "service.name":"spring-petclinic","process.thread.name":"http-nio-8080-exec-8","log.logger":"org.springframework.samples.petclinic.owner.OwnerController","transaction.id":"28b7fb8d5aba51f1","trace.id":"2869b25b5469590610fea49ac04af7da"}
2525
----
2626

27+
// To do: Update these links to be documentation links
28+
[float]
29+
=== Get started
30+
31+
Refer to the installation instructions of the individual loggers for
32+
https://github.com/elastic/ecs-dotnet#logging[.NET],
33+
Go (https://github.com/elastic/ecs-logging-go-zap[zap]),
34+
https://www.elastic.co/guide/en/ecs-logging/java/current/setup.html[Java],
35+
https://github.com/elastic/ecs-logging-js[JavaScript],
36+
https://github.com/elastic/ecs-logging-php[PHP],
37+
https://github.com/elastic/ecs-logging-python[Python],
38+
and https://github.com/elastic/ecs-logging-ruby[Ruby].
39+
2740
[float]
2841
=== Why ECS logging?
2942

@@ -58,18 +71,6 @@ showing only the logs which belong to the corresponding request.
5871
Vice versa, you can also jump from a log line in the Logs UI to the Span Timeline of the APM UI.
5972
--
6073

61-
*Broad support for languages and loggers*::
62-
+
63-
--
64-
We have loggers for https://github.com/elastic/ecs-dotnet[.NET],
65-
Go (https://github.com/elastic/ecs-logging-go-zap[zap]),
66-
https://www.elastic.co/guide/en/ecs-logging/java/current/intro.html[Java],
67-
https://github.com/elastic/ecs-logging-js[JavaScript],
68-
https://github.com/elastic/ecs-logging-php[PHP],
69-
https://github.com/elastic/ecs-logging-python[Python],
70-
and https://github.com/elastic/ecs-logging-ruby[Ruby].
71-
--
72-
7374
[float]
7475
==== Additional advantages when using in combination with Filebeat
7576

@@ -106,3 +107,100 @@ This is much more efficient than using daily indices.
106107
--
107108
Leverage Filebeat's default ECS-compatible {filebeat-ref}/configuration-template.html[index template].
108109
--
110+
111+
[float]
112+
=== Field mapping
113+
114+
[float]
115+
==== Default fields
116+
117+
These fields are populated by the ECS loggers by default.
118+
Some of them, such as the `log.origin.*` fields, may have to be explicitly enabled.
119+
Others, such as `process.thread.name`, are not applicable to all languages.
120+
Refer to the documentation of the individual loggers for more information.
121+
122+
|===
123+
|ECS field | Description | Example
124+
125+
|{ecs-ref}/ecs-base.html[`@timestamp`]
126+
|The timestamp of the log event.
127+
|`"2019-08-06T12:09:12.375Z"`
128+
129+
|{ecs-ref}/ecs-log.html[`log.level`]
130+
|The level or severity of the log event.
131+
|`"INFO"`
132+
133+
|{ecs-ref}/ecs-log.html[`log.logger`]
134+
|The name of the logger inside an application.
135+
|`"org.example.MyClass"`
136+
137+
|{ecs-ref}/ecs-log.html[`log.origin.file.name`]
138+
|The name of the file containing the source code which originated the log event.
139+
|`"App.java"`
140+
141+
|{ecs-ref}/ecs-log.html[`log.origin.file.line`]
142+
|The line number of the file containing the source code which originated the log event.
143+
|`42`
144+
145+
|{ecs-ref}/ecs-log.html[`log.origin.function`]
146+
|The name of the function or method which originated the log event.
147+
|`"methodName"`
148+
149+
|{ecs-ref}/ecs-base.html[`message`]
150+
|The log message.
151+
|`"Hello World!"`
152+
153+
|{ecs-ref}/ecs-error.html[`error.type`]
154+
|Only present for logs that contain an exception or error.
155+
The type or class of the error if this log event contains an exception.
156+
|`"java.lang.NullPointerException"`
157+
158+
|{ecs-ref}/ecs-error.html[`error.message`]
159+
|Only present for logs that contain an exception or error.
160+
The message of the exception or error.
161+
|`"The argument cannot be null"`
162+
163+
|{ecs-ref}/ecs-error.html[`error.stack_trace`]
164+
|Only present for logs that contain an exception or error.
165+
The full stack trace of the exception or error as a raw string.
166+
|`"Exception in thread "main" java.lang.NullPointerException\n\tat org.example.App.methodName(App.java:42)"`
167+
168+
|{ecs-ref}/ecs-process.html[`process.thread.name`]
169+
|The name of the thread the event has been logged from.
170+
|`"main"`
171+
172+
|===
173+
174+
175+
[float]
176+
==== Configurable fields
177+
178+
Refer to the documentation of the individual loggers on how to set these fields.
179+
180+
|===
181+
|ECS field | Description | Example
182+
183+
|{ecs-ref}/ecs-service.html[`service.name`]
184+
| Helps to filer the logs by service.
185+
|`"my-service"`
186+
187+
|{ecs-ref}/ecs-event.html[`event.dataset`]
188+
| Enables the {observability-guide}/inspect-log-anomalies.html[log rate anomaly detection].
189+
|`"my-service.log"`
190+
191+
|===
192+
193+
194+
[float]
195+
==== Custom fields
196+
197+
Most loggers allow you to add additional custom fields.
198+
This includes both, static and dynamic ones.
199+
Examples for dynamic fields are logging structured objects,
200+
or fields from a thread local context, such as `MDC` or `ThreadContext`.
201+
202+
When adding custom fields, we recommend using existing {ecs-ref}/ecs-field-reference.html[ECS fields] for these custom values.
203+
If there is no appropriate ECS field,
204+
consider prefixing your fields with `labels.`, as in `labels.foo`, for simple key/value pairs.
205+
For nested structures, consider prefixing with `custom.`.
206+
This approach protects against conflicts in case ECS later adds the same fields but with a different mapping.

‎docs/setup.asciidoc

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,32 @@
1-
[[setup]]
2-
== Get Started
1+
////
2+
This page serves at a template for setup.asciidoc.
3+
This content is shared across all ECS Logging plugins.
4+
Changes made here must be relevant to all plugin languages.
5+
Include this file with the following lines:
6+
:ecs-repo-dir: {ecs-logging-root}/docs/
7+
include::{ecs-repo-dir}/setup.asciidoc[tag=<tag-name>]
8+
Need to change heading levels? Use `leveloffset`
9+
////
310
4-
include::./tab-widgets/code.asciidoc[]
11+
// [float]
12+
// [[setup-step-1]]
13+
// === Step 1: Configure application logging
514
6-
[float]
7-
[[setup-step-1]]
8-
=== Step 1: Configure application logging
15+
// Unique to each agent
916
10-
Refer to the installation instructions of the individual loggers for
11-
https://github.com/elastic/ecs-dotnet#logging[.NET],
12-
Go (https://github.com/elastic/ecs-logging-go-zap[zap]),
13-
https://www.elastic.co/guide/en/ecs-logging/java/current/setup.html[Java],
14-
https://github.com/elastic/ecs-logging-js[JavaScript],
15-
https://github.com/elastic/ecs-logging-php[PHP],
16-
https://github.com/elastic/ecs-logging-python[Python],
17-
and https://github.com/elastic/ecs-logging-ruby[Ruby].
17+
// [float]
18+
// [[setup-step-2]]
19+
// === Step 2: Enable APM log correlation (optional)
1820
19-
[float]
20-
[[setup-step-2]]
21-
=== Step 2: Enable APM log correlation (optional)
22-
If you are using an Elastic APM agent,
23-
enable {apm-get-started-ref}/observability-integrations.html#apm-logging-integration[log correlation].
21+
// Unique to each agent
2422
25-
[float]
26-
[[setup-step-3]]
27-
=== Step 3: Configure Filebeat
23+
// [float]
24+
// [[setup-step-3]]
25+
// === Step 3: Configure Filebeat
2826
27+
// tag::configure-filebeat[]
28+
include::./tab-widgets/code.asciidoc[]
2929
include::./tab-widgets/filebeat-widget.asciidoc[]
3030
31-
For more information, check the {filebeat-ref}/configuring-howto-filebeat.html[Filebeat documentation].
32-
31+
For more information, see the {filebeat-ref}/configuring-howto-filebeat.html[Filebeat reference].
32+
// end::configure-filebeat[]

‎docs/tab-widgets/filebeat-widget.asciidoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
++++
2-
<div class="tabs" data-tab-group="os">
2+
<div class="tabs" data-tab-group="fb">
33
<div role="tablist" aria-label="filebeat">
44
<button role="tab"
55
aria-selected="true"

0 commit comments

Comments
 (0)