Setting naming convention for exporter packages (open-telemetry#629)

* Setting naming convention for exporter packages There is an implicit convention around exporter packages in several language instrumentations. Adding the convention to the spec standardizes the convention. * Addressing feedback - modifying wording for exporter packages to have prefixes - fixing link naming - adding entry to changelog * Update specification/library-guidelines.md Co-authored-by: Armin Ruech <[email protected]> * adding arminru's suggestions Co-authored-by: Armin Ruech <[email protected]>
carlosalberto · Jun 12, 2020 · 850c286 · 850c286
1 parent 58a6871
commit 850c286
Show file tree

Hide file tree

Showing 4 changed files with 19 additions and 3 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,8 @@ the release.
 
 ## Unreleased
 
+- Added conventions for naming of exporter packages
+
 ## v0.5.0 (06-02-2020)
 
 - Define Log Data Model.

diff --git a/specification/glossary.md b/specification/glossary.md
@@ -12,7 +12,13 @@ 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="instrumented_library"></a>
+<a name="telemetry_sdk"></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>
 
 ### Instrumented Library
 
@@ -37,7 +43,7 @@ Example: `io.opentelemetry.contrib.mongodb`.
 
 Synonyms: *Instrumenting Library*
 
-<a name="name"></a>
+<a name="instrumentation_library"></a>
 
 ### Tracer Name / Meter Name
 

diff --git a/specification/library-guidelines.md b/specification/library-guidelines.md
@@ -82,6 +82,14 @@ Vendors are encouraged to keep protocol-specific exporters as simple as possible
 
 End users should be given the flexibility of making many of the decisions regarding the queuing, retrying, tagging, batching functionality that make the most sense for their application. For example, if an application's telemetry data must be delivered to a remote backend that has no guaranteed availability the end user may choose to use a persistent local queue and an `Exporter` to retry sending on failures. As opposed to that for an application that sends telemetry to a locally running Agent daemon, the end user may prefer to have a simpler exporting configuration without retrying or queueing.
 
+If additional exporters for the sdk are provided as separate libraries, the
+name of the library should be prefixed with the terms "OpenTelemetry" and "Exporter" in accordance with the naming conventions of the respective technology.
+
+For example:
+
+- Python and Java: opentelemetry-exporter-jaeger
+- Javascript: @opentelemetry/exporter-jeager
+
 ### Alternative Implementations
 
 The end-user application may decide to take a dependency on alternative implementation.

diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md
@@ -54,7 +54,7 @@ and Zipkin.
 
 Zipkin service name MUST be set to the value of the
 [resource attribute](../../resource/semantic_conventions/README.md):
-`service.name`. In Zipkin it is important that the service name is consistent 
+`service.name`. In Zipkin it is important that the service name is consistent
 for all spans in a local root. Otherwise service graph and aggregations would
 not work properly. OpenTelemetry doesn't provide this consistency guarantee.
 Exporter may chose to override the value for service name based on a local root