Restructure otel concepts (#1411)
* Restructure otel concepts * fix some links * fix some more links
This commit is contained in:
Severin Neumann
GitHub
parent
c421651825
commit
440510defe
|
|
@ -8,7 +8,7 @@ weight: 200
|
|||
We would like to acknowledge the following sources for some of the content on this site:
|
||||
|
||||
1. [APM is Dying and That's Okay - Lightstep](https://lightstep.com/blog/apm-is-dying-and-thats-okay)
|
||||
2. [Alexandria Pigram](https://github.com/alexandriastech) via [Honeycomb](https://www.honeycomb.io/) for tracing content in [OTel Concepts](/docs/concepts/otel-concepts)
|
||||
2. [Alexandria Pigram](https://github.com/alexandriastech) via [Honeycomb](https://www.honeycomb.io/) for tracing content in [Traces](/docs/concepts/signals/traces/#tracing-in-opentelemetry)
|
||||
3. [What is OpenTelemetry - Dynatrace](https://www.dynatrace.com/news/blog/what-is-opentelemetry-2/)
|
||||
4. [Understanding OpenTracing, OpenCensus, and OpenMetrics - BMC](https://www.bmc.com/blogs/opentracing-opencensus-openmetrics/)
|
||||
5. [Ask Miss O11y: Baggage in OTel - Honeycomb](https://www.honeycomb.io/blog/ask-miss-o11y-opentelemetry-baggage/)
|
||||
|
|
|
|||
|
|
@ -121,8 +121,7 @@ service:
|
|||
<img width="35" src="https://raw.github.com/open-telemetry/opentelemetry.io/main/iconography/32x32/Receivers.svg"></img>
|
||||
|
||||
A receiver, which can be push or pull based, is how data gets into the
|
||||
Collector. Receivers may support one or more [data
|
||||
sources](../../concepts/data-sources).
|
||||
Collector. Receivers may support one or more [data sources](../../concepts/signals).
|
||||
|
||||
The `receivers:` section is how receivers are configured. Many receivers come
|
||||
with default settings so simply specifying the name of the receiver is enough
|
||||
|
|
@ -277,7 +276,7 @@ processors:
|
|||
<img width="35" src="https://raw.github.com/open-telemetry/opentelemetry.io/main/iconography/32x32/Exporters.svg"></img>
|
||||
An exporter, which can be push or pull based, is how you send data to one or
|
||||
more backends/destinations. Exporters may support one or more [data
|
||||
sources](../../concepts/data-sources).
|
||||
sources](../../concepts/signals).
|
||||
|
||||
The `exporters:` section is how exporters are configured. Exporters may come
|
||||
with default settings, but many require configuration to specify at least the
|
||||
|
|
|
|||
|
|
@ -1,16 +0,0 @@
|
|||
---
|
||||
title: Data sources
|
||||
weight: 30
|
||||
---
|
||||
|
||||
In OpenTelemetry, a Data Source refers to the type of data that supported by the
|
||||
specification. It currently supports the Data Sources below, and more may be
|
||||
added in the future.
|
||||
|
||||
- [Traces](/docs/concepts/otel-concepts/#tracing-in-opentelemetry)
|
||||
- [Metrics](/docs/concepts/otel-concepts/#metrics-in-opentelemetry)
|
||||
- [Logs](/docs/concepts/otel-concepts/#logs-in-opentelemetry)
|
||||
- [Baggage](/docs/concepts/otel-concepts/#baggage-in-opentelemetry)
|
||||
|
||||
> For details on each data source, visit
|
||||
> [OTel Concepts](/docs/concepts/otel-concepts)
|
||||
|
|
@ -4,7 +4,7 @@ weight: 90
|
|||
---
|
||||
|
||||
The OpenTelemetry projects consists of multiple [components](../components) that
|
||||
support multiple [data sources](../data-sources). The reference implementation
|
||||
support multiple [signals](../signals). The reference implementation
|
||||
of OpenTelemetry is available as:
|
||||
|
||||
- [Language-specific instrumentation libraries](../instrumenting)
|
||||
|
|
|
|||
|
|
@ -79,8 +79,7 @@ spec][context propagation].
|
|||
|
||||
### **Data Source**
|
||||
|
||||
One of [`Traces`](#trace), [`Metrics`](#metric) or [`Logs`](#log). More on Data
|
||||
Sources [here][data source].
|
||||
See [`Signal`](#signal)
|
||||
|
||||
### **Dimension**
|
||||
|
||||
|
|
@ -276,6 +275,11 @@ A component of an [`Application`](#application). Multiple instances of a
|
|||
[`Service`](#service) are typically deployed for high availability and
|
||||
scalability. A [`Service`](#service) may be deployed in multiple locations.
|
||||
|
||||
### **Signal**
|
||||
|
||||
One of [`Traces`](#trace), [`Metrics`](#metric) or [`Logs`](#log). More on
|
||||
Signals [here][signals].
|
||||
|
||||
### **Span**
|
||||
|
||||
Represents a single operation within a [`Trace`](#trace). See [more][span].
|
||||
|
|
@ -356,14 +360,13 @@ on web pages when requested. See [more][zpages].
|
|||
[context propagation]:
|
||||
/docs/reference/specification/overview#context-propagation
|
||||
[dag]: https://en.wikipedia.org/wiki/Directed_acyclic_graph
|
||||
[data source]: /docs/concepts/data-sources
|
||||
[distributed tracing]: /docs/concepts/otel-concepts/#tracing-in-opentelemetry
|
||||
[distributed tracing]: /docs/concepts/signals/traces/
|
||||
[field]: /docs/reference/specification/logs/data-model#field-kinds
|
||||
[http]: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol
|
||||
[json]: https://en.wikipedia.org/wiki/JSON
|
||||
[log]: /docs/reference/specification/glossary#log
|
||||
[log record]: /docs/reference/specification/glossary#log-record
|
||||
[metric]: /docs/concepts/otel-concepts/#metrics-in-opentelemetry
|
||||
[metric]: /docs/concepts/signals/metrics/
|
||||
[opencensus]: https://opencensus.io
|
||||
[opentracing]: https://opentracing.io
|
||||
[propagators]: /docs/instrumentation/go/manual/#propagators-and-context
|
||||
|
|
@ -372,6 +375,7 @@ on web pages when requested. See [more][zpages].
|
|||
[rest]: https://en.wikipedia.org/wiki/Representational_state_transfer
|
||||
[rpc]: https://en.wikipedia.org/wiki/Remote_procedure_call
|
||||
[sampling]: /docs/reference/specification/trace/sdk#sampling
|
||||
[signals]: /docs/concepts/signals/
|
||||
[span]: /docs/reference/specification/trace/api#span
|
||||
[spans]: /docs/reference/specification/trace/api#add-events
|
||||
[spec-exporter-lib]: /docs/reference/specification/glossary/#exporter-library
|
||||
|
|
|
|||
|
|
@ -14,7 +14,8 @@ allows us to easily troubleshoot and handle novel problems (i.e. "unknown
|
|||
unknowns”), and helps us answer the question, "Why is this happening?"
|
||||
|
||||
In order to be able to ask those questions of a system, the application must be
|
||||
properly instrumented. That is, the application code must emit signals such as
|
||||
properly instrumented. That is, the application code must emit
|
||||
[signals](/docs/concepts/signals/) such as
|
||||
[traces](/docs/concepts/observability-primer/#distributed-traces),
|
||||
[metrics](/docs/concepts/observability-primer/#reliability--metrics), and
|
||||
[logs](/docs/concepts/observability-primer/#logs). An application is properly
|
||||
|
|
@ -78,8 +79,8 @@ that a request makes, painting a picture of what happened during the time in
|
|||
which that operation was executed.
|
||||
|
||||
A Span contains name, time-related data,
|
||||
[structured log messages](/docs/concepts/otel-concepts/#span-events), and
|
||||
[other metadata (i.e. Attributes)](/docs/concepts/otel-concepts/#attributes) to
|
||||
[structured log messages](/docs/concepts/signals/traces/#span-events), and
|
||||
[other metadata (i.e. Attributes)](/docs/concepts/signals/traces/#attributes) to
|
||||
provide information about the operation it tracks.
|
||||
|
||||
Below is a sample of the type of information that would be present in a Span:
|
||||
|
|
@ -87,7 +88,7 @@ Below is a sample of the type of information that would be present in a Span:
|
|||
<img src="/img/span_visualization.png" alt="Sample Span" width="300"/>
|
||||
|
||||
> For more on Spans and how they pertain to OTel, visit
|
||||
> [Advanced OTel Concepts](/docs/concepts/otel-concepts/#spans-in-opentelemetry).
|
||||
> [Spans in OpenTelemetry](/docs/concepts/signals/traces/#spans-in-opentelemetry).
|
||||
|
||||
### Distributed Traces
|
||||
|
||||
|
|
@ -123,4 +124,4 @@ its child Spans. When a Span encapsulates another Span, this also represents a
|
|||
nested relationship.
|
||||
|
||||
> For more on Traces and how they pertain to OTel, visit
|
||||
> [Advanced OTel Concepts](/docs/concepts/otel-concepts/#tracing-in-opentelemetry).
|
||||
> [Traces in OpenTelemetry](/docs/concepts/signals/traces/).
|
||||
|
|
|
|||
|
|
@ -0,0 +1,8 @@
|
|||
---
|
||||
title: Signals
|
||||
weight: 11
|
||||
---
|
||||
|
||||
In OpenTelemetry, a **Signal** refers to the categories of telemetry that are
|
||||
supported by the specification. It currently supports the **Signals** below,
|
||||
and more may be added in the future.
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: "Baggage"
|
||||
description: >-
|
||||
Baggage refers to contextual information that’s passed between spans
|
||||
weight: 4
|
||||
---
|
||||
|
||||
Imagine you want to have a `CustomerId` attribute on every span in your trace,
|
||||
which involves multiple services; however, `CustomerId` is only available in one
|
||||
specific service. To accomplish your goal, you can use OpenTelemetry Baggage to
|
||||
propagate this value across your system.
|
||||
|
||||
In OpenTelemetry, "Baggage" refers to contextual information that’s passed
|
||||
between spans. It's a key-value store that resides within a trace context,
|
||||
making values available to any span created within that trace.
|
||||
|
||||
OpenTelemetry uses [Context Propagation](/docs/concepts/signals/traces/#context-propagation) to pass Baggage
|
||||
around, and each of the different library implementations has propagators that
|
||||
will parse and make that Baggage available without you needing to explicitly
|
||||
implement it.
|
||||
|
||||
|
||||
|
||||
## Why does OTel Baggage exist?
|
||||
|
||||
OpenTelemetry is cross-platform and cross-framework. Baggage makes it such that
|
||||
the context values live in the same place, have the same format, and follow the
|
||||
same pattern. That means that all your applications, no matter what the
|
||||
language, will be able to read them, parse them, and use them. This is important
|
||||
when you’re building a large-scale distributed system, and you want to provide
|
||||
autonomy to teams to work in whatever language or framework they want.
|
||||
|
||||
While it is completely possible to use something else for this (e.g.,
|
||||
standardizing on headers and whatnot, in your organization), it puts the burden
|
||||
on development teams to build helpers in every framework and language, which can
|
||||
unintentionally get neglected when other higher-priority items come up.
|
||||
|
||||
## What OTel Baggage be used for?
|
||||
|
||||
OTel Baggage should be used for non-sensitive data that you're okay with
|
||||
potentially exposing to third parties.
|
||||
|
||||
Common use cases include information that’s only accessible further up a stack.
|
||||
This can include things like Account Identification, User Ids, Product Ids, and
|
||||
origin IPs, for example. Passing these down your stack allows you to then add
|
||||
them to your Spans in downstream services to make it easier to filter when
|
||||
you’re searching in your Observability back-end.
|
||||
|
||||
There are no built-in integrity checks to ensure that the Baggage items are
|
||||
yours, so exercise caution when working with Baggage.
|
||||
|
||||
|
||||
|
||||
## Baggage != Span attributes
|
||||
|
||||
One important thing to note about Baggage is that it is not a subset of the
|
||||
[Span Attributes](/docs/concepts/signals/traces/#attributes). When you add something as Baggage, it does not
|
||||
automatically end up on the Attributes of the child system’s spans. You must
|
||||
explicitly take something out of Baggage and append it as Attributes.
|
||||
|
||||
```csharp
|
||||
var accountId = Baggage.GetBaggage("AccountId");
|
||||
Activity.Current?.SetTag("AccountId", accountId);
|
||||
```
|
||||
|
||||
> For more information, see the [baggage specification][].
|
||||
|
||||
[baggage specification]: /docs/reference/specification/overview/#baggage-signal
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: "Logs"
|
||||
description: >-
|
||||
A log is a timestamped text record, either structured (recommended) or unstructured, with metadata.
|
||||
weight: 3
|
||||
---
|
||||
|
||||
A **log** is a timestamped text record, either structured (recommended) or
|
||||
unstructured, with metadata. While logs are an independent data source, they may
|
||||
also be attached to spans. In OpenTelemetry, any data that is not part of a
|
||||
distributed trace or a metric is a log. For example, _events_ are a specific
|
||||
type of log. Logs are often used to determine the root cause of an issue and
|
||||
typically contain information about who changed what as well as the result of
|
||||
the change.
|
||||
|
||||
> For more information, see the [logs specification][].
|
||||
|
||||
[logs specification]: /docs/reference/specification/overview/#log-signal
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
title: "Metrics"
|
||||
description: >-
|
||||
A metric is a measurement about a service, captured at runtime.
|
||||
weight: 2
|
||||
---
|
||||
|
||||
A **metric** is a measurement about a service, captured at runtime. Logically,
|
||||
the moment of capturing one of these measurements is known as a _metric event_
|
||||
which consists not only of the measurement itself, but the time that it was
|
||||
captured and associated metadata.
|
||||
|
||||
Application and request metrics are important indicators of availability and
|
||||
performance. Custom metrics can provide insights into how availability
|
||||
indicators impact user experience or the business. Collected data can be used to
|
||||
alert of an outage or trigger scheduling decisions to scale up a deployment
|
||||
automatically upon high demand.
|
||||
|
||||
OpenTelemetry defines three _metric instruments_ today:
|
||||
|
||||
- **counter**: a value that is summed over time -- you can think of this like an
|
||||
odometer on a car; it only ever goes up.
|
||||
- **measure**: a value that is aggregated over time. This is more akin to the
|
||||
trip odometer on a car, it represents a value over some defined range.
|
||||
- **observer**: captures a current set of values at a particular point in time,
|
||||
like a fuel gauge in a vehicle.
|
||||
|
||||
In addition to the three metric instruments, the concept of _aggregations_ is an
|
||||
important one to understand. An aggregation is a technique whereby a large
|
||||
number of measurements are combined into either exact or estimated statistics
|
||||
about metric events that took place during a time window. The OpenTelemetry API
|
||||
itself does not allow you to specify these aggregations, but provides some
|
||||
default ones. In general, the OpenTelemetry SDK provides for common aggregations
|
||||
(such as sum, count, last value, and histograms) that are supported by
|
||||
visualizers and telemetry backends.
|
||||
|
||||
Unlike request tracing, which is intended to capture request lifecycles and
|
||||
provide context to the individual pieces of a request, metrics are intended to
|
||||
provide statistical information in aggregate. Some examples of use cases for
|
||||
metrics include:
|
||||
|
||||
- Reporting the total number of bytes read by a service, per protocol type.
|
||||
- Reporting the total number of bytes read and the bytes per request.
|
||||
- Reporting the duration of a system call.
|
||||
- Reporting request sizes in order to determine a trend.
|
||||
- Reporting CPU or memory usage of a process.
|
||||
- Reporting average balance values from an account.
|
||||
- Reporting current active requests being handled.
|
||||
|
||||
> For more information, see the [metrics specification][].
|
||||
|
||||
[metrics specification]: /docs/reference/specification/overview/#metric-signal
|
||||
|
|
@ -1,117 +1,10 @@
|
|||
---
|
||||
title: "OTel Concepts"
|
||||
weight: 11
|
||||
title: "Traces"
|
||||
description: >-
|
||||
Traces give us the big picture of what happens when a request is made by user or an application.
|
||||
weight: 1
|
||||
---
|
||||
|
||||
This page dives into OpenTelemetry concepts.
|
||||
|
||||
## Spans in OpenTelemetry
|
||||
|
||||
A [**Span**](/docs/concepts/observability-primer/#spans) represents a unit of
|
||||
work or operation. Spans are the building blocks of Traces. In OpenTelemetry,
|
||||
they include the following information:
|
||||
|
||||
- Name
|
||||
- Start and End Timestamps
|
||||
- [Span Context](#span-context)
|
||||
- [Attributes](#attributes)
|
||||
- [Span Events](#span-events)
|
||||
- [Span Links](#span-links)
|
||||
- [Span Status](#span-status)
|
||||
|
||||
Sample Span:
|
||||
|
||||
```json
|
||||
{
|
||||
"trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
|
||||
"parent_id": "",
|
||||
"span_id": "086e83747d0e381e",
|
||||
"name": "/v1/sys/health",
|
||||
"start_time": "2021-10-22 16:04:01.209458162 +0000 UTC",
|
||||
"end_time": "2021-10-22 16:04:01.209514132 +0000 UTC",
|
||||
"status_code": "STATUS_CODE_OK",
|
||||
"status_message": "",
|
||||
"attributes": {
|
||||
"net.transport": "IP.TCP",
|
||||
"net.peer.ip": "172.17.0.1",
|
||||
"net.peer.port": "51820",
|
||||
"net.host.ip": "10.177.2.152",
|
||||
"net.host.port": "26040",
|
||||
"http.method": "GET",
|
||||
"http.target": "/v1/sys/health",
|
||||
"http.server_name": "mortar-gateway",
|
||||
"http.route": "/v1/sys/health",
|
||||
"http.user_agent": "Consul Health Check",
|
||||
"http.scheme": "http",
|
||||
"http.host": "10.177.2.152:26040",
|
||||
"http.flavor": "1.1"
|
||||
},
|
||||
"events": {
|
||||
"name": "",
|
||||
"message": "OK",
|
||||
"timestamp": "2021-10-22 16:04:01.209512872 +0000 UTC"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Span Context
|
||||
|
||||
Span Context provides specific context about the trace and span using two
|
||||
identifiers: Trace ID and Span ID. Each Span is identified by an ID that is
|
||||
unique within a Trace called a Span ID. A Span uses a Trace ID to identify the
|
||||
relationship between span and its trace. A string represents the Span ID. A Span
|
||||
requires Span Context to travel across service and process boundaries.
|
||||
|
||||
### Attributes
|
||||
|
||||
Attributes are key-value pairs that contain metadata that you can use to
|
||||
annotate a Span to carry information about the operation it is tracking.
|
||||
|
||||
### Span Events
|
||||
|
||||
A Span Event can be thought of as a structured log message (or annotation) on a
|
||||
Span, provides additional context on what is occurring during a specific
|
||||
operation.
|
||||
|
||||
For example, a critical path in a multi-threaded application might need to
|
||||
acquire a lock on a mutex to have exclusive access to a resource. An Event can
|
||||
be created at two points: once when the resource is acquired, and once when it
|
||||
is released.
|
||||
|
||||
### Span Links
|
||||
|
||||
Links exist so that you can associate one span with one or more spans, implying
|
||||
a causal relationship. For example, let’s say we have a distributed system where
|
||||
some operations are tracked by a trace.
|
||||
|
||||
In response to some of these operations, an additional operation is queued to be
|
||||
executed, but its execution is asynchronous. We can track this subsequent
|
||||
operation with a trace as well.
|
||||
|
||||
We would like to associate the trace for the subsequent operations with the
|
||||
first trace, but we cannot predict when the subsequent operations will start. We
|
||||
need to associate these two traces, so we will use a span link.
|
||||
|
||||
You can link the last span from the first trace to the first span in the second
|
||||
trace. Now, they are causally associated with one another.
|
||||
|
||||
Links are optional but serve as a good way to associate trace spans with one
|
||||
another.
|
||||
|
||||
### Span Status
|
||||
|
||||
A status will be attached to a span. Typically, you will set a span status when
|
||||
there is a known error in the application code, such as an exception. A Span
|
||||
Status will be tagged as one of the following values:
|
||||
|
||||
- `Unset`
|
||||
- `Ok`
|
||||
- `Error`
|
||||
|
||||
When an exception is handled, a Span status can be set to Error. Otherwise, a
|
||||
Span status is in the Unset state. By setting a Span status to Unset, the
|
||||
back-end that processes spans can now assign a final status.
|
||||
|
||||
## Tracing in OpenTelemetry
|
||||
|
||||
[**Traces**](/docs/concepts/observability-primer/#distributed-traces) give us
|
||||
|
|
@ -279,127 +172,111 @@ By combining Context and Propagation, you now can assemble a Trace.
|
|||
|
||||
> For more information, see the [traces specification][]
|
||||
|
||||
## Metrics in OpenTelemetry
|
||||
[traces specification]: /docs/reference/specification/overview/#tracing-signal
|
||||
|
||||
A **metric** is a measurement about a service, captured at runtime. Logically,
|
||||
the moment of capturing one of these measurements is known as a _metric event_
|
||||
which consists not only of the measurement itself, but the time that it was
|
||||
captured and associated metadata.
|
||||
## Spans in OpenTelemetry
|
||||
|
||||
Application and request metrics are important indicators of availability and
|
||||
performance. Custom metrics can provide insights into how availability
|
||||
indicators impact user experience or the business. Collected data can be used to
|
||||
alert of an outage or trigger scheduling decisions to scale up a deployment
|
||||
automatically upon high demand.
|
||||
A [**Span**](/docs/concepts/observability-primer/#spans) represents a unit of
|
||||
work or operation. Spans are the building blocks of Traces. In OpenTelemetry,
|
||||
they include the following information:
|
||||
|
||||
OpenTelemetry defines three _metric instruments_ today:
|
||||
- Name
|
||||
- Start and End Timestamps
|
||||
- [Span Context](#span-context)
|
||||
- [Attributes](#attributes)
|
||||
- [Span Events](#span-events)
|
||||
- [Span Links](#span-links)
|
||||
- [Span Status](#span-status)
|
||||
|
||||
- **counter**: a value that is summed over time -- you can think of this like an
|
||||
odometer on a car; it only ever goes up.
|
||||
- **measure**: a value that is aggregated over time. This is more akin to the
|
||||
trip odometer on a car, it represents a value over some defined range.
|
||||
- **observer**: captures a current set of values at a particular point in time,
|
||||
like a fuel gauge in a vehicle.
|
||||
Sample Span:
|
||||
|
||||
In addition to the three metric instruments, the concept of _aggregations_ is an
|
||||
important one to understand. An aggregation is a technique whereby a large
|
||||
number of measurements are combined into either exact or estimated statistics
|
||||
about metric events that took place during a time window. The OpenTelemetry API
|
||||
itself does not allow you to specify these aggregations, but provides some
|
||||
default ones. In general, the OpenTelemetry SDK provides for common aggregations
|
||||
(such as sum, count, last value, and histograms) that are supported by
|
||||
visualizers and telemetry backends.
|
||||
|
||||
Unlike request tracing, which is intended to capture request lifecycles and
|
||||
provide context to the individual pieces of a request, metrics are intended to
|
||||
provide statistical information in aggregate. Some examples of use cases for
|
||||
metrics include:
|
||||
|
||||
- Reporting the total number of bytes read by a service, per protocol type.
|
||||
- Reporting the total number of bytes read and the bytes per request.
|
||||
- Reporting the duration of a system call.
|
||||
- Reporting request sizes in order to determine a trend.
|
||||
- Reporting CPU or memory usage of a process.
|
||||
- Reporting average balance values from an account.
|
||||
- Reporting current active requests being handled.
|
||||
|
||||
> For more information, see the [metrics specification][].
|
||||
|
||||
## Logs in OpenTelemetry
|
||||
|
||||
A **log** is a timestamped text record, either structured (recommended) or
|
||||
unstructured, with metadata. While logs are an independent data source, they may
|
||||
also be attached to spans. In OpenTelemetry, any data that is not part of a
|
||||
distributed trace or a metric is a log. For example, _events_ are a specific
|
||||
type of log. Logs are often used to determine the root cause of an issue and
|
||||
typically contain information about who changed what as well as the result of
|
||||
the change.
|
||||
|
||||
> For more information, see the [logs specification][].
|
||||
|
||||
## Baggage in OpenTelemetry
|
||||
|
||||
Imagine you want to have a `CustomerId` attribute on every span in your trace,
|
||||
which involves multiple services; however, `CustomerId` is only available in one
|
||||
specific service. To accomplish your goal, you can use OpenTelemetry Baggage to
|
||||
propagate this value across your system.
|
||||
|
||||
In OpenTelemetry, "Baggage" refers to contextual information that’s passed
|
||||
between spans. It's a key-value store that resides within a trace context,
|
||||
making values available to any span created within that trace.
|
||||
|
||||
OpenTelemetry uses [Context Propagation](#context-propagation) to pass Baggage
|
||||
around, and each of the different library implementations has propagators that
|
||||
will parse and make that Baggage available without you needing to explicitly
|
||||
implement it.
|
||||
|
||||
|
||||
|
||||
### Why does OTel Baggage exist?
|
||||
|
||||
OpenTelemetry is cross-platform and cross-framework. Baggage makes it such that
|
||||
the context values live in the same place, have the same format, and follow the
|
||||
same pattern. That means that all your applications, no matter what the
|
||||
language, will be able to read them, parse them, and use them. This is important
|
||||
when you’re building a large-scale distributed system, and you want to provide
|
||||
autonomy to teams to work in whatever language or framework they want.
|
||||
|
||||
While it is completely possible to use something else for this (e.g.,
|
||||
standardizing on headers and whatnot, in your organization), it puts the burden
|
||||
on development teams to build helpers in every framework and language, which can
|
||||
unintentionally get neglected when other higher-priority items come up.
|
||||
|
||||
### What OTel Baggage be used for?
|
||||
|
||||
OTel Baggage should be used for non-sensitive data that you're okay with
|
||||
potentially exposing to third parties.
|
||||
|
||||
Common use cases include information that’s only accessible further up a stack.
|
||||
This can include things like Account Identification, User Ids, Product Ids, and
|
||||
origin IPs, for example. Passing these down your stack allows you to then add
|
||||
them to your Spans in downstream services to make it easier to filter when
|
||||
you’re searching in your Observability back-end.
|
||||
|
||||
There are no built-in integrity checks to ensure that the Baggage items are
|
||||
yours, so exercise caution when working with Baggage.
|
||||
|
||||
|
||||
|
||||
### Baggage != Span attributes
|
||||
|
||||
One important thing to note about Baggage is that it is not a subset of the
|
||||
[Span Attributes](#attributes). When you add something as Baggage, it does not
|
||||
automatically end up on the Attributes of the child system’s spans. You must
|
||||
explicitly take something out of Baggage and append it as Attributes.
|
||||
|
||||
```csharp
|
||||
var accountId = Baggage.GetBaggage("AccountId");
|
||||
Activity.Current?.SetTag("AccountId", accountId);
|
||||
```json
|
||||
{
|
||||
"trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
|
||||
"parent_id": "",
|
||||
"span_id": "086e83747d0e381e",
|
||||
"name": "/v1/sys/health",
|
||||
"start_time": "2021-10-22 16:04:01.209458162 +0000 UTC",
|
||||
"end_time": "2021-10-22 16:04:01.209514132 +0000 UTC",
|
||||
"status_code": "STATUS_CODE_OK",
|
||||
"status_message": "",
|
||||
"attributes": {
|
||||
"net.transport": "IP.TCP",
|
||||
"net.peer.ip": "172.17.0.1",
|
||||
"net.peer.port": "51820",
|
||||
"net.host.ip": "10.177.2.152",
|
||||
"net.host.port": "26040",
|
||||
"http.method": "GET",
|
||||
"http.target": "/v1/sys/health",
|
||||
"http.server_name": "mortar-gateway",
|
||||
"http.route": "/v1/sys/health",
|
||||
"http.user_agent": "Consul Health Check",
|
||||
"http.scheme": "http",
|
||||
"http.host": "10.177.2.152:26040",
|
||||
"http.flavor": "1.1"
|
||||
},
|
||||
"events": {
|
||||
"name": "",
|
||||
"message": "OK",
|
||||
"timestamp": "2021-10-22 16:04:01.209512872 +0000 UTC"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> For more information, see the [baggage specification][].
|
||||
### Span Context
|
||||
|
||||
[baggage specification]: /docs/reference/specification/overview/#baggage-signal
|
||||
[logs specification]: /docs/reference/specification/overview/#log-signal
|
||||
[metrics specification]: /docs/reference/specification/overview/#metric-signal
|
||||
[traces specification]: /docs/reference/specification/overview/#tracing-signal
|
||||
Span Context provides specific context about the trace and span using two
|
||||
identifiers: Trace ID and Span ID. Each Span is identified by an ID that is
|
||||
unique within a Trace called a Span ID. A Span uses a Trace ID to identify the
|
||||
relationship between span and its trace. A string represents the Span ID. A Span
|
||||
requires Span Context to travel across service and process boundaries.
|
||||
|
||||
### Attributes
|
||||
|
||||
Attributes are key-value pairs that contain metadata that you can use to
|
||||
annotate a Span to carry information about the operation it is tracking.
|
||||
|
||||
### Span Events
|
||||
|
||||
A Span Event can be thought of as a structured log message (or annotation) on a
|
||||
Span, provides additional context on what is occurring during a specific
|
||||
operation.
|
||||
|
||||
For example, a critical path in a multi-threaded application might need to
|
||||
acquire a lock on a mutex to have exclusive access to a resource. An Event can
|
||||
be created at two points: once when the resource is acquired, and once when it
|
||||
is released.
|
||||
|
||||
### Span Links
|
||||
|
||||
Links exist so that you can associate one span with one or more spans, implying
|
||||
a causal relationship. For example, let’s say we have a distributed system where
|
||||
some operations are tracked by a trace.
|
||||
|
||||
In response to some of these operations, an additional operation is queued to be
|
||||
executed, but its execution is asynchronous. We can track this subsequent
|
||||
operation with a trace as well.
|
||||
|
||||
We would like to associate the trace for the subsequent operations with the
|
||||
first trace, but we cannot predict when the subsequent operations will start. We
|
||||
need to associate these two traces, so we will use a span link.
|
||||
|
||||
You can link the last span from the first trace to the first span in the second
|
||||
trace. Now, they are causally associated with one another.
|
||||
|
||||
Links are optional but serve as a good way to associate trace spans with one
|
||||
another.
|
||||
|
||||
### Span Status
|
||||
|
||||
A status will be attached to a span. Typically, you will set a span status when
|
||||
there is a known error in the application code, such as an exception. A Span
|
||||
Status will be tagged as one of the following values:
|
||||
|
||||
- `Unset`
|
||||
- `Ok`
|
||||
- `Error`
|
||||
|
||||
When an exception is handled, a Span status can be set to Error. Otherwise, a
|
||||
Span status is in the Unset state. By setting a Span status to Unset, the
|
||||
back-end that processes spans can now assign a final status.
|
||||
|
|
@ -9,7 +9,7 @@ libraries](/docs/reference/specification/glossary/#instrumentation-library) that
|
|||
generate telemetry data for a particular instrumented library.
|
||||
|
||||
For example, the instrumentation library for ASP.NET Core will automatically
|
||||
create [spans](/docs/concepts/otel-concepts#spans-in-opentelemetry) that track
|
||||
create [spans](/docs/concepts/signals/traces/#spans-in-opentelemetry) that track
|
||||
inbound requests once you configure it in your app/service.
|
||||
|
||||
## Setup
|
||||
|
|
@ -23,7 +23,7 @@ dotnet add package OpenTelemetry.Instrumentation.{library-name-or-type}
|
|||
|
||||
It is typically then registered at application startup time, such as when
|
||||
creating a
|
||||
[TracerProvider](/docs/concepts/otel-concepts#tracing-in-opentelemetry).
|
||||
[TracerProvider](/docs/concepts/signals/traces/#tracer-provider).
|
||||
|
||||
## Example with ASP.NET Core and HttpClient
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ weight: 4
|
|||
---
|
||||
|
||||
In order to visualize and analyze your
|
||||
[traces](/docs/concepts/otel-concepts#tracing-in-opentelemetry) and metrics, you
|
||||
[traces](/docs/concepts/signals/traces/#tracing-in-opentelemetry) and metrics, you
|
||||
will need to export them to a backend.
|
||||
|
||||
## Console exporter
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ dotnet add package OpenTelemetry
|
|||
## Console application
|
||||
|
||||
The following sample demonstrates manual
|
||||
[tracing](/docs/concepts/otel-concepts#tracing-in-opentelemetry) via a console
|
||||
[tracing](/docs/concepts/signals/traces/#tracing-in-opentelemetry) via a console
|
||||
app.
|
||||
|
||||
First, install the required package:
|
||||
|
|
@ -64,7 +64,7 @@ activity?.SetTag("baz", new int[] { 1, 2, 3 });
|
|||
```
|
||||
|
||||
The code will generate a single
|
||||
[span](/docs/concepts/otel-concepts#spans-in-opentelemetry) like this:
|
||||
[span](/docs/concepts/signals/traces/#spans-in-opentelemetry) like this:
|
||||
|
||||
```
|
||||
Activity.Id: 00-cf0e89a41682d0cc7a132277da6a45d6-c714dd3b15e21378-01
|
||||
|
|
@ -88,7 +88,7 @@ This output matches the span created in the preceding code sample.
|
|||
## ASP.NET Core
|
||||
|
||||
The following sample demonstrates automatic and manual
|
||||
[tracing](/docs/concepts/otel-concepts#tracing-in-opentelemetry) with ASP.NET
|
||||
[tracing](/docs/concepts/signals/traces/#tracing-in-opentelemetry) with ASP.NET
|
||||
Core.
|
||||
|
||||
First, install requried packages:
|
||||
|
|
@ -147,7 +147,7 @@ app.Run();
|
|||
```
|
||||
|
||||
When you run the app and navigate to the `/hello` route, you'll see output about
|
||||
[spans](/docs/concepts/otel-concepts#spans-in-opentelemetry) similar to the
|
||||
[spans](/docs/concepts/signals/traces/#spans-in-opentelemetry) similar to the
|
||||
following:
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ application.
|
|||
## A note on terminology
|
||||
|
||||
.NET is different from other languages/runtimes that support OpenTelemetry.
|
||||
[Tracing](/docs/concepts/otel-concepts#tracing-in-opentelemetry) is implemented
|
||||
[Tracing](/docs/concepts/signals/traces/#tracing-in-opentelemetry) is implemented
|
||||
by the
|
||||
[System.Diagnostics](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics)
|
||||
API, repurposing existing constructs like `ActivitySource` and `Activity` to be
|
||||
|
|
@ -27,7 +27,7 @@ you can refer to the [OpenTelemetry API Shim docs for tracing]({{< relref "shim"
|
|||
## Initializing tracing
|
||||
|
||||
There are two main ways to initialize
|
||||
[tracing](/docs/concepts/otel-concepts#tracing-in-opentelemetry), depending on
|
||||
[tracing](/docs/concepts/signals/traces/#tracing-in-opentelemetry), depending on
|
||||
whether you're using a console app or something that's ASP.NET Core-based.
|
||||
|
||||
### Console app
|
||||
|
|
@ -118,9 +118,9 @@ endpoint, you'll have to use a different exporter.
|
|||
## Setting up an ActivitySource
|
||||
|
||||
Once tracing is initialized, you can configure an
|
||||
[`ActivitySource`](/docs/concepts/otel-concepts#tracer), which will be how you
|
||||
[`ActivitySource`](/docs/concepts/signals/traces/#tracer), which will be how you
|
||||
trace operations with
|
||||
[`Activity`s](/docs/concepts/otel-concepts#spans-in-opentelemetry).
|
||||
[`Activity`s](/docs/concepts/signals/traces/#spans-in-opentelemetry).
|
||||
|
||||
Typically, an `ActivitySource` is instantiated once per app/service that is
|
||||
being instrumented, so it's a good idea to instantiate it once in a shared
|
||||
|
|
@ -146,9 +146,9 @@ although it is generally sufficient to just have one defined per service.
|
|||
|
||||
## Creating Activities
|
||||
|
||||
To create an [`Activity`](/docs/concepts/otel-concepts#spans-in-opentelemetry),
|
||||
To create an [`Activity`](/docs/concepts/signals/traces/#spans-in-opentelemetry),
|
||||
give it a name and create it from your
|
||||
[`ActivitySource`](/docs/concepts/otel-concepts#tracer).
|
||||
[`ActivitySource`](/docs/concepts/signals/traces/#tracer).
|
||||
|
||||
```csharp
|
||||
using var myActivity = MyActivitySource.StartActivity("SayHello");
|
||||
|
|
@ -225,7 +225,7 @@ Note that `using` is not used in the prior example. Doing so will end current
|
|||
|
||||
## Add tags to an Activity
|
||||
|
||||
Tags (the equivalent of [`Attributes`](/docs/concepts/otel-concepts#attributes)
|
||||
Tags (the equivalent of [`Attributes`](/docs/concepts/signals/traces/#attributes)
|
||||
in OpenTelemetry) let you attach key/value pairs to an `Activity` so it carries
|
||||
more information about the current operation that it's tracking.
|
||||
|
||||
|
|
@ -239,7 +239,7 @@ activity?.SetTag("operation.other-stuff", new int[] { 1, 2, 3 });
|
|||
|
||||
## Adding events
|
||||
|
||||
An [event](/docs/concepts/otel-concepts#span-events) is a human-readable message
|
||||
An [event](/docs/concepts/signals/traces/#span-events) is a human-readable message
|
||||
on an `Activity` that represents "something happening" during its lifetime. You
|
||||
can think of it like a primitive log.
|
||||
|
||||
|
|
@ -279,7 +279,7 @@ myActivity?.AddEvent(new("Gonna try it!", DateTimeOffset.Now, new(eventTags)));
|
|||
## Adding links
|
||||
|
||||
An `Activity` can be created with zero or more
|
||||
[`ActivityLink`s](/docs/concepts/otel-concepts#span-links) that are causally
|
||||
[`ActivityLink`s](/docs/concepts/signals/traces/#span-links) that are causally
|
||||
related.
|
||||
|
||||
```csharp
|
||||
|
|
@ -302,7 +302,7 @@ using var anotherActivity =
|
|||
|
||||
## Set Activity status
|
||||
|
||||
A [status](/docs/concepts/otel-concepts#span-status) can be set on an activity,
|
||||
A [status](/docs/concepts/signals/traces/#span-status) can be set on an activity,
|
||||
typically used to specify that an activity has not completed successfully -
|
||||
`ActivityStatusCode.Error`. In rare scenarios, you could override the `Error`
|
||||
status with `Ok`, but don't set `Ok` on successfully-completed spans.
|
||||
|
|
|
|||
|
|
@ -19,12 +19,12 @@ terminology consistent with the OpenTelemetry spec.
|
|||
## Initializing tracing
|
||||
|
||||
There are two main ways to initialize
|
||||
[tracing](/docs/concepts/otel-concepts#tracing-in-opentelemetry), depending on
|
||||
[tracing](/docs/concepts/signals/traces/#tracing-in-opentelemetry), depending on
|
||||
whether you're using a console app or something that's ASP.NET Core-based.
|
||||
|
||||
### Console app
|
||||
|
||||
To start [tracing](/docs/concepts/otel-concepts#tracing-in-opentelemetry) in a
|
||||
To start [tracing](/docs/concepts/signals/traces/#tracing-in-opentelemetry) in a
|
||||
console app, you need to create a tracer provider.
|
||||
|
||||
First, ensure that you have the right packages:
|
||||
|
|
@ -65,7 +65,7 @@ endpoint, you'll have to use a different exporter.
|
|||
|
||||
### ASP.NET Core
|
||||
|
||||
To start [tracing](/docs/concepts/otel-concepts#tracing-in-opentelemetry) in an
|
||||
To start [tracing](/docs/concepts/signals/traces/#tracing-in-opentelemetry) in an
|
||||
ASP.NET Core-based app, use the OpenTelemetry extensions for ASP.NET Core setup.
|
||||
|
||||
First, ensure that you have the right packages:
|
||||
|
|
@ -105,7 +105,7 @@ builder.Services.AddOpenTelemetryTracing(b =>
|
|||
.AddSingleton(TracerProvider.Default.GetTracer(serviceName)));
|
||||
```
|
||||
|
||||
In the preceding example, a [`Tracer`](/docs/concepts/otel-concepts#tracer)
|
||||
In the preceding example, a [`Tracer`](/docs/concepts/signals/traces/#tracer)
|
||||
corresponding to the service is injected during setup. This lets you get access
|
||||
to an instance in your endpoint mapping (or controllers if you're using an older
|
||||
version of .NET).
|
||||
|
|
@ -122,8 +122,8 @@ endpoint, you'll have to use a different exporter.
|
|||
## Setting up a tracer
|
||||
|
||||
Once tracing is initialized, you can configure a
|
||||
[`Tracer`](/docs/concepts/otel-concepts#tracer), which will be how you trace
|
||||
operations with [`Span`s](/docs/concepts/otel-concepts#spans-in-opentelemetry).
|
||||
[`Tracer`](/docs/concepts/signals/traces/#tracer), which will be how you trace
|
||||
operations with [`Span`s](/docs/concepts/signals/traces/#spans-in-opentelemetry).
|
||||
|
||||
Typically, a `Tracer` is instantiated once per app/service that is being
|
||||
instrumented, so it's a good idea to instantiate it once in a shared location.
|
||||
|
|
@ -159,7 +159,7 @@ app.MapGet("/hello", (Tracer tracer) =>
|
|||
|
||||
If you're not using ASP.NET Core or would rather not inject an instance of a
|
||||
`Tracer`, create one from your instantialized
|
||||
[`TracerProvider`](/docs/concepts/otel-concepts#tracer-provider):
|
||||
[`TracerProvider`](/docs/concepts/signals/traces/#tracer-provider):
|
||||
|
||||
```csharp
|
||||
// ...
|
||||
|
|
@ -179,7 +179,7 @@ generally sufficient to just have one defined per service.
|
|||
|
||||
## Creating Spans
|
||||
|
||||
To create a [span](/docs/concepts/otel-concepts#spans-in-opentelemetry), give it
|
||||
To create a [span](/docs/concepts/signals/traces/#spans-in-opentelemetry), give it
|
||||
a name and create it from your `Tracer`.
|
||||
|
||||
```csharp
|
||||
|
|
@ -258,7 +258,7 @@ behavior.
|
|||
|
||||
## Add Attributes to a Span
|
||||
|
||||
[Attributes](/docs/concepts/otel-concepts#attributes) let you attach key/value
|
||||
[Attributes](/docs/concepts/signals/traces/#attributes) let you attach key/value
|
||||
pairs to a `TelemetrySpan` so it carries more information about the current
|
||||
operation that it's tracking.
|
||||
|
||||
|
|
@ -272,7 +272,7 @@ span.SetAttribute("operation.other-stuff", new int[] { 1, 2, 3 });
|
|||
|
||||
## Adding events
|
||||
|
||||
An [event](/docs/concepts/otel-concepts#span-events) is a human-readable message
|
||||
An [event](/docs/concepts/signals/traces/#span-events) is a human-readable message
|
||||
on an `TelemetrySpan` that represents "something happening" during its lifetime.
|
||||
You can think of it like a primitive log.
|
||||
|
||||
|
|
@ -289,7 +289,7 @@ span.AddEvent("Dit it!");
|
|||
```
|
||||
|
||||
Events can also be created with a timestamp and a collection of
|
||||
[attributes](/docs/concepts/otel-concepts#attributes).
|
||||
[attributes](/docs/concepts/signals/traces/#attributes).
|
||||
|
||||
```csharp
|
||||
using var span = tracer.StartActiveSpan("SayHello");
|
||||
|
|
@ -314,7 +314,7 @@ span.AddEvent("asdf", DateTimeOffset.Now, new(attributeData));
|
|||
## Adding links
|
||||
|
||||
A `TelemetrySpan` can be created with zero or more
|
||||
[`Link`s](/docs/concepts/otel-concepts#span-links) that are causally related.
|
||||
[`Link`s](/docs/concepts/signals/traces/#span-links) that are causally related.
|
||||
|
||||
```csharp
|
||||
// Get a context from somewhere, perhaps it's passed in as a parameter
|
||||
|
|
@ -332,7 +332,7 @@ using var span = tracer.StartActiveSpan("another-span", links: links);
|
|||
|
||||
## Set span status
|
||||
|
||||
A [status](/docs/concepts/otel-concepts#span-status) can be set on a span,
|
||||
A [status](/docs/concepts/signals/traces/#span-status) can be set on a span,
|
||||
typically used to specify that a span has not completed successfully -
|
||||
`Status.Error`. In rare scenarios, you could override the `Error` status with
|
||||
`Ok`, but don't set `Ok` on successfully-completed spans.
|
||||
|
|
|
|||
Loading…
Reference in New Issue