diff --git a/docs/agent-api.asciidoc b/docs/agent-api.asciidoc index 9b8112048a..4cdd3f1ab9 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/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[] 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..94d3ec1c39 --- /dev/null +++ b/docs/logs.asciidoc @@ -0,0 +1,34 @@ +[[logs]] +## Logs + +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 feature is part of {observability-guide}/application-logs.html[Application log ingestion strategies]. + +[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 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-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] +(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 +{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 <>.