normalize term for instrumentations (open-telemetry#539)

* normalize term for instrumentations

Fixes open-telemetry#476

A single term for instrumentation libraries would be beneficial, as
it reduces ambiguation. Removing synonyms "integration" and "adapter".

Integration doesn't imply some form of instrumentation, while adapter
could easily overlap with middleware or other concepts in existing
frameworks that will be instrumented.

* Addressing feedback

Using the full "instrumentation libraries" form where possible.

Fixing capitalization of OpenTelemetry.

Adding reference to "Instrumenting Libraries".

Adding link to definition in overview

* finishing cleaning up merge errors.

* fixing for lint.

* re-removing milestones

* Update specification/glossary.md

fixing typo

Co-authored-by: Giovanni Liva <giovanni.liva@dynatrace.com>

* Addressing feedback

Re-adding a section clarifying the goal of opentelemetry to
enable native instrumentation.

Fixing links.

* rewriting first paragraph on instrumentation libraries

Clarifying several aspects about instrumentation libraries.

* Update specification/error-handling.md

Co-authored-by: Morgan McLean <morgan_mclean@hotmail.com>

Co-authored-by: Giovanni Liva <giovanni.liva@dynatrace.com>
Co-authored-by: Morgan McLean <morgan_mclean@hotmail.com>

Author: 3 people

specification/error-handling.md

@@ -44,7 +44,7 @@ And make a reasonable trade off of the SDK performance and fullness of type chec
 
 ## Self-diagnostics
 
-All OpenTelemetry libraries -- the API, SDK, exporters, instrumentation adapters, etc. -- are encouraged to expose self-troubleshooting metrics, spans, and other telemetry that can be easily enabled and filtered out by default.
+All OpenTelemetry libraries -- the API, SDK, exporters, instrumentations, etc. -- are encouraged to expose self-troubleshooting metrics, spans, and other telemetry that can be easily enabled and filtered out by default.
 
 One good example of such telemetry is a `Span` exporter that indicates how much time exporters spend uploading telemetry.
 Another example may be a metric exposed by a `SpanProcessor` that describes the current queue size of telemetry data to be uploaded.

specification/glossary.md

@@ -25,15 +25,15 @@ Example: `org.mongodb.client`.
 
 <a name="instrumenting_library"></a>
 
-### Instrumenting Library
+### Instrumentation Library
 
 Denotes the library that provides the instrumentation for a given [Instrumented Library](#instrumented_library).
-*Instrumented Library* and *Instrumenting Library* may be the same library
+*Instrumented Library* and *Instrumentation Library* may be the same library
 if it has built-in OpenTelemetry instrumentation.
 
 Example: `io.opentelemetry.contrib.mongodb`.
 
-Synonyms: *Instrumentation Library*, *Integration*.
+Synonyms: *Instrumentation Library*
 
 <a name="name"></a>
 

specification/overview.md

@@ -261,22 +261,29 @@ service).
 Read more at OpenTelemetry Service [Long-term
 Vision](https://github.com/open-telemetry/opentelemetry-collector/blob/master/docs/vision.md).
 
-## Instrumentation adapters
+## Instrumentation Libraries
+
+See [Instrumentation Library](glossary.md#instrumentation_library)
 
 The inspiration of the project is to make every library and application
-manageable out of the box by instrumenting it with OpenTelemetry. However on the
-way to this goal there will be a need to enable instrumentation by plugging
-instrumentation adapters into the library of choice. These adapters can be
-wrapping library APIs, subscribing to the library-specific callbacks or
-translating telemetry exposed in other formats into OpenTelemetry model.
-
-Instrumentation adapters may be called different names. It is often referred as
-plugin, collector or auto-collector, telemetry module, bridge, etc. It is always
-recommended to follow the library and language standards. For instance, if
-instrumentation adapter is implemented as "log appender" - it will probably be
-called an `appender`, not an instrumentation adapter. However if there is no
-established name - the recommendation is to call packages "Instrumentation
-Adapter" or simply "Adapter".
+observable out of the box by having them call OpenTelemetry API directly. However,
+many libraries will not have such integration, and as such there is a need for
+a separate library which would inject such calls, using mechanisms such as
+wrapping interfaces, subscribing to library-specific callbacks, or translating
+existing telemetry into the OpenTelemetry model.
+
+A library that enables OpenTelemetry observability for another library is called
+an [Instrumentation Library](glossary.md#instrumentation_library).
+
+An instrumentation library should be named to follow any naming conventions of
+the instrumented library (e.g. 'middleware' for a web framework).
+
+If there is no established name, the recommendation is to prefix packages
+with "opentelemetry-instrumentation", followed by the instrumented library
+name itself. Examples include:
+
+* opentelemetry-instrumentation-flask (Python)
+* @opentelemetry/instrumentation-grpc (Javascript)
 
 ## Code injecting adapters
 

specification/trace/api.md

@@ -88,8 +88,7 @@ Some applications may use multiple `TracerProvider` instances, e.g. to provide
 different settings (e.g. `SpanProcessor`s) to each of those instances and -
 in further consequence - to the `Tracer` instances created by them.
 
-- `name` (required): This name must identify the instrumentation library (also
-  referred to as integration, e.g. `io.opentelemetry.contrib.mongodb`) and *not*
+- `name` (required): This name must identify the instrumentation library (e.g. `io.opentelemetry.contrib.mongodb`) and *not*
   the instrumented library.
   In case an invalid name (null or empty string) is specified, a working
   default Tracer implementation as a fallback is returned rather than returning