From e45caadefa18c569e4532433f6b0701e5f305667 Mon Sep 17 00:00:00 2001 From: Sylvain Juge <763082+SylvainJuge@users.noreply.github.com> Date: Fri, 2 Jun 2023 11:27:52 +0200 Subject: [PATCH 1/5] align log docs --- docs/log-correlation.asciidoc | 22 --------------------- docs/logs.asciidoc | 37 +++++++++++++++++++++++++++++++++++ docs/redirects.asciidoc | 5 +++++ 3 files changed, 42 insertions(+), 22 deletions(-) delete mode 100644 docs/log-correlation.asciidoc create mode 100644 docs/logs.asciidoc diff --git a/docs/log-correlation.asciidoc b/docs/log-correlation.asciidoc deleted file mode 100644 index 77ba73394a..0000000000 --- a/docs/log-correlation.asciidoc +++ /dev/null @@ -1,22 +0,0 @@ -[[log-correlation]] -== Log correlation - -In order to correlate logs from your app with transactions captured by the -Elastic APM Node.js Agent, your logs must contain one or more of the following identifiers: - -* `transaction.id` -* `trace.id` -* `span.id` - -The Node.js Agent provides the `apm.currentTraceIds` method to help with this task. - -:leveloffset: -1 -include::agent-api.asciidoc[tag=currentTraceIds] -:leveloffset: +1 - -Using your favorite logging framework, you'd then need to inject this information into your logs. - -When your logs contain the appropriate identifiers, the final step is to ingest them into the same -Elasticsearch instance that contains your APM data. See -{apm-guide-ref}/log-correlation.html#ingest-logs-in-es[Ingest your logs into Elasticsearch] -for more information. diff --git a/docs/logs.asciidoc b/docs/logs.asciidoc new file mode 100644 index 0000000000..781c4d9689 --- /dev/null +++ b/docs/logs.asciidoc @@ -0,0 +1,37 @@ +[[logs]] +## Logs + +Elastic Nodejs Agent provides <>. +The agent will automaticaly inject correlation IDs that allow navigation between logs, traces and services. + +This features is part of {observability-guide}/application-logs.html[Application log ingestion strategies]. + +The {ecs-logging-nodejs-ref}/intro.html[`ecs-logging-nodejs`] library can also be used to use the {ecs-logging-ref}/intro.html[ECS logging] format without an APM agent. +When deployed with the Nodejs APM agent, the agent will provide <> IDs. + +[float] +[[log-correlation-ids]] +== Log correlation + +{apm-guide-ref}/log-correlation.html[Log correlation] allows you to navigate to all logs belonging to a particular trace +and vice-versa: for a specific log, see in which context it has been logged and which parameters the user provided. + +In order to correlate logs from your app with transactions captured by the +Elastic APM Node.js Agent, your logs must contain one or more of the following identifiers: + +* `transaction.id` +* `trace.id` +* `span.id` + +The Node.js Agent provides the `apm.currentTraceIds` method to help with this task. + +:leveloffset: -1 +include::agent-api.asciidoc[tag=currentTraceIds] +:leveloffset: +1 + +Using your favorite logging framework, you'd then need to inject this information into your logs. + +When your logs contain the appropriate identifiers, the final step is to ingest them into the same +Elasticsearch instance that contains your APM data. See +{apm-guide-ref}/log-correlation.html#ingest-logs-in-es[Ingest your logs into Elasticsearch] +for more information. diff --git a/docs/redirects.asciidoc b/docs/redirects.asciidoc index 00a1b74a54..b7c85825eb 100644 --- a/docs/redirects.asciidoc +++ b/docs/redirects.asciidoc @@ -50,3 +50,8 @@ This page has moved. - For details on ES Modules (ESM) support, see <>. - For information on using the APM agent with TypeScript, see <>. + +[role="exclude",id="log-correlation"] +=== Log correlation + +This section has moved. See <>. From 6f0043883f4d84bd7a6dbd4eb7c9aff4ae8518e1 Mon Sep 17 00:00:00 2001 From: Sylvain Juge <763082+SylvainJuge@users.noreply.github.com> Date: Fri, 2 Jun 2023 14:06:31 +0200 Subject: [PATCH 2/5] fix and reorder links --- docs/index.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 812bed368b..3bb3ff10f3 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -32,12 +32,12 @@ include::./api.asciidoc[] include::./metrics.asciidoc[] +include::./logs.asciidoc[] + include::./api-opentelemetry.asciidoc[] include::./opentracing.asciidoc[] -include::./log-correlation.asciidoc[] - include::./source-maps.asciidoc[] include::./distributed-tracing.asciidoc[] From bb83f4b1992439e7056a3e888c3576169dc41ebf Mon Sep 17 00:00:00 2001 From: Sylvain Juge <763082+SylvainJuge@users.noreply.github.com> Date: Fri, 9 Jun 2023 09:15:57 +0200 Subject: [PATCH 3/5] apply suggestion patch --- docs/agent-api.asciidoc | 8 +------- docs/logs.asciidoc | 33 +++++++++++++++------------------ 2 files changed, 16 insertions(+), 25 deletions(-) diff --git a/docs/agent-api.asciidoc b/docs/agent-api.asciidoc index 57333d9032..64e5f0db99 100644 --- a/docs/agent-api.asciidoc +++ b/docs/agent-api.asciidoc @@ -863,13 +863,9 @@ apm.clearPatches(['timers']) [small]#Added in: v2.17.0# -// This content is reused in log-correlation.asciidoc -// Ensure any updates here also make sense there -// tag::currentTraceIds[] - `apm.currentTraceIds` produces an object containing `trace.id` and either `transaction.id` or `span.id` when a current transaction or span is available. When no transaction or span is available it will return an empty object. -This enables <> to APM traces with structured loggers. +This enables <> to APM traces with structured loggers. [source,js] ---- @@ -884,8 +880,6 @@ This enables <> to APM traces with structured l } ---- -// end::currentTraceIds[] - [[apm-register-custom-metrics]] ==== `apm.registerMetric(name[, labels], callback)` diff --git a/docs/logs.asciidoc b/docs/logs.asciidoc index 781c4d9689..d59f21efde 100644 --- a/docs/logs.asciidoc +++ b/docs/logs.asciidoc @@ -1,13 +1,12 @@ [[logs]] ## Logs -Elastic Nodejs Agent provides <>. -The agent will automaticaly inject correlation IDs that allow navigation between logs, traces and services. +The Elastic APM Node.js Agent provides support for <>. When +used together with the {ecs-logging-nodejs-ref}/intro.html[`ecs-logging-nodejs` +packages], correlation IDs will be automatically injected into log records to +allow navigation between logs, traces, and services. -This features is part of {observability-guide}/application-logs.html[Application log ingestion strategies]. - -The {ecs-logging-nodejs-ref}/intro.html[`ecs-logging-nodejs`] library can also be used to use the {ecs-logging-ref}/intro.html[ECS logging] format without an APM agent. -When deployed with the Nodejs APM agent, the agent will provide <> IDs. +This feature is part of {observability-guide}/application-logs.html[Application log ingestion strategies]. [float] [[log-correlation-ids]] @@ -16,20 +15,18 @@ When deployed with the Nodejs APM agent, the agent will provide <> API for this. +If your application is also using one of the {ecs-logging-nodejs-ref}/intro.html[ECS formatting plugin packages] +(available for Pino, Winston, and Morgan), then this APM Agent API will +automatically be used to inject the appropriate tracing fields into your log +records. Otherwise, configure your logger to add these fields when emitting a +log record. When your logs contain the appropriate identifiers, the final step is to ingest them into the same Elasticsearch instance that contains your APM data. See From 34afc6fe51b79323f0b822eb42b8af58a42bb6b1 Mon Sep 17 00:00:00 2001 From: Sylvain Juge <763082+SylvainJuge@users.noreply.github.com> Date: Fri, 9 Jun 2023 09:18:20 +0200 Subject: [PATCH 4/5] add a few links to ECS spec --- docs/logs.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/logs.asciidoc b/docs/logs.asciidoc index d59f21efde..f9fe788b5e 100644 --- a/docs/logs.asciidoc +++ b/docs/logs.asciidoc @@ -18,8 +18,8 @@ and vice-versa: for a specific log, see in which context it has been logged and In order to correlate logs from your application with traces captured by the Elastic APM Node.js Agent, your logs must contain the following identifiers: -* `trace.id` -* `transaction.id` or `span.id` +* {ecs-ref}/ecs-tracing.html[`trace.id`] +* {ecs-ref}/ecs-tracing.html[`transaction.id`]* or {ecs-ref}/ecs-error.html[`span.id`] The APM Node.js Agent provides the <> API for this. If your application is also using one of the {ecs-logging-nodejs-ref}/intro.html[ECS formatting plugin packages] From c8821de801417efec1035d10330eea77a9993009 Mon Sep 17 00:00:00 2001 From: SylvainJuge <763082+SylvainJuge@users.noreply.github.com> Date: Thu, 15 Jun 2023 15:41:40 +0200 Subject: [PATCH 5/5] Update docs/logs.asciidoc Co-authored-by: Trent Mick --- docs/logs.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/logs.asciidoc b/docs/logs.asciidoc index f9fe788b5e..94d3ec1c39 100644 --- a/docs/logs.asciidoc +++ b/docs/logs.asciidoc @@ -19,7 +19,7 @@ In order to correlate logs from your application with traces captured by the Elastic APM Node.js Agent, your logs must contain the following identifiers: * {ecs-ref}/ecs-tracing.html[`trace.id`] -* {ecs-ref}/ecs-tracing.html[`transaction.id`]* or {ecs-ref}/ecs-error.html[`span.id`] +* {ecs-ref}/ecs-tracing.html[`transaction.id`] or {ecs-ref}/ecs-tracing.html[`span.id`] The APM Node.js Agent provides the <> API for this. If your application is also using one of the {ecs-logging-nodejs-ref}/intro.html[ECS formatting plugin packages]