Move specifications into sub-directories per signal (open-telemetry#546)

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

Author: bogdandrutu

README.md

@@ -14,19 +14,19 @@ The OpenTelemetry specification describes the cross-language requirements and ex
   - [Package/Library Layout](specification/library-layout.md)
   - [Concurrency and Thread-Safety](specification/concurrency.md)
 - API Specification
-  - [CorrelationContext](specification/api-correlationcontext.md)
-    - [Propagators](specification/api-propagators.md)
-  - [Tracing](specification/api-tracing.md)
-  - [Metrics](specification/api-metrics.md)
-    - [User-Facing API](specification/api-metrics-user.md)
-    - [Meter API](specification/api-metrics-meter.md)
+  - [CorrelationContext](specification/correlationcontext/api.md)
+    - [Propagators](specification/context/api-propagators.md)
+  - [Tracing](specification/trace/api.md)
+  - [Metrics](specification/metrics/api.md)
+    - [User-Facing API](specification/metrics/api-user.md)
+    - [Meter API](specification/metrics/api-meter.md)
 - SDK Specification
-  - [Tracing](specification/sdk-tracing.md)
-  - [Resource](specification/sdk-resource.md)
+  - [Tracing](specification/trace/sdk.md)
+  - [Resource](specification/resource/sdk.md)
   - [Configuration](specification/sdk-configuration.md)
 - Data Specification
-  - [Semantic Conventions](specification/data-semantic-conventions.md)
-  - [Protocol](specification/protocol.md)
+  - [Semantic Conventions](specification/overview.md#semantic-conventions.md)
+  - [Protocol](specification/protocol/README.md)
 - About the Project
   - [Timeline](#project-timeline)
   - [Notation Conventions and Compliance](#notation-conventions-and-compliance)

specification/img/library-design.png internal/img/library-design.png

@@ -27,7 +27,7 @@ Parity can be defined as the following features:
 - An SDK implementing OpenTelemetry specification.
 - Backwards compatibility with OpenTracing and OpenCensus via bridges.
 - Metadata helpers or other means for recording common operations defined in the
-  OpenTelemetry [semantic conventions](specification/data-semantic-conventions.md).
+  OpenTelemetry [semantic conventions](specification/overview.md#semantic-conventions.md).
 - Tests which provide evidence of interoperability.
 - Benchmarks which provide evidence of expected resource utilization.
 - Documentation and getting started guide.

specification/img/library-full.png internal/img/library-full.png

@@ -8,7 +8,7 @@ specification.
 Denotes the library that implements the *OpenTelemetry API*.
 
 See [Library Guidelines](library-guidelines.md#sdk-implementation) and
-[Library resource semantic conventions](data-resource-semantic-conventions.md#telemetry-sdk)
+[Library resource semantic conventions](resource/semantic_conventions/README.md#telemetry-sdk)
 
 <a name="instrumented_library"></a>
 
@@ -38,11 +38,11 @@ Synonyms: *Instrumentation Library*, *Integration*.
 ## 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](api-tracing.md#obtaining-a-tracer)/[Obtaining a Meter](api-metrics-user.md#obtaining-a-meter)). 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-user.md#obtaining-a-meter)). It identifies the [Instrumenting Library](#instrumenting_library).
 
 ## Namespace
 
-This term applies to [Metric names](api-metrics-user.md#metric-names) only. The namespace is used to disambiguate identical metric
+This term applies to [Metric names](metrics/api-user.md#metric-names) only. The namespace is used to disambiguate identical metric
 names used in different [instrumenting libraries](#instrumenting_library). The [Name](#name) provided
 for creating a `Meter` serves as its namespace in addition to the primary semantics
 described [here](#name).

specification/img/library-minimal.png internal/img/library-minimal.png

@@ -35,7 +35,7 @@ _Note to Language Library Authors:_ OpenTelemetry specification, API and SDK imp
 
 Here is a generic design for a language library (arrows indicate calls):
 
-![Language Library Design Diagram](img/library-design.png)
+![Language Library Design Diagram](../internal/img/library-design.png)
 
 ### Expected Usage
 
@@ -55,7 +55,7 @@ This self-sufficiency is achieved the following way.
 
 The API dependency contains a minimal implementation of the API. When no other implementation is explicitly included in the application no telemetry data will be collected. Here is what active components look like in this case:
 
-![Minimal Operation Diagram](img/library-minimal.png)
+![Minimal Operation Diagram](../internal/img/library-minimal.png)
 
 It is important that values returned from this minimal implementation of API are valid and do not require the caller to perform extra checks (e.g. createSpan() method should not fail and should return a valid non-null Span object). The caller should not need to know and worry about the fact that minimal implementation is in effect. This minimizes the boilerplate and error handling in the instrumented code.
 
@@ -67,17 +67,17 @@ SDK implementation is a separate (optional) dependency. When it is plugged in it
 
 SDK implements core functionality that is required for translating API calls into telemetry data that is ready for exporting. Here is how OpenTelemetry components look like when SDK is enabled:
 
-![Full Operation Diagram](img/library-full.png)
+![Full Operation Diagram](../internal/img/library-full.png)
 
-SDK defines an [Exporter interface](sdk-tracing.md#span-exporter). Protocol-specific exporters that are responsible for sending telemetry data to backends must implement this interface.
+SDK defines an [Exporter interface](trace/sdk.md#span-exporter). Protocol-specific exporters that are responsible for sending telemetry data to backends must implement this interface.
 
 SDK also includes optional helper exporters that can be composed for additional functionality if needed.
 
-Library designers need to define the language-specific `Exporter` interface based on [this generic specification](sdk-tracing.md#span-exporter).
+Library designers need to define the language-specific `Exporter` interface based on [this generic specification](trace/sdk.md#span-exporter).
 
 #### Protocol Exporters
 
-Telemetry backend vendors are expected to implement [Exporter interface](sdk-tracing.md#span-exporter). Data received via Export() function should be serialized and sent to the backend in a vendor-specific way.
+Telemetry backend vendors are expected to implement [Exporter interface](trace/sdk.md#span-exporter). Data received via Export() function should be serialized and sent to the backend in a vendor-specific way.
 
 Vendors are encouraged to keep protocol-specific exporters as simple as possible and achieve desirable additional functionality such as queuing and retrying using helpers provided by SDK.
 

milestones.md

@@ -29,22 +29,22 @@ api
 
 This directory describes the API that provides in-process context propagation.
 
-### [/metrics](api-metrics.md)
+### [/metrics](./metrics/api.md)
 
 This directory describes the Metrics API that can be used to record application metrics.
 
-### [/correlationcontext](api-correlationcontext.md)
+### [/correlationcontext](correlationcontext/api.md)
 
 This directory describes the CorrelationContext API that can be used to manage context propagation
 and metrics-related labeling.
 
-### [/trace](api-tracing.md)
+### [/trace](trace/api.md)
 
 This API consist of a few main classes:
 
-- `Tracer` is used for all operations. See [Tracer](api-tracing.md#tracer) section.
+- `Tracer` is used for all operations. See [Tracer](trace/api.md#tracer) section.
 - `Span` is a mutable object storing information about the current operation
-   execution. See [Span](api-tracing.md#span) section.
+   execution. See [Span](trace/api.md#span) section.
 
 ### `/internal` (_Optional_)
 
@@ -81,7 +81,7 @@ This directory describes the SDK implementation for api/context.
 
 This directory describes the SDK implementation for api/metrics.
 
-### [/sdk/resource](sdk-resource.md)
+### [/sdk/resource](resource/sdk.md)
 
 The resource directory primarily defines a type [Resource](overview.md#resources) that captures
 information about the entity for which stats or traces are recorded. For example, metrics exposed
@@ -90,7 +90,7 @@ and container name.
 
 ### `/sdk/correlationcontext`
 
-### [/sdk/trace](sdk-tracing.md)
+### [/sdk/trace](trace/sdk.md)
 
 This directory describes the SDK implementation for api/trace.
 

specification/api-propagators.md specification/context/api-propagators.md

@@ -5,5 +5,5 @@
 
 This document will be updated as part of the v0.4 milestone with a
 detailed list of `Meter` API functions.  These functions are given a
-high-level description in the [overview document](api-metrics.md) and
+high-level description in the [overview document](api.md) and
 this document will simply give details on the `Meter` API.

specification/context.md specification/context/context.md

@@ -28,7 +28,7 @@
 
 Note: This specification for the v0.3 OpenTelemetry milestone does not
 include specification related to the Observer instrument, as described
-in the [overview](api-metrics.md).  Observer instruments were detailed
+in the [overview](api.md).  Observer instruments were detailed
 in [OTEP
 72-metric-observer](https://github.com/open-telemetry/oteps/blob/master/text/0072-metric-observer.md)
 and will be added to this document following the v0.3 milestone.
@@ -412,7 +412,7 @@ unordered labels (i.e., a list of bound keys and values) to the
 
 ## Detailed specification
 
-See the [SDK-facing Metrics API](api-metrics-meter.md) specification
+See the [SDK-facing Metrics API](api-meter.md) specification
 for an in-depth summary of each method in the Metrics API.
 
 ### Instrument construction
@@ -462,7 +462,7 @@ that it used, and the metric name is the only required field.
 | Monotonic              | WithMonotonic(boolean)    | Configure a counter or gauge that accepts only monotonic/non-monotonic updates. |
 | Absolute               | WithAbsolute(boolean)     | Configure a measure that does or does not accept negative updates. |
 
-See the Metric API [specification overview](api-metrics.md) for more
+See the Metric API [specification overview](api.md) for more
 information about the kind-specific monotonic and absolute options.
 
 ### Bound instrument API

specification/api-correlationcontext.md specification/correlationcontext/api.md

@@ -46,7 +46,7 @@ Metrics API.
 
 The API provides functions for capturing raw measurements, through
 several [calling
-conventions](api-metrics-user.md#metric-calling-conventions) that
+conventions](api-user.md#metric-calling-conventions) that
 offer different levels of performance.  Regardless of calling
 convention, we define a _metric event_ as the logical thing that
 happens when a new measurement is captured.  This moment of capture
@@ -69,7 +69,7 @@ and converting into various [exposition formats](#exposition-formats).
 However, we find that there are many other uses for metric events,
 such as to record aggregated or raw measurements in tracing and
 logging systems.  For this reason, [OpenTelemetry requires a
-separation of the API from the SDK](library-guidelines.md#requirements),
+separation of the API from the SDK](../library-guidelines.md#requirements),
 so that different SDKs can be configured at run time.
 
 ### Metric Instruments
@@ -97,13 +97,13 @@ measurement, and several settings that convey additional meaning
 events that it produces.
 
 Details about calling conventions for each kind of instrument are
-covered in the [user-level API specification](api-metrics-user.md).
+covered in the [user-level API specification](api-user.md).
 
 ### Label sets
 
 _Label_ is the term used to refer to a key-value attribute associated
 with a metric event.  Although they are fundamentally similar to [Span
-attributes](api-tracing.md#span) in the tracing API, a label set is
+attributes](../trace/api.md#span) in the tracing API, a label set is
 given its own type in the Metrics API (generally: `LabelSet`).  Label
 sets are a feature of the API meant to facilitate re-use and thereby
 to lower the cost of processing metric events.  Users are encouraged
@@ -112,7 +112,7 @@ previously encoded representation of the labels.
 
 Users obtain label sets by calling a `Meter` API function.  Each of
 the instrument calling conventions detailed in the [user-level API
-specification](api-metrics-user.md) accepts a label set.
+specification](api-user.md) accepts a label set.
 
 ### Meter Interface
 
@@ -138,7 +138,7 @@ sampling policies.  (TODO: refer to the semantic convention on the
 reporting library name).
 
 Details about installing an SDK and obtaining a named `Meter` are
-covered in the [SDK-level API specification](api-metrics-meter.md).
+covered in the [SDK-level API specification](api-meter.md).
 
 ### Aggregations
 
@@ -245,7 +245,7 @@ Metric events have the same logical representation, regardless of
 kind.  Whether a Counter, a Measure, or an Observer instrument, metric
 events produced through an instrument consist of:
 
-- [Context](context.md) (Span context, Correlation context)
+- [Context](../context/context.md) (Span context, Correlation context)
 - timestamp (implicit to the SDK)
 - instrument definition (name, kind, and semantic options)
 - label set (associated key-values)

specification/glossary.md

@@ -0,0 +1,3 @@
+# Metrics Semantic Conventions
+
+TODO: Add semantic conventions for metric names and labels.

specification/library-guidelines.md

@@ -189,10 +189,6 @@ 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.
 
-OpenTelemetry defines the naming convention for metric names as well as a
-well-known metric names in [Semantic Conventions](data-semantic-conventions.md)
-document.
-
 ## CorrelationContext
 
 In addition to trace propagation, OpenTelemetry provides a simple mechanism for propagating
@@ -238,7 +234,7 @@ All of OpenTelemetry cross-cutting concerns, such as traces and metrics,
 share an underlying `Context` mechanism for storing state and
 accessing data across the lifespan of a distributed transaction.
 
-See the [Context](context.md)
+See the [Context](context/context.md)
 
 ## Propagators
 
@@ -286,3 +282,17 @@ Adapter" or simply "Adapter".
 ## Code injecting adapters
 
 TODO: fill out as a result of SIG discussion.
+
+## Semantic Conventions
+
+OpenTelemetry defines standard names and values of Resource attributes and
+Span attributes.
+
+* [Resource Conventions](resource/semantic_conventions/README.md)
+* [Span Conventions](trace/semantic_conventions/README.md)
+* [Metrics Conventions](metrics/semantic_conventions/README.md)
+
+The type of the attribute SHOULD be specified in the semantic convention
+for that attribute. Array values are allowed for attributes. For
+protocols that do not natively support array values such values MUST be
+represented as JSON strings.

specification/library-layout.md

@@ -2,6 +2,6 @@
 
 This is the specification of new OpenTelemetry protocol. This is work in progress.
 
-- [Design Goals](proto-design-goals.md).
-- [Requirements](proto-requirements.md).
+- [Design Goals](design-goals.md).
+- [Requirements](requirements.md).
 - Specification (TBD).

specification/api-metrics-meter.md specification/metrics/api-meter.md

@@ -4,7 +4,7 @@ This document will drive OpenTelemetry Protocol design and RFC.
 
 ## Goals
 
-See the goals of OpenTelemetry Protocol design [here](proto-design-goals.md).
+See the goals of OpenTelemetry Protocol design [here](design-goals.md).
 
 ## Vocabulary
 

specification/api-metrics-user.md specification/metrics/api-user.md

@@ -1,6 +1,6 @@
 # Resource SDK
 
-A [Resource](overview.md#resources) is an immutable representation of the entity producing
+A [Resource](../overview.md#resources) is an immutable representation of the entity producing
 telemetry. For example, a process producing telemetry that is running in a
 container on Kubernetes has a Pod name, it is in a namespace and possibly is
 part of a Deployment which also has a name. All three of these attributes can be
@@ -13,14 +13,14 @@ with closed source environments. The SDK MUST allow for creation of `Resources`
 for associating them with telemetry.
 
 When used with distributed tracing, a resource can be associated with the
-[TracerProvider](sdk-tracing.md#tracer-sdk) when it is created.
+[TracerProvider](../trace/sdk.md#tracer-sdk) when it is created.
 That association cannot be changed later.
 When associated with a `TracerProvider`,
 all `Span`s produced by any `Tracer` from the provider MUST be associated with this `Resource`.
 
 Analogous to distributed tracing, when used with metrics,
 a resource can be associated with a `MeterProvider`.
-When associated with a [`MeterProvider`](api-metrics-user.md#obtaining-a-meter),
+When associated with a [`MeterProvider`](../metrics/api-user.md#obtaining-a-meter),
 all `Metrics` produced by any `Meter` from the provider will be
 associated with this `Resource`.
 
@@ -69,7 +69,7 @@ It is recommended, but not required, to provide a way to quickly create an empty
 resource.
 
 Note that the OpenTelemetry project documents certain ["standard
-attributes"](data-semantic-conventions.md) that have prescribed semantic meanings.
+attributes"](semantic_conventions/README.md) that have prescribed semantic meanings.
 
 ## Resource operations
 

specification/api-metrics.md specification/metrics/api.md

@@ -1,6 +1,6 @@
-# Resource Conventions
+# Resource Semantic Conventions
 
-This document defines standard attributes for resources. These attributes are typically used in the [Resource](sdk-resource.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from
+This document defines standard attributes for resources. These attributes are typically used in the [Resource](../sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from
 [OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md).
 
 * [Service](#service)

specification/metrics/semantic_conventions/README.md

@@ -260,7 +260,7 @@ The API MUST accept the following parameters:
 - `Attribute`s - A collection of key-value pairs, with the same semantics as
   the ones settable with [Span::SetAttributes](#set-attributes). Additionally,
   these attributes may be used to make a sampling decision as noted in [sampling
-  description](sdk-tracing.md#sampling). An empty collection will be assumed if
+  description](sdk.md#sampling). An empty collection will be assumed if
   not specified.
 
   Whenever possible, users SHOULD set any already known attributes at span creation
@@ -305,7 +305,7 @@ The parent should be selected in the following order of precedence:
 
 During the `Span` creation user MUST have the ability to record links to other `Span`s. Linked
 `Span`s can be from the same or a different trace. See [Links
-description](overview.md#links-between-spans).
+description](../overview.md#links-between-spans).
 
 A `Link` is defined by the following properties:
 
@@ -361,7 +361,7 @@ allows to record and process information about the individual Span without
 sending it to the backend. An example of this scenario may be recording and
 processing of all incoming requests for the processing and building of
 SLA/SLO latency charts while sending only a subset - sampled spans - to the
-backend. See also the [sampling section of SDK design](sdk-tracing.md#sampling).
+backend. See also the [sampling section of SDK design](sdk.md#sampling).
 
 Users of the API should only access the `IsRecording` property when
 instrumenting code and never access `SampledFlag` unless used in context
@@ -405,7 +405,7 @@ both containing an array of strings to represent a mapping
 `header_keys[i] -> header_values[i]`).
 
 Note that the OpenTelemetry project documents certain ["standard
-attributes"](data-semantic-conventions.md) that have prescribed semantic meanings.
+attributes"](semantic_conventions/README.md) that have prescribed semantic meanings.
 
 #### Add Events
 
@@ -437,7 +437,7 @@ Events SHOULD preserve the order in which they're set. This will typically match
 the ordering of the events' timestamps.
 
 Note that the OpenTelemetry project documents certain ["standard event names and
-keys"](data-semantic-conventions.md) which have prescribed semantic meanings.
+keys"](semantic_conventions/README.md) which have prescribed semantic meanings.
 
 #### Set Status