Add java documentation for log signal (open-telemetry#2583)

Co-authored-by: Phillip Carter <[email protected]>

content/en/docs/instrumentation/java/manual.md

@@ -71,6 +71,8 @@ telemetry source-identifying info.
 </project>
 ```
 
+See [releases][releases] for a full list of artifact coordinates.
+
 ### Gradle
 
 ```kotlin
@@ -82,6 +84,8 @@ dependencies {
 }
 ```
 
+See [releases][releases] for a full list of artifact coordinates.
+
 ### Imports
 
 ```java
@@ -116,6 +120,8 @@ SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
   .setResource(resource)
   .build();
 
+// TODO: add log configuration when stable
+
 OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
   .setTracerProvider(sdkTracerProvider)
   .setMeterProvider(sdkMeterProvider)
@@ -616,6 +622,90 @@ meter
   });
 ```
 
+## Logs
+
+Logs are distinct from Metrics and Tracing in that there is no user-facing logs
+API. Instead, there is tooling to bridge logs from existing popular log
+frameworks (e.g. SLF4j, JUL, Logback, Log4j) into the OpenTelemetry ecosystem.
+
+The two typical workflows discussed below each cater to different application
+requirements.
+
+### Direct to collector
+
+In the direct to collector workflow, logs are emitted directly from an
+application to a collector using a network protocol (e.g. OTLP). This workflow
+is simple to set up as it doesn't require any additional log forwarding
+components, and allows an application to easily emit structured logs that
+conform to the [log data model][log data model]. However, the overhead required
+for applications to queue and export logs to a network location may not be
+suitable for all applications.
+
+To use this workflow:
+
+- Install appropriate [Log Appender](#log-appenders).
+- Configure the OpenTelemetry [Log SDK](#logs-sdk) to export log records to
+  desired target destination (the [collector][opentelemetry collector] or
+  other).
+
+#### Log appenders
+
+A log appender bridges logs from a log framework into the OpenTelemetry
+[Log SDK](#logs-sdk) using the [Logs Bridge API][logs bridge API]. Log appenders
+are available for various popular java log frameworks:
+
+- [Log4j2 Appender][log4j2 appender]
+- [Logback Appender][logback appender]
+
+The links above contain full usage and installation documentation, but
+installation is generally as follows:
+
+- Add required dependency via gradle or maven.
+- Extend the application's log configuration (i.e. `logback.xml`, `log4j.xml`,
+  etc) to include a reference to the OpenTelemetry log appender.
+  - Optionally configure the log framework to determine which logs (i.e. filter
+    by severity or logger name) are passed to the appender.
+  - Optionally configure the appender to indicate how logs are mapped to
+    OpenTelemetry Log Records (i.e. capture thread information, context data,
+    markers, etc).
+
+Log appenders automatically include the trace context in log records, enabling
+log correlation with traces.
+
+The [Log Appender example][log appender example] demonstrates setup for a
+variety of scenarios.
+
+### Via file or stdout
+
+In the file or stdout workflow, logs are written to files or standout output.
+Another component (e.g. FluentBit) is responsible for reading / tailing the
+logs, parsing them to more structured format, and forwarding them a target, such
+as the collector. This workflow may be preferable in situations where
+application requirements do not permit additional overhead from
+[direct to collector](#direct-to-collector). However, it requires that all log
+fields required down stream are encoded into the logs, and that the component
+reading the logs parse the data into the [log data model][log data model]. The
+installation and configuration of log forwarding components is outside the scope
+of this document.
+
+Log correlation with traces is available by installing
+[log context instrumentation](#log-context-instrumentation).
+
+#### Log context instrumentation
+
+OpenTelemetry provides components which enrich log context with trace context
+for various popular java log frameworks:
+
+- [Log4j context data instrumentation][log4j context instrumentation]
+- [Logback MDC instrumentation][logback context instrumentation]
+
+This links above contain full usage and installation documentation, but
+installation is generally as follows:
+
+- Add required dependency via gradle or maven.
+- Extend the application's log configuration (i.e. `logback.xml` or `log4j.xml`,
+  etc) to reference the trace context fields in the log pattern.
+
 ## SDK Configuration
 
 The configuration examples reported in this document only apply to the SDK
@@ -798,6 +888,68 @@ view is replaced by the registered view. Additional registered views that match
 the instrument are additive, and result in multiple exported metrics for the
 instrument.
 
+### Logs SDK
+
+The logs SDK dictates how logs are processed when using the
+[direct to collector](#direct-to-collector) workflow. No log SDK is needed when
+using the [log forwarding](#via-file-or-stdout) workflow.
+
+The typical log SDK configuration installs a log record processor and exporter.
+For example, the following installs the
+[BatchLogRecordProcessor](#logrecord-processor), which periodically exports to a
+network location via the [OtlpGrpcLogRecordExporter](#logrecord-exporter):
+
+```java
+SdkLoggerProvider loggerProvider = SdkLoggerProvider.builder()
+  .addLogRecordProcessor(
+    BatchLogRecordProcessor.builder(
+      OtlpGrpcLogRecordExporter.builder()
+          .setEndpoint("http://localhost:4317")
+          .build())
+      .build())
+  .build();
+```
+
+See [releases][releases] for log specific artifact coordinates.
+
+#### LogRecord Processor
+
+LogRecord processors process LogRecords emitted by
+[log appenders](#log-appenders).
+
+OpenTelemetry provides the following LogRecord processors out of the box:
+
+- `BatchLogRecordProcessor`: periodically sends batches of LogRecords to a
+  [LogRecordExporter](#logrecord-exporter).
+- `SimpleLogRecordProcessor`: immediately sends each LogRecord to a
+  [LogRecordExporter](#logrecord-exporter).
+
+Custom LogRecord processors are supported by implementing the
+`LogRecordProcessor` interface. Common use cases include enriching the
+LogRecords with contextual data like baggage, or filtering / obfuscating
+sensitive data.
+
+#### LogRecord Exporter
+
+`BatchLogRecordProcessor` and `SimpleLogRecordProcessor` are paired with
+`LogRecordExporter`, which is responsible for sending telemetry data to a
+particular backend. OpenTelemetry provides the following exporters out of the
+box:
+
+- OpenTelemetry Protocol Exporter: sends the data in OTLP to the [OpenTelemetry
+  Collector] or other OTLP receivers. Varieties include
+  `OtlpGrpcLogRecordExporter` and `OtlpHttpLogRecordExporter`.
+- `InMemoryLogRecordExporter`: keeps the data in memory, useful for testing and
+  debugging.
+- Logging Exporter: saves the telemetry data into log streams. Varieties include
+  `SystemOutLogRecordExporter` and `OtlpJsonLoggingLogRecordExporter`. Note:
+  `OtlpJsonLoggingLogRecordExporter` logs to JUL, and may cause infinite loops
+  (i.e. JUL -> SLF4J -> Logback -> OpenTelemetry Appender -> OpenTelemetry Log
+  SDK -> JUL) if not carefully configured.
+
+Custom exporters are supported by implementing the `LogRecordExporter`
+interface.
+
 ### Auto Configuration
 
 Instead of manually creating the `OpenTelemetry` instance by using the SDK
@@ -863,7 +1015,7 @@ AutoConfiguredOpenTelemetrySdk.builder()
         .build();
 ```
 
