Skip to content

Commit 3dc319f

Browse files
trentmbmorelli25
trentm
and
bmorelli25
authored
docs: AsciiDoc docs for publishing (#44)
Move most of the README docs into docs/*.asciidoc for publishing. Co-authored-by: Brandon Morelli <[email protected]>
1 parent 1a5f056 commit 3dc319f

File tree

12 files changed

+855
-340
lines changed

12 files changed

+855
-340
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,9 @@ typings/
6060
# next.js build output
6161
.next
6262

63+
# doc build output
64+
html_docs
65+
6366
.ecs
6467
.DS_Store
6568
/tmp

‎Makefile

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
.PHONY: all
66
all:
77
./.ci/run-install.sh
8+
(cd utils && npm install)
89

910
.PHONY: clean
1011
clean:
@@ -34,6 +35,19 @@ fmt:
3435
test:
3536
./.ci/run-test.sh
3637

38+
# Build and open the rendered docs for testing.
39+
#
40+
# Requirements:
41+
# - Docker is running
42+
# - "../docs" is an elastic/docs.git clone
43+
# - "../ecs-logging" is an elastic/ecs-logging.git clone
44+
.PHONY: docs-and-open
45+
docs-and-open:
46+
export GIT_HOME=$(shell cd .. && pwd) && \
47+
$$GIT_HOME/docs/build_docs \
48+
--resource $$GIT_HOME/ecs-logging/docs/ --chunk 1 --open \
49+
--doc $$PWD/docs/index.asciidoc
50+
3751
# List licenses of prod deps.
3852
.PHONY: list-licenses
3953
list-licenses:

‎README.md

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,9 @@
55
[![Build Status](https://apm-ci.elastic.co/buildStatus/icon?job=apm-agent-nodejs%2Fecs-logging-nodejs-mbp%2Fmaster)](https://apm-ci.elastic.co/job/apm-agent-nodejs/job/ecs-logging-nodejs-mbp/job/master/) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](http://standardjs.com/)
66

77
This set of libraries allows you to transform your application logs to structured logs that comply with the [Elastic Common Schema (ECS)](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html).
8-
In combination with [filebeat](https://www.elastic.co/products/beats/filebeat) you can send your logs directly to Elasticsearch and leverage [Kibana's Logs UI](https://www.elastic.co/guide/en/infrastructure/guide/current/logs-ui-overview.html) to inspect all logs in one single place.
9-
See [ecs-logging](https://github.com/elastic/ecs-logging) for other ECS logging libraries and more resources about ECS & logging.
8+
In combination with [filebeat](https://www.elastic.co/products/beats/filebeat) you can send your logs directly to Elasticsearch and leverage [Kibana's Logs app](https://www.elastic.co/guide/en/observability/current/monitor-logs.html) to inspect all logs in one single place.
9+
10+
Please see the [Node.js ECS logging documentation](https://www.elastic.co/guide/en/ecs-logging/nodejs/current/intro.html).
1011

1112
---
1213

@@ -16,13 +17,16 @@ backwards-incompatible changes might be introduced in releases during the
1617

1718
---
1819

19-
### Supported logging frameworks
20+
## Supported logging frameworks
2021

22+
- [Morgan](https://github.com/expressjs/morgan) via [@elastic/ecs-morgan-format](./loggers/morgan)
23+
([docs](https://www.elastic.co/guide/en/ecs-logging/nodejs/current/morgan.html))
2124
- [Pino](https://getpino.io/#/) via [@elastic/ecs-pino-format](./loggers/pino)
25+
([docs](https://www.elastic.co/guide/en/ecs-logging/nodejs/current/pino.html))
2226
- [Winston](https://github.com/winstonjs/winston) via [@elastic/ecs-winston-format](./loggers/winston)
23-
- [Morgan](https://github.com/expressjs/morgan) via [@elastic/ecs-morgan-format](./loggers/morgan)
27+
([docs](https://www.elastic.co/guide/en/ecs-logging/nodejs/current/winston.html))
2428

25-
### References
29+
## Links
2630

2731
* Introduction to ECS [blog post](https://www.elastic.co/blog/introducing-the-elastic-common-schema).
2832
* Logs UI [blog post](https://www.elastic.co/blog/infrastructure-and-logs-ui-new-ways-for-ops-to-interact-with-elasticsearch).

‎docs/index.asciidoc

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
:ecs-repo-dir: {ecs-logging-root}/docs/
2+
3+
include::{docs-root}/shared/versions/stack/current.asciidoc[]
4+
include::{docs-root}/shared/attributes.asciidoc[]
5+
6+
ifdef::env-github[]
7+
NOTE: For the best reading experience,
8+
please view this documentation at https://www.elastic.co/guide/en/ecs-logging/nodejs/current/index.html[elastic.co]
9+
endif::[]
10+
11+
= ECS Logging Node.js Reference
12+
13+
ifndef::env-github[]
14+
include::./intro.asciidoc[Introduction]
15+
include::./morgan.asciidoc[Logging with Morgan]
16+
include::./pino.asciidoc[Logging with Pino]
17+
include::./winston.asciidoc[Logging with Winston]
18+
endif::[]

‎docs/intro.asciidoc

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
[[intro]]
2+
== Introduction
3+
4+
beta::[]
5+
6+
Node.js ECS loggers are formatter plugins for your favorite logging libraries.
7+
They make it easy to format your logs into ECS-compatible JSON. In combination
8+
with https://www.elastic.co/products/beats/filebeat[filebeat] you can send your
9+
logs directly to Elasticsearch and leverage {observability-guide}/monitor-logs.html[Kibana's Logs app]
10+
to inspect all logs in one single place.
11+
12+
The Node.js ECS logging formatters log structured JSON and support serialization
13+
of Error objects and HTTP Request and Response objects from Node.js core and
14+
popular web frameworks. A minimal log record includes the following fields:
15+
16+
[source,json]
17+
----
18+
{
19+
"@timestamp": "2021-01-13T21:32:38.095Z",
20+
"log.level": "info",
21+
"message": "hi",
22+
"ecs": {"version":"1.5.0"}
23+
}
24+
----
25+
26+
TIP: Want to learn more about ECS, ECS logging, and other available language plugins?
27+
See the {ecs-logging-ref}/intro.html[ECS logging guide].
28+
29+
Ready to jump into Node.js ECS logging?
30+
31+
- <<morgan,ECS Logging with Morgan>>
32+
- <<pino,ECS Logging with Pino>>
33+
- <<winston,ECS Logging with Winston>>

‎docs/morgan.asciidoc

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
[[morgan]]
2+
== ECS Logging with Morgan
3+
4+
This Node.js package provides a formatter for the https://github.com/expressjs/morgan#readme[morgan]
5+
logging middleware -- commonly used with Express -- compatible with
6+
{ecs-logging-ref}/intro.html[Elastic Common Schema (ECS) logging].
7+
In combination with the https://www.elastic.co/beats/filebeat[Filebeat] shipper,
8+
you can https://www.elastic.co/log-monitoring[monitor all your logs] in one
9+
place in the Elastic Stack.
10+
11+
12+
[float]
13+
=== Setup
14+
15+
[float]
16+
[[morgan-setup-step-1]]
17+
==== Step 1: Install
18+
19+
[source,cmd]
20+
----
21+
$ npm install @elastic/ecs-morgan-format
22+
----
23+
24+
25+
[float]
26+
[[morgan-setup-step-2]]
27+
==== Step 2: Configure
28+
29+
[source,js]
30+
----
31+
const app = require('express')()
32+
const morgan = require('morgan')
33+
const ecsFormat = require('@elastic/ecs-morgan-format')
34+
35+
app.use(morgan(ecsFormat())) <1>
36+
37+
// ...
38+
app.get('/', function (req, res) {
39+
res.send('hello, world!')
40+
})
41+
app.listen(3000)
42+
----
43+
<1> Pass the ECS formatter to `morgan()`.
44+
45+
46+
[float]
47+
[[morgan-setup-step-3]]
48+
==== Step 3: Configure Filebeat
49+
50+
The best way to collect the logs once they are ECS-formatted is with {filebeat-ref}[Filebeat]:
51+
52+
include::{ecs-repo-dir}/setup.asciidoc[tag=configure-filebeat]
53+
54+
55+
[float]
56+
[[morgan-usage]]
57+
=== Usage
58+
59+
[source,js]
60+
----
61+
const app = require('express')()
62+
const morgan = require('morgan')
63+
const ecsFormat = require('@elastic/ecs-morgan-format')
64+
65+
app.use(morgan(ecsFormat()))
66+
67+
app.get('/', function (req, res) {
68+
res.send('hello, world!')
69+
})
70+
app.get('/error', function (req, res, next) {
71+
next(new Error('boom'))
72+
})
73+
74+
app.listen(3000)
75+
----
76+
77+
Running this script (the full example is https://github.com/elastic/ecs-logging-nodejs/blob/master/loggers/morgan/examples/express.js[here])
78+
and making a request (via `curl -i localhost:3000/`) will produce log output
79+
similar to the following:
80+
81+
[source,cmd]
82+
----
83+
% node examples/express.js | jq . # piping to jq for pretty-printing
84+
{
85+
"@timestamp": "2021-01-16T00:03:23.279Z",
86+
"log.level": "info",
87+
"message": "::1 - - [16/Jan/2021:00:03:23 +0000] \"GET / HTTP/1.1\" 200 13 \"-\" \"curl/7.64.1\"",
88+
"ecs": {
89+
"version": "1.5.0"
90+
},
91+
"http": {
92+
"version": "1.1",
93+
"request": {
94+
"method": "get",
95+
"headers": {
96+
"host": "localhost:3000",
97+
"accept": "*/*"
98+
}
99+
},
100+
"response": {
101+
"status_code": 200,
102+
"headers": {
103+
"x-powered-by": "Express",
104+
"content-type": "text/html; charset=utf-8",
105+
"etag": "W/\"d-HwnTDHB9U/PRbFMN1z1wps51lqk\""
106+
},
107+
"body": {
108+
"bytes": 13
109+
}
110+
}
111+
},
112+
"url": {
113+
"path": "/",
114+
"domain": "localhost",
115+
"full": "http://localhost:3000/"
116+
},
117+
"user_agent": {
118+
"original": "curl/7.64.1"
119+
}
120+
}
121+
----
122+
123+
[float]
124+
[[morgan-format-options]]
125+
=== Format Options
126+
127+
You can pass any https://github.com/expressjs/morgan#morganformat-options[`format` argument]
128+
you would normally pass to `morgan()`, and the log "message" field will use the
129+
specified format. The default is https://github.com/expressjs/morgan#combined[`combined`].
130+
131+
[source,js]
132+
----
133+
const app = require('express')()
134+
const morgan = require('morgan')
135+
const ecsFormat = require('@elastic/ecs-morgan-format')
136+
137+
app.use(morgan(ecsFormat('tiny'))) <1>
138+
// ...
139+
----
140+
141+
[float]
142+
[[morgan-log-level]]
143+
=== log.level
144+
145+
The `log.level` field will be "error" for response codes >= 500, otherwise
146+
"info". For example, running https://github.com/elastic/ecs-logging-nodejs/blob/master/loggers/morgan/examples/express.js[examples/express.js]
147+
again, a `curl -i localhost:3000/error` will yield:
148+
149+
[source,cmd]
150+
----
151+
% node examples/express.js | jq .
152+
{
153+
"@timestamp": "2021-01-18T17:52:12.810Z",
154+
"log.level": "error",
155+
"message": "::1 - - [18/Jan/2021:17:52:12 +0000] \"GET /error HTTP/1.1\" 500 1416 \"-\" \"curl/7.64.1\"",
156+
"http": {
157+
"response": {
158+
"status_code": 500,
159+
...
160+
----
161+
162+
163+
[float]
164+
[[morgan-apm]]
165+
=== Integration with APM Tracing
166+
167+
This ECS log formatter integrates with https://www.elastic.co/apm[Elastic APM] tracing.
168+
If your Node app is using the {apm-node-ref}/intro.html[Node.js Elastic APM Agent],
169+
then fields are added to log records that {ecs-ref}/ecs-tracing.html[identify an active trace] and the configured service name
170+
({ecs-ref}/ecs-service.html#field-service-name["service.name"] and
171+
{ecs-ref}/ecs-event.html#field-event-dataset["event.dataset"]).
172+
These fields allow cross linking between traces and logs in Kibana and support
173+
log anomaly detection.
174+
175+
For example, running https://github.com/elastic/ecs-logging-nodejs/blob/master/loggers/morgan/examples/express-with-apm.js[examples/express-with-apm.js] and `curl -i localhost:3000/` results in a log record with the following:
176+
177+
[source,cmd]
178+
----
179+
% node examples/express-with-apm.js | jq .
180+
{
181+
...
182+
"event": {
183+
"dataset": "express-with-elastic-apm.log"
184+
},
185+
"trace": {
186+
"id": "e097193afa9ac221017b45a1f674601c"
187+
},
188+
"transaction": {
189+
"id": "c6aa5b47e01bad72"
190+
},
191+
"service": {
192+
"name": "express-with-elastic-apm"
193+
}
194+
}
195+
----
196+
197+
These IDs match trace data reported by the APM agent.

0 commit comments

Comments
 (0)