OpenTelemetry Semantic Conventions

Semantic Convention constants for use with the OpenTelemetry SDK/APIs. This document defines standard attributes for traces.

Installation

npm install --save @opentelemetry/semantic-conventions

Import Structure

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

npm install --save @opentelemetry/semantic-conventions

import {
  ATTR_NETWORK_PEER_ADDRESS,
  ATTR_NETWORK_PEER_PORT,
  ATTR_NETWORK_PROTOCOL_NAME,
  ATTR_NETWORK_PROTOCOL_VERSION,
  NETWORK_TRANSPORT_VALUE_TCP,
} from '@opentelemetry/semantic-conventions';

const span = tracer.startSpan(spanName, spanOptions)
  .setAttributes({
    [ATTR_NETWORK_PEER_ADDRESS]: 'localhost',
    [ATTR_NETWORK_PEER_PORT]: 8080,
    [ATTR_NETWORK_PROTOCOL_NAME]: 'http',
    [ATTR_NETWORK_PROTOCOL_VERSION]: '1.1',
    [ATTR_NETWORK_TRANSPORT]: NETWORK_TRANSPORT_VALUE_TCP,
  });

Unstable SemConv

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.

import {
  ATTR_PROCESS_COMMAND,
  ATTR_PROCESS_COMMAND_ARGS,
  ATTR_PROCESS_COMMAND_LINE,
} from '@opentelemetry/semantic-conventions/incubating';

const span = tracer.startSpan(spanName, spanOptions)
  .setAttributes({
    [ATTR_PROCESS_COMMAND]: 'cat',
    [ATTR_PROCESS_COMMAND_ARGS]: ['file1', 'file2'],
    [ATTR_CONTAINER_COMMAND_LINE]: 'cat file1 file2',
  });

Deprecations

There are two main types of deprecations in this package:

1. "semconv deprecations": The process of defining the OpenTelemetry Semantic Conventions sometimes involves deprecating a particular field name as conventions are stabilized. For example, the stabilization of HTTP conventions 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/semantic-conventions@1.26.0.

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:

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 below.

Migrating from SemanticAttributes.*, SemanticResourceAttributes.*, ...

Deprecated as of @opentelemetry/semantic-conventions@1.0.0.

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:

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 below.

Migrated usage

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.

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:
• For more about OpenTelemetry JavaScript:
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.