-## Logging and Error Handling
+## SDK Logging and Error Handling
 
 OpenTelemetry uses
 [java.util.logging](https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html)
@@ -930,12 +1082,25 @@ io.opentelemetry.sdk.trace.export.BatchSpanProcessor = io.opentelemetry.extensio
 [instrumented library]:
   /docs/reference/specification/glossary/#instrumented-library
 [library guidelines]: /docs/reference/specification/library-guidelines
+[logs bridge API]: /docs/reference/specification/logs/bridge-api
+[log data model]: /docs/reference/specification/logs/data-model
+[log4j2 appender]:
+  https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/log4j/log4j-appender-2.17/library
+[logback appender]:
+  https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/logback/logback-appender-1.0/library
+[log appender example]:
+  https://github.com/open-telemetry/opentelemetry-java-docs/tree/main/log-appender
+[log4j context instrumentation]:
+  https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/log4j/log4j-context-data/log4j-context-data-2.17/library-autoconfigure
+[logback context instrumentation]:
+  https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/logback/logback-mdc-1.0/library
 [obtaining a tracer]: /docs/reference/specification/trace/api/#get-a-tracer
 [opentelemetry collector]:
   https://github.com/open-telemetry/opentelemetry-collector
 [opentelemetry registry]: /ecosystem/registry/?component=exporter&language=java
 [parentbased]:
   https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/ParentBasedSampler.java
+[releases]: https://github.com/open-telemetry/opentelemetry-java#releases
 [semantic conventions]: /docs/reference/specification/trace/semantic_conventions
 [traceidratiobased]:
   https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/TraceIdRatioBasedSampler.java