open-telemetry · carlosalberto · Jan 20, 2021 · Dec 14, 2020 · Dec 14, 2020 · Dec 14, 2020
diff --git a/internal/img/api-lifecycle.png b/internal/img/api-lifecycle.png
diff --git a/internal/img/architecture.png b/internal/img/architecture.png
diff --git a/internal/img/long-term-support.png b/internal/img/long-term-support.png
diff --git a/specification/glossary.md b/specification/glossary.md
@@ -8,7 +8,13 @@ Some other fundamental terms are documented in the [overview document](overview.
 
 <!-- toc -->
 
+- [User Roles](#user-roles)
+  * [Application Owner](#application-owner)
+  * [Library Author](#library-author)
+  * [Instrumentation Author](#instrumentation-author)
+  * [Plugin Author](#plugin-author)
 - [Common](#common)
+  * [Signals](#signals)
   * [In-band and Out-of-band Data](#in-band-and-out-of-band-data)
   * [Telemetry SDK](#telemetry-sdk)
   * [Exporter Library](#exporter-library)
@@ -26,8 +32,30 @@ Some other fundamental terms are documented in the [overview document](overview.
 
 <!-- tocstop -->
 
+## User Roles
+
+### Application Owner
+
+The maintainer of an application or service, responsible for configuring and managing the lifecycle of the OpenTelemetry SDK.
+
+### Library Author
+
+The maintainer of a shared library which is depended upon by many applications, and targeted by OpenTelemetry instrumentation.
+
+### Instrumentation Author
+
+The maintainer of OpenTelemetry instrumentation written against the OpenTelemetry API. This may be instrumentation written within application code, within a shared library, or within an instrumentation library.
+
+### Plugin Author
+
+The maintainer of an OpenTelemetry SDK Plugin, written against OpenTelemetry SDK plugin interfaces.
+
 ## Common
 
+### Signals
+
+OpenTelemetry is structured around signals, or categories of telemetry. Metrics, logs, traces, and baggage are examples of signals. Each signal represents a coherent, stand-alone set of functionality. Each signal follows a separate lifecycle defining its current stability level.
+
 <a name="in-band"></a>
 <a name="out-of-band"></a>
 
@@ -54,9 +82,17 @@ 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).
 
+### Constructors
+
+Constructors are public code used by Application Owners to initialize and configure the OpenTelemetry SDK and contrib packages. Examples of constructors include configuration objects, environment variables, and builders.
+
+### SDK Plugins
+
+Plugins are libraries which extend the OpenTelemetry SDK Examples of plugin interfaces include the `SpanProcessor`, `Exporter`, and `Sampler` interfaces.
+
 ### Exporter Library
 
-Libraries which are compatible with the [Telemetry SDK](#telemetry-sdk) and provide functionality to emit telemetry to consumers.
+Exporters are SDK Plugins which implement the `Exporter` interface, and emit telemetry to consumers.
 
 ### Instrumented Library
 

diff --git a/specification/overview.md b/specification/overview.md
@@ -8,6 +8,11 @@ Table of Contents
 
 <!-- toc -->
 
+- [OpenTelemetry Architecture](#opentelemetry-architecture)
+  * [API](#api)
+  * [SDK](#sdk)
+  * [Semantics](#semantics)
+  * [Contrib Packages](#contrib-packages)
 - [Distributed Tracing](#distributed-tracing)
   * [Trace](#trace)
   * [Span](#span)
@@ -33,12 +38,43 @@ Table of Contents
 
 </details>
 
-This document provides an overview of the pillars of telemetry that
-OpenTelemetry supports and defines important fundamental terms.
+This document provides an overview of the OpenTelemetry project and defines important fundamental terms.
 
 Additional term definitions can be found in the [glossary](glossary.md).
 
-## Distributed Tracing
+## OpenTelemetry Client Architecture
+
+![Cross cutting concerns](../internal/img/architecture.png)
+
+At the highest architectural level, OpenTelemetry clients are organized into **signals**. Each signal provides a specialized form of observability. For example, tracing, metrics, and baggage are three separate signals. Signals share a common subsystem – **context propagation** – but they function independently from each other.
+
+Each signal provides a mechanism for software to describe itself. A codebase, such as web framework or a database client, takes a dependency on various signals in order to describe itself. OpenTelemetry instrumentation code is then mixed into the other code within that codebase. This makes OpenTelemetry a **cross-cutting concern** - a piece of software which must be mixed into many other pieces of software in order to provide value. Cross-cutting concerns, by their very nature, violate a core design principle – separation of concerns. As a result, OpenTelemetry client design requires extra care and attention to avoid creating issues for the codebase which depend upon these cross-cutting APIs.
+
+OpenTelemetry clients are designed to separate the portion of each signal which must be imported as cross-cutting concerns from the portions which can be managed independently. OpenTelemetry clients are also designed to be an extensible framework. To accomplish this these goals, each signal consists of four types of packages.
+
+### API
+
+API packages consist of the cross-cutting public interfaces used for instrumentation. Any portion of an OpenTelemetry client which imported into 3rd-party libraries and application code is considered part of the API. To manage different levels of stability, every signal has its own, independent API package. Stable APIs may then be bundled up into a unified API which provides additional convenience methods.
+
+### SDK
+
+The implementation of the API. The SDK is managed by the application owner. Note that the SDK includes additional public interfaces which are not considered part of the API package, as they are not cross-cutting concerns. These public interfaces are defined as **constructors** and **plugin interfaces**. Examples of plugin interfaces include the `SpanProcessor`, `Exporter`, and `Sampler` interfaces. Examples of constructors include **configuration objects**, **environment variables**, and **SDK builders**. Application owners use the SDK constructors; plugin authors use the SDK plugin interfaces. Instrumentation authors must never directly reference any SDK package of any kind, only the API.
+
+### Semantics
+
+The **Semantic Conventions** define the keys and values which describe commonly observed concepts and operations within cloud computing. See details [below](#semantic-conventions).
+
+### Contrib Packages
+
+The OpenTelemetry project maintains integrations with popular OSS projects which have been identified as important for observing modern web services. Example API integrations include instrumentation for web frameworks, database clients, and message queues. Example SDK integrations include plugins for exporting telemetry to popular analysis tools and telemetry storage systems.
+
+Some plugins, such as OTLP Exporters and TraceContext Propagators, are required by the OpenTelemetry specification. These required plugins are included as part of the SDK.
+
+Plugins and instrumentation packages which are optional and separate from the SDK are referred to as **Contrib** packages. **API Contrib** refers to packages which depend solely upon the API; **SDK Contrib** refers to packages which also depend upon the SDK.
+
+The term Contrib specifically refers to the collection of plugins and instrumentation maintained by the OpenTelemetry project; it does not refer to third party plugins hosted elsewhere.
+
+## Tracing Signal
 
 A distributed trace is a set of events, triggered as a result of a single
 logical operation, consolidated across various components of an application. A
@@ -48,7 +84,7 @@ to start an action on a website - in this example, the trace will represent
 calls made between the downstream services that handled the chain of requests
 initiated by this button being pressed.
 
-### Trace
+### Traces
 
 **Traces** in OpenTelemetry are defined implicitly by their **Spans**. In
 particular, a **Trace** can be thought of as a directed acyclic graph (DAG) of
@@ -86,9 +122,10 @@ Temporal relationships between Spans in a single Trace
          [Span E·······]        [Span F··]
 ```
 
-### Span
+### Spans
 
-Each **Span** encapsulates the following state:
+A span represents an operation within a transaction. Each **Span** encapsulates
+the following state:
 
 - An operation name
 - A start and finish timestamp
@@ -149,7 +186,7 @@ represents a single parent scenario, in many cases the parent **Span** fully
 encloses the child **Span**. This is not the case in scatter/gather and batch
 scenarios.
 
-## Metrics
+## Metric Signal
 
 OpenTelemetry allows to record raw measurements or metrics with predefined
 aggregation and set of labels.
@@ -224,14 +261,14 @@ validation and sanitization of the Metrics data. Instead, pass the data to the
 backend, rely on the backend to perform validation, and pass back any errors
 from the backend.
 
-## Logs
+## Log Signal
 
 ### Data model
 
 [Log Data Model](logs/data-model.md) defines how logs and events are understood by
 OpenTelemetry.
 
-## Baggage
+## Baggage Signal
 
 In addition to trace propagation, OpenTelemetry provides a simple mechanism for propagating
 name/value pairs, called `Baggage`. `Baggage` is intended for