diff --git a/semantic-conventions/CHANGELOG.md b/semantic-conventions/CHANGELOG.md index 4bf95ff047..2739f42b69 100644 --- a/semantic-conventions/CHANGELOG.md +++ b/semantic-conventions/CHANGELOG.md @@ -13,6 +13,8 @@ All notable changes to the semantic-conventions package will be documented in th ### :books: (Refine Doc) +* docs: Document suggested usage of unstable semconv: copy relevant definitions into your code base. + ### :house: (Internal) ## 1.28.0 diff --git a/semantic-conventions/README.md b/semantic-conventions/README.md index cf14621c06..263fd2f7c7 100644 --- a/semantic-conventions/README.md +++ b/semantic-conventions/README.md @@ -18,7 +18,7 @@ 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. + This entry-point is _NOT_ subject to the restrictions of semantic versioning and _MAY_ contain breaking changes in minor releases. See below for suggested usage of this entry-point. Exported constants follow this naming scheme: @@ -59,30 +59,51 @@ const span = tracer.startSpan(spanName, spanOptions) -```bash -npm install --save-exact @opentelemetry/semantic-conventions -``` +Because the "incubating" entry-point may include breaking changes in minor versions, it is recommended that instrumentation libraries **not** import `@opentelemetry/semantic-conventions/incubating` in runtime code, but instead **copy relevant definitions into their own code base**. (This is the same [recommendation](https://opentelemetry.io/docs/specs/semconv/non-normative/code-generation/#stability-and-versioning) as for other languages.) -**Note**: Because the "incubating" entry-point may include breaking changes in minor versions, it is recommended that users of unstable semconv values either: +For example, create a "src/semconv.ts" (or "lib/semconv.js" if implementing in JavaScript) file that copies from [experimental_attributes.ts](./src/experimental_attributes.ts) or [experimental_metrics.ts](./src/experimental_metrics.ts): -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 +// src/semconv.ts +export const ATTR_DB_NAMESPACE = 'db.namespace'; +export const ATTR_DB_OPERATION_NAME = 'db.operation.name'; +``` ```ts +// src/instrumentation.ts +import { + ATTR_SERVER_PORT, + ATTR_SERVER_ADDRESS, +} from '@opentelemetry/semantic-conventions'; import { - ATTR_PROCESS_COMMAND, - ATTR_PROCESS_COMMAND_ARGS, - ATTR_PROCESS_COMMAND_LINE, -} from '@opentelemetry/semantic-conventions/incubating'; + ATTR_DB_NAMESPACE, + ATTR_DB_OPERATION_NAME, +} from './semconv'; + +span.setAttributes({ + [ATTR_DB_NAMESPACE]: ..., + [ATTR_DB_OPERATION_NAME]: ..., + [ATTR_SERVER_PORT]: ..., + [ATTR_SERVER_ADDRESS]: ..., +}) +``` -const span = tracer.startSpan(spanName, spanOptions) - .setAttributes({ - [ATTR_PROCESS_COMMAND]: 'cat', - [ATTR_PROCESS_COMMAND_ARGS]: ['file1', 'file2'], - [ATTR_CONTAINER_COMMAND_LINE]: 'cat file1 file2', - }); +Occasionally, one should review changes to `@opentelemetry/semantic-conventions` to see if any used unstable conventions have changed or been stabilized. However, an update to a newer minor version of the package will never be breaking. + +#### Why not pin the version? + +A considered alternative for using unstable exports is to **pin** the version. I.e., depend on an exact version, rather than on a version range. + +```bash +npm install --save-exact @opentelemetry/semantic-conventions ``` +Then, import directly from `@opentelemetry/semantic-conventions/incubating`. +This is **not** recommended. + +In some languages having multiple versions of a package in a single application is not possible. This *is* possible in JavaScript. The primary argument against pinning this package is that it can easily lead to many copies being installed in an application's `node_modules/...`, which can cause significant disk usage. In a disk-constrained environment, such as AWS Lambda Layers, that can be a blocker. + + ## Deprecations There are two main types of deprecations in this package: @@ -153,16 +174,26 @@ See [Migrated usage](#migrated-usage) below. ### Migrated usage +If using any unstable conventions, copy the relevant definitions into your code base (e.g. to "src/semconv.ts", see [above](#unstable-semconv)): + +```ts +// src/semconv.ts +export const ATTR_DB_SYSTEM = 'db.system' as const; +export const DB_SYSTEM_VALUE_POSTGRESQL = "postgresql" as const; +``` + +then: + ```js import { ATTR_SERVICE_NAME, ATTR_HTTP_ROUTE, METRIC_HTTP_CLIENT_REQUEST_DURATION -} from '@opentelemetry/semantic-conventions'; +} from '@opentelemetry/semantic-conventions'; // stable semconv import { ATTR_DB_SYSTEM, DB_SYSTEM_VALUE_POSTGRESQL -} from '@opentelemetry/semantic-conventions/incubating'; +} from './semconv'; // unstable semconv console.log(ATTR_SERVICE_NAME); // 'service.name' console.log(ATTR_HTTP_ROUTE); // 'http.route' @@ -176,13 +207,6 @@ console.log(ATTR_DB_SYSTEM); // 'db.system' 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