[doc] Align agents logs documentation (#1394)

* align agent logs docs * fix 'logs' header conflict * Apply suggestions from code review Co-authored-by: Emily S <[email protected]> --------- Co-authored-by: Emily S <[email protected]>
elastic · Jul 3, 2023 · e099480 · e099480
1 parent 6b3213f
commit e099480
Show file tree

Hide file tree

Showing 4 changed files with 41 additions and 5 deletions.
diff --git a/docs/index.asciidoc b/docs/index.asciidoc
@@ -23,12 +23,12 @@ include::./api.asciidoc[]
 
 include::./metrics.asciidoc[]
 
+include::./logs.asciidoc[]
+
 include::./opentracing.asciidoc[]
 
 include::./graphql.asciidoc[]
 
-include::./log-correlation.asciidoc[]
-
 include::./performance-tuning.asciidoc[]
 
 include::./debugging.asciidoc[]

diff --git a/docs/log-correlation.asciidoc → docs/logs.asciidoc b/docs/log-correlation.asciidoc → docs/logs.asciidoc
@@ -3,8 +3,26 @@ NOTE: For the best reading experience,
 please view this documentation at https://www.elastic.co/guide/en/apm/agent/ruby[elastic.co]
 endif::[]
 
-[[log-correlation]]
-== Log correlation
+[[logs]]
+== Logs
+
+Elastic Ruby APM Agent provides the following log features:
+
+- <<log-correlation-ids>>: Automatically inject correlation IDs that allow navigation between logs, traces and services.
+- <<log-reformatting>>: Automatically reformat plaintext logs in {ecs-logging-ref}/intro.html[ECS logging] format.
+
+Those features are part of {observability-guide}/application-logs.html[Application log ingestion strategies].
+
+The {ecs-logging-ruby-ref}/intro.html[`ecs-logging-ruby`] library can also be used to format logs in the {ecs-logging-ref}/intro.html[ECS logging] format without an APM agent.
+When deployed with the Ruby APM agent, the agent will provide <<log-correlation-ids,log correlation>> 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.
+
 
 Trace/log correlation can be set up in three different ways.
 
@@ -119,3 +137,12 @@ PUT _ingest/pipeline/extract_trace_id
 ----
 
 Please see {apm-guide-ref}/log-correlation.html[Observability integrations] for more information.
+
+[float]
+[[log-reformatting]]
+=== Log reformatting (experimental)
+
+Log reformatting is controlled by the <<config-log-ecs-formatting, `log_ecs_reformatting`>> configuration option, and is disabled by default.
+
+The reformatted logs will include both the <<log-correlation-ids, trace and service correlation>> IDs.
+
diff --git a/docs/opentracing.asciidoc b/docs/opentracing.asciidoc
@@ -89,6 +89,6 @@ The `Span.set_baggage` method is not supported.
 Baggage items are dropped with a warning log message.
 
 [float]
-[[logs]]
+[[opentracing-logs]]
 === Logs
 Logs are currently not supported.
diff --git a/docs/redirects.asciidoc b/docs/redirects.asciidoc
@@ -0,0 +1,9 @@
+["appendix",role="exclude",id="redirects"]
+= Deleted pages
+
+The following pages have moved or been deleted.
+
+[role="exclude",id="log-correlation"]
+=== Log correlation
+
+This section has moved. See <<logs>>.