chore(semantic-conventions): docs on entry-points, deprecations; impr…

…ove some deprecation messages (#5166)

Co-authored-by: Jackson Weber <[email protected]>
Co-authored-by: Jamie Danielson <[email protected]>

semantic-conventions/CHANGELOG.md

@@ -13,6 +13,8 @@ All notable changes to the semantic-conventions package will be documented in th
 
 ### :books: (Refine Doc)
 
+* chore: Improve documentation on entry-points (top-level and "incubating") and on deprecations. [#5025](https://github.com/open-telemetry/opentelemetry-js/issues/5025) @trentm
+
 ### :house: (Internal)
 
 * chore: Update the comments of some deprecated constants to point to the currently relevant replacement constant, if any. [#5160](https://github.com/open-telemetry/opentelemetry-js/pull/5160) @trentm

semantic-conventions/README.md

@@ -13,18 +13,31 @@ npm install --save @opentelemetry/semantic-conventions
 
 ## Import Structure
 
-This package has 2 separate exports.
-The main export (`@opentelemetry/semantic-conventions`) includes only stable semantic conventions.
-It is subject to the restrictions of semantic versioning 2.0.
-The `/incubating` export (`@opentelemetry/semantic-conventions/incubating`) contains all stable and unstable semantic conventions.
-It is _NOT_ subject to the restrictions of semantic versioning and _MAY_ contain breaking changes in minor releases.
+This package has 2 separate entry-points:
+
+- The main entry-point, `@opentelemetry/semantic-conventions`, includes only stable semantic conventions.
+  This entry-point follows semantic versioning 2.0: it will not include breaking changes except with a change in the major version number.
+- The "incubating" entry-point, `@opentelemetry/semantic-conventions/incubating`, contains unstable semantic conventions (sometimes called "experimental") and, for convenience, a re-export of the stable semantic conventions.
+  This entry-point is _NOT_ subject to the restrictions of semantic versioning and _MAY_ contain breaking changes in minor releases.
+
+Exported constants follow this naming scheme:
+
+- `ATTR_${attributeName}` for attributes
+- `METRIC_${metricName}` for metric names
+- `${attributeName}_VALUE_{$enumValue}` for enumerations
+
+The `ATTR`, `METRIC`, and `VALUE` static strings were used to facilitate readability and filtering in auto-complete lists in IDEs.
 
 ## Usage
 
 ### Stable SemConv
 
+```bash
+npm install --save @opentelemetry/semantic-conventions
+```
+
 ```ts
-import { 
+import {
   ATTR_NETWORK_PEER_ADDRESS,
   ATTR_NETWORK_PEER_PORT,
   ATTR_NETWORK_PROTOCOL_NAME,
@@ -44,8 +57,19 @@ const span = tracer.startSpan(spanName, spanOptions)
 
 ### Unstable SemConv
 
+<!-- Dev Note: ^^ This '#unstable-semconv' anchor is being used in jsdoc links in the code. -->
+
+```bash
+npm install --save-exact @opentelemetry/semantic-conventions
+```
+
+**Note**: Because the "incubating" entry-point may include breaking changes in minor versions, it is recommended that users of unstable semconv values either:
+
+1. depend on a pinned (exact) version of the package (`npm install --save-exact ...`), or
+2. [copy relevant definitions to their code base](https://opentelemetry.io/docs/specs/semconv/non-normative/code-generation/#stability-and-versioning).
+
 ```ts
-import { 
+import {
   ATTR_PROCESS_COMMAND,
   ATTR_PROCESS_COMMAND_ARGS,
   ATTR_PROCESS_COMMAND_LINE,
@@ -59,6 +83,107 @@ const span = tracer.startSpan(spanName, spanOptions)
   });
 ```
 
+## Deprecations
+
+There are two main types of deprecations in this package:
+
+1. "semconv deprecations": The process of defining the OpenTelemetry [Semantic Conventions][semconv-docs] sometimes involves deprecating a particular field name as conventions are [stabilized][semconv-stability]. For example, the [stabilization of HTTP conventions][semconv-http-stabilization] included deprecating the `http.url` span attribute in favor of `url.full`. When using this JS package, that appears as a deprecation of the `ATTR_HTTP_URL` export in favour of `ATTR_URL_FULL`.
+2. "JS package deprecations": Independently, this JavaScript package has twice changed how it exports the Semantic Conventions constants, e.g. `ATTR_HTTP_URL` instead of `SEMATTRS_HTTP_URL`. The two older forms are still included in 1.x versions of this package for backwards compatibility. The rest of this section shows how to migrate to the latest form.
+
+### Migrating from `SEMATTRS_*`, `SEMRESATTRS_*`, ...
+
+Deprecated as of `@opentelemetry/[email protected]`.
+
+Before v1.26.0, constants for each semconv attribute were exported, prefixed with `SEMRESATTRS_` (if defined as a Resource Attribute) or `SEMATTRS_`. As well, constants were exported for each value in an enumeration, of the form `${attributeName}VALUES_${enumValue}`. For example:
+
+**Deprecated usage:**
+
+```js
+import {
+  SEMRESATTRS_SERVICE_NAME,
+  SEMATTRS_HTTP_ROUTE,
+  SEMATTRS_DB_SYSTEM,
+  DBSYSTEMVALUES_POSTGRESQL
+} from '@opentelemetry/semantic-conventions';
+
+// 'service.name' resource attribute
+console.log(SEMRESATTRS_SERVICE_NAME); // migrate to 'ATTR_SERVICE_NAME'
+
+// 'http.route' attribute
+console.log(SEMATTRS_HTTP_ROUTE); // migrate to 'ATTR_HTTP_ROUTE'
+
+// 'db.system' attribute
+console.log(SEMATTRS_DB_SYSTEM); // migrate to 'ATTR_DB_SYSTEM' (in incubating [*])
+
+// 'postgresql' enum value for 'db.system' attribute
+console.log(DBSYSTEMVALUES_POSTGRESQL); // migrate to 'DB_SYSTEM_VALUE_POSTGRESQL' (in incubating [*])
+```
+
+See [Migrated usage](#migrated-usage) below.
+
+### Migrating from `SemanticAttributes.*`, `SemanticResourceAttributes.*`, ...
+
+Deprecated as of `@opentelemetry/[email protected]`.
+
+Before v1.0.0, constants were exported in namespace objects `SemanticResourceAttributes` and `SemanticAttributes`, and a namespace object for enumerated values for some fields (e.g. `DbSystemValues` for values of the 'db.system' enum). For example:
+
+**Deprecated usage:**
+
+```js
+import {
+  SemanticAttributes,
+  SemanticResourceAttributes,
+  DbSystemValues,
+} from '@opentelemetry/semantic-conventions';
+
+// 'service.name' resource attribute
+console.log(SemanticResourceAttributes.SERVICE_NAME); // migrate to 'ATTR_SERVICE_NAME'
+
+// 'http.route' attribute
+console.log(SemanticAttributes.HTTP_ROUTE); // migrate to 'ATTR_HTTP_ROUTE'
+
+// 'db.system' attribute
+console.log(SemanticAttributes.DB_SYSTEM); // migrate to 'ATTR_DB_SYSTEM' (in incubating [*])
+
+// 'postgresql' enum value for 'db.system' attribute
+console.log(DbSystemValues.POSTGRESQL); // migrate to 'DB_SYSTEM_VALUE_POSTGRESQL' (in incubating [*])
+```
+
+See [Migrated usage](#migrated-usage) below.
+
+### Migrated usage
+
+```js
+import {
+  ATTR_SERVICE_NAME,
+  ATTR_HTTP_ROUTE,
+  METRIC_HTTP_CLIENT_REQUEST_DURATION
+} from '@opentelemetry/semantic-conventions';
+import {
+  ATTR_DB_SYSTEM,
+  DB_SYSTEM_VALUE_POSTGRESQL
+} from '@opentelemetry/semantic-conventions/incubating';
+
+console.log(ATTR_SERVICE_NAME); // 'service.name'
+console.log(ATTR_HTTP_ROUTE);   // 'http.route'
+
+// Bonus: the older exports did not include metric names from semconv.
+// 'http.client.request.duration' metric name
+console.log(METRIC_HTTP_CLIENT_REQUEST_DURATION);
+
+console.log(ATTR_DB_SYSTEM);    // 'db.system'
+// 'postgresql' enum value for 'db.system' attribute
+console.log(DB_SYSTEM_VALUE_POSTGRESQL);
+```
+
+### What is "incubating"?
+
+The first three fields in the preceding code sample ('service.name', 'http.route', 'http.client.request.duration') are _stable_ in semantic conventions, the latter two are not. Version 1.26.0 of this package separated stable and unstable into separate module entry points: stable conventions are imported `from '@opentelemetry/semantic-conventions'` and unstable `from '@opentelemetry/semantic-conventions/incubating'`. The name "incubating" is [suggested by the Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/non-normative/code-generation/#semantic-conventions-artifact-structure).
+
+It is recommended that if you are using exports from _incubating_, that you **pin the version** in your package.json dependencies (e.g. via `npm install --save-exact @opentelemetry/semantic-conventions`) _or_ that you copy the relevant definitions into your code base. This is because the removal of exports from the _incubating_ entry point is _not considered a breaking change_ and hence can happen in a minor version.
+
+Note: The _incubating_ entry point also exports all stable fields, so the above example could be changed to import all five constants `from '@opentelemetry/semantic-conventions/incubating'`.
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
@@ -74,5 +199,7 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
 [npm-url]: https://www.npmjs.com/package/@opentelemetry/semantic-conventions
 [npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fsemantic-conventions.svg
-
+[semconv-docs]: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md
+[semconv-stability]: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#semantic-conventions-stability
+[semconv-http-stabilization]: https://opentelemetry.io/blog/2023/http-conventions-declared-stable/
 [trace-semantic_conventions]: https://github.com/open-telemetry/semantic-conventions/tree/main/specification/trace/semantic_conventions