Skip to content

Commit

Permalink
Change log readme request context to trace context (#3332)
Browse files Browse the repository at this point in the history
Related to #3268.

Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
  • Loading branch information
jack-berg and tigrannajaryan committed Mar 22, 2023
1 parent 05cd8e0 commit def6fc3
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 15 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,9 @@ release.

### Logs

- Update log readme "request context" to "trace context".
([#3332](https://github.com/open-telemetry/opentelemetry-specification/pull/3332))

### Resource

### Semantic Conventions
Expand Down
30 changes: 15 additions & 15 deletions specification/logs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,10 @@ backends that don't know how to work well together.

## OpenTelemetry Solution

Distributed tracing introduced the notion of request context propagation.
Distributed tracing introduced the notion of trace context propagation.

Fundamentally, though, nothing prevents the logs to adopt the same context
propagation concepts. If the recorded logs contained request context identifiers
propagation concepts. If the recorded logs contained trace context identifiers
(such as trace and span ids or user-defined baggage) it would result
in much richer correlation between logs and traces, as well as correlation
between logs emitted by different components of a distributed system. This would
Expand Down Expand Up @@ -174,7 +174,7 @@ Logs can be correlated with the rest of observability data in a few dimensions:
of time or the range of time the execution took place. This is the most basic
form of correlation.

- By the **execution context**, also known as the request context. It is a
- By the **execution context**, also known as the trace context. It is a
standard practice to record the execution context (trace and span ids as well
as user-defined context) in the spans. OpenTelemetry extends this practice to
logs where possible by including [TraceId](data-model.md#field-traceid) and
Expand Down Expand Up @@ -215,9 +215,9 @@ may also be able to write records to standard system logs: this case is covered
below in the [Third-Party Applications](#third-party-application-logs) section).

System operations recorded in the logs can be a result of a request execution.
However system logs either do not include any data about the request context or
However system logs either do not include any data about the trace context or
if included it is highly idiosyncratic and thus difficult to identify, parse and
use. This makes it nearly impossible to perform request context correlation for
use. This makes it nearly impossible to perform trace context correlation for
system logs. However we can and should automatically enrich system logs with the
resource context - the information about the host that is available during
collection. This can include the host name, IP address, container or pod name,
Expand All @@ -234,7 +234,7 @@ processor.
These are logs generated by various infrastructure components, such as
Kubernetes events (if you are wondering why events are discussed in the context
of logs see [Event API Overview](./event-api.md#overview)). Like system logs, the
infrastructure logs lack a request context and can be enriched by the resource
infrastructure logs lack a trace context and can be enriched by the resource
context - information about the node, pod, container, etc.

OpenTelemetry Collector or other agents can be used to query logs from most
Expand Down Expand Up @@ -280,20 +280,20 @@ instead of plain text and by doing so help improve the reliability of log
collection.

More significant modifications to these applications can be done manually by
their developers, such as addition of the request context to every log
their developers, such as addition of the trace context to every log
statement, however this is likely going to be vanishingly rare due to the effort
required.

As opposed to manual efforts we have an interesting opportunity to "upgrade"
application logs in a less laborious way by providing full or semi
auto-instrumenting solutions that modify the logging libraries used by the
application to automatically output the request context such as the trace id or
span id with every log statement. The request context can be automatically
auto-instrumenting solutions that modify trace logging libraries used by the
application to automatically output the trace context such as the trace id or
span id with every log statement. The trace context can be automatically
extracted from incoming requests if standard compliant request propagation is
used, e.g. via [W3C TraceContext](https://w3c.github.io/trace-context/). In
addition, the requests outgoing from the application may be injected with the
same request context data, thus resulting in context propagation through the
application and creating an opportunity to have full request context in logs
same trace context data, thus resulting in context propagation through the
application and creating an opportunity to have full trace context in logs
collected from all applications that can be instrumented in this manner.

Some logging libraries are designed to be extended in this manner relatively
Expand Down Expand Up @@ -361,7 +361,7 @@ logs directly to the logging backend without using a log collection agent.

To facilitate both approaches described above OpenTelemetry provides
a [Bridge API](./bridge-api.md) and [SDK](./sdk.md), which can be used together with existing
logging libraries to automatically inject the request context in the emitted logs,
logging libraries to automatically inject the trace context in the emitted logs,
and provide an easy way to send the logs via OTLP. Instead of
modifying each logging statement, [Appenders](./bridge-api.md#how-to-create-log4j-style-appender)
use the API to bridge logs from existing logging libraries to the OpenTelemetry
Expand All @@ -378,7 +378,7 @@ or simple configuration of a logging library to use an OpenTelemetry appender or
extension will still be the easiest way to emit context-enriched logs. As
already described earlier we provide extensions to some popular logging
libraries languages to support the manual instrumentation cases. The extensions
will support the inclusion of the request context in the logs and allow to send
will support the inclusion of the trace context in the logs and allow to send
logs using OTLP protocol to the backend or to the Collector, bypassing the need
to have the logs represented as text files. Emitted logs are automatically
augmented by application-specific resource context (e.g. process id, programming
Expand Down Expand Up @@ -428,7 +428,7 @@ The following functionality exists to enable log collection:
We can provide auto-instrumentation for most popular logging libraries. The
auto-instrumented logging statements will do the following:

- Read incoming request context (this is part of broader instrumentation that
- Read incoming trace context (this is part of broader instrumentation that
auto-instrumenting libraries perform).

- Configure logging libraries to use trace id and span id fields from request
Expand Down

0 comments on commit def6fc3

Please sign in to comment.