From 2a86fe8dc3a1f7d57f4831892fe2786434e8230c Mon Sep 17 00:00:00 2001 From: Trent Mick Date: Wed, 11 Dec 2024 17:37:01 -0800 Subject: [PATCH] doc(semantic-conventions): clarify suggested usage of *unstable* semconv It is recommended that users (typically instrumentation libraries) of *unstable* semconv create a local copy of relevant definitions, rather than pinning. Pinning of this package can easily lead to very many versions of the package being installed, which leads to heavy disk usage. Refs: #5182 --- semantic-conventions/CHANGELOG.md | 2 + semantic-conventions/README.md | 76 ++++++++++++++++++++----------- 2 files changed, 52 insertions(+), 26 deletions(-) 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