@@ -143,15 +143,23 @@ Given the above state of the logging space we took the following approach:
143143 OpenTelemetry log data model. OpenTelemetry Collector can read such logs and
144144 translate them to OpenTelemetry log data model.
145145
146- - OpenTelemetry defines a Logs API
147- for [ emitting LogRecords] ( ./api.md#emit-a-logrecord ) . It is provided for
148- library authors to build [ log appender ] ( ../glossary.md#log-appender--bridge ) ,
146+ - OpenTelemetry defines a [ Logs API] ( ./api.md )
147+ for [ emitting LogRecords] ( ./api.md#emit-a-logrecord ) . It was primarily designed
148+ for library authors to build [ log appenders ] ( ../glossary.md#log-appender--bridge ) ,
149149 which use the API to bridge between existing logging libraries and the
150- OpenTelemetry log data model. Existing logging libraries generally provide
151- a much richer set of features than what is defined in OpenTelemetry.
152- It is NOT a goal of OpenTelemetry to ship a feature-rich logging library.
153- Yet, the Logs API can also be used directly if one prefers to couple the code
154- to it instead of using a bridged logging library.
150+ OpenTelemetry log data model. The Logs API can also be used directly by
151+ applications, which is particularly important for:
152+
153+ - ** Instrumentation libraries** to avoid coupling to a particular logging library.
154+ - ** Emitting structured events** following [ semantic conventions] ( https://opentelemetry.io/docs/specs/semconv/ ) ,
155+ especially when the existing logging library cannot emit structured data or specify event names.
156+ - ** Scenarios requiring direct control** over log emission without
157+ intermediary logging library.
158+
159+ Note that existing logging libraries generally provide a much richer set of
160+ features than what is defined in OpenTelemetry. Yet, languages may provide
161+ an [ ergonomic API] ( ./api.md#ergonomic-api ) for better developer experience
162+ when using it directly.
155163
156164- OpenTelemetry defines an [ SDK] ( ./sdk.md ) implementation of the [ API] ( ./api.md ) ,
157165 which enables configuration of [ processing] ( ./sdk.md#logrecordprocessor )
@@ -375,17 +383,30 @@ application startup.
375383
376384These are greenfield developments. OpenTelemetry provides recommendations and
377385best practices about how to emit logs (along with traces and metrics) from these
378- applications. For applicable languages and frameworks the auto-instrumentation
379- or simple configuration of a logging library to use an OpenTelemetry log appender
380- will still be the easiest way to emit context-enriched logs. As
381- already described earlier we provide extensions to some popular logging
382- libraries languages to support the manual instrumentation cases. The extensions
383- will support the inclusion of the trace context in the logs and allow to send
384- logs using OTLP protocol to the backend or to the Collector, bypassing the need
385- to have the logs represented as text files. Emitted logs are automatically
386- augmented by application-specific resource context (e.g. process id, programming
387- language, logging library name and version, etc). Full correlation across all
388- context dimensions will be available for these logs.
386+ applications.
387+
388+ Applications have several options for emitting logs:
389+
390+ 1 . ** Using existing logging libraries with OpenTelemetry log appenders** : For
391+ applicable languages and frameworks, auto-instrumentation or simple
392+ configuration of a logging library to use an OpenTelemetry log appender will
393+ be the easiest way to emit context-enriched logs. As already described earlier,
394+ we provide extensions to some popular logging libraries to support manual
395+ instrumentation cases. The extensions support the inclusion of the trace
396+ context in the logs and allow sending logs via OTLP protocol to the backend
397+ or to the Collector, bypassing the need to have the logs represented as text
398+ files.
399+
400+ 2 . ** Using the OpenTelemetry Logs API directly** : Applications can use the
401+ [ Logs API] ( ./api.md ) directly to emit structured logs and events. This approach
402+ works well for emitting events following [ semantic conventions] ( https://opentelemetry.io/docs/specs/semconv/ )
403+ and enables easier reuse of attributes used across different signals. Note
404+ that a language can provide a more convenient [ ergonomic API] ( ./api.md#ergonomic-api ) .
405+
406+ Regardless of the approach, emitted logs are automatically augmented by
407+ application-specific resource context (e.g. process id, programming language,
408+ logging library name and version, etc). Full correlation across all context
409+ dimensions will be available for these logs.
389410
390411This is how a typical new application uses OpenTelemetry API, SDK and the
391412existing log libraries:
0 commit comments