Skip to content

Commit

Permalink
Describe in-band and out-of-band terms (#714)
Browse files Browse the repository at this point in the history
* Describe in-band and out-of-band terms

Signed-off-by: Yuri Shkuro <ys@uber.com>

* move anchors

Signed-off-by: Yuri Shkuro <ys@uber.com>

* Update specification/glossary.md

Co-authored-by: Christian Neumüller <christian+github@neumueller.me>

* Fix language

* Move to the top

Signed-off-by: Yuri Shkuro <ys@uber.com>

* Fix anchors

* Re-add anchor

Signed-off-by: Yuri Shkuro <ys@uber.com>

* fix link

Co-authored-by: Christian Neumüller <christian+github@neumueller.me>
  • Loading branch information
2 people authored and Alex Boten committed Jul 20, 2020
1 parent eb29f6f commit 82386cf
Showing 1 changed file with 30 additions and 13 deletions.
43 changes: 30 additions & 13 deletions specification/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,32 +5,48 @@ specification.

## Common

<a name="in-band"></a>
<a name="out-of-band"></a>
### In-band and Out-of-band Data

> In telecommunications, **in-band signaling** is the sending of control information within the same band or channel used for data such as voice or video. This is in contrast to **out-of-band signaling** which is sent over a different channel, or even over a separate network ([Wikipedia](https://en.wikipedia.org/wiki/In-band_signaling)).
In OpenTelemetry we refer to **in-band data** as data that is passed
between components of a distributed system as part of business messages,
for example, when trace or correlation contexts are included
in the HTTP requests in the form of HTTP headers.
Such data usually does not contain the telemetry,
but is used to correlate and join the telemetry produced by various components.
The telemetry itself is referred to as **out-of-band data**:
it is transmitted from applications via dedicated messages,
usually asynchronously by background routines
rather than from the critical path of the business logic.
Metrics, logs, and traces exported to telemetry backends are examples of out-of-band data.

<a name="telemetry_sdk"></a>
### Telemetry SDK

Denotes the library that implements the *OpenTelemetry API*.

See [Library Guidelines](library-guidelines.md#sdk-implementation) and
[Library resource semantic conventions](resource/semantic_conventions/README.md#telemetry-sdk)

<a name="telemetry_sdk"></a>
[Library resource semantic conventions](resource/semantic_conventions/README.md#telemetry-sdk).

<a name="exporter_library"></a>
### Exporter Library

Libraries which are compatible with the [Telemetry SDK](glossary.md#telemetry-sdk) and provide functionality to emit telemetry to consumers.

<a name="exporter_library"></a>
Libraries which are compatible with the [Telemetry SDK](#telemetry-sdk) and provide functionality to emit telemetry to consumers.

### Instrumented Library

Denotes the library for which the telemetry signals (traces, metrics, logs) are gathered.

The calls to the OpenTelemetry API can be done either by the Instrumented Library itself,
or by another [Instrumenting Library](#instrumenting_library).
or by another [Instrumentation Library](#instrumentation-library).

Example: `org.mongodb.client`.

<a name="instrumenting_library"></a>

<a name="instrumentation_library"></a>
### Instrumentation Library

Denotes the library that provides the instrumentation for a given [Instrumented Library](#instrumented-library).
Expand All @@ -41,14 +57,15 @@ See [Overview](overview.md#instrumentation-libraries) for a more detailed defini

Example: `io.opentelemetry.contrib.mongodb`.

Synonyms: *Instrumenting Library*

<a name="instrumentation_library"></a>
Synonyms: *Instrumenting Library*.

<a name="tracer-name"></a>
<a name="meter-name"></a>
### Tracer Name / Meter Name

This refers to the `name` and (optional) `version` arguments specified when
creating a new `Tracer` or `Meter` (see [Obtaining a Tracer](trace/api.md#obtaining-a-tracer)/[Obtaining a Meter](metrics/api.md#meter-interface)). It identifies the [Instrumenting Library](#instrumenting_library).
creating a new `Tracer` or `Meter` (see [Obtaining a Tracer](trace/api.md#obtaining-a-tracer)/[Obtaining a Meter](metrics/api.md#meter-interface)).
The name/version pair identifies the [Instrumentation Library](#instrumentation-library).

## Logs

Expand All @@ -58,7 +75,7 @@ A recording of an event. Typically the record includes a timestamp indicating
when the event happened as well as other data that describes what happened,
where it happened, etc.

Also known as Log Entry.
Synonyms: *Log Entry*.

### Log

Expand Down

0 comments on commit 82386cf

Please sign in to comment.