chore: Localized OTEL attribute constants (#2928)

Author: jsumners-nr

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,244 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+// Attribute values are found at:
+// https://opentelemetry.io/docs/specs/semconv/attributes-registry/
+// Attribute constant names are found at:
+// https://github.com/open-telemetry/opentelemetry-js/tree/e744798957ac6d980673262a61634f066d9f66a3/semantic-conventions/src
+
+/**
+ * Provides a hash of constant attribute names to attribute values as defined
+ * by the OTEL semantic conventions. The values and names are still very much
+ * in flux (2025-02). As a result, it is easier for us to copy the ones we need
+ * here.
+ *
+ * 1. Everything should be listed in alphabetical order.
+ * 2. If an attribute can have multiple names, but all have a common value,
+ * only list one constant for us to standardize on internally. Make notes of
+ * the other possible upstream names within the jsdoc for the attribute. If they
+ * have different values, include multiple attributes with documentation
+ * referencing which should be favored.
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/
+ *
+ * @type {object}
+ */
+module.exports = {
+  /**
+   * Name of the database (schema) being accessed.
+   */
+  ATTR_DB_NAME: 'db.name',
+
+  /**
+   * The name of the database operation being performed.
+   *
+   * @example select
+   * @example findAndModify
+   */
+  ATTR_DB_OPERATION: 'db.operation',
+
+  /**
+   * The table name that is targeted in the operation.
+   */
+  ATTR_DB_SQL_TABLE: 'db.sql.table',
+
+  /**
+   * The database statement being executed.
+   *
+   * @example select * from foo
+   */
+  ATTR_DB_STATEMENT: 'db.statement',
+
+  /**
+   * Name of the remote database technology being accessed.
+   *
+   * @example mysql
+   * @see https://opentelemetry.io/docs/specs/semconv/database/sql/
+   */
+  ATTR_DB_SYSTEM: 'db.system',
+
+  /**
+   * The full resource URL.
+   *
+   * @example https://example.com/foo?bar=baz
+   */
+  ATTR_FULL_URL: 'url.full',
+
+  /**
+   * Value of the HTTP `host` header.
+   *
+   * {@link ATTR_HTTP_REQUEST_METHOD} is newer and should be used instead.
+   */
+  ATTR_HTTP_HOST: 'http.host',
+
+  /**
+   * The HTTP request method, e.g. `GET` or `POST`.
+   */
+  ATTR_HTTP_METHOD: 'http.method',
+
+  /**
+   * HTTP method used for the request, e.g. `GET` or `POST`.
+   */
+  ATTR_HTTP_REQUEST_METHOD: 'http.request.method',
+
+  /**
+   * Framework representation for a route, may include parameter tokens.
+   *
+   * @example /orders/:order_id
+   */
+  ATTR_HTTP_ROUTE: 'http.route',
+
+  /**
+   * The full resource URL.
+   *
+   * {@link ATTR_FULL_URL} is newer and should be used instead.
+   *
+   * @example https://example.com/foo?bar=baz
+   */
+  ATTR_HTTP_URL: 'http.url',
+
+  /**
+   * The message destination name.
+   *
+   * {@link ATTR_MESSAGING_DESTINATION_NAME} is newer and should be used.
+   */
+  ATTR_MESSAGING_DESTINATION: 'messaging.destination',
+
+  /**
+   * The kind of message destination (don't really know, this is what the
+   * otel code calls it).
+   */
+  ATTR_MESSAGING_DESTINATION_KIND: 'messaging.destination_kind',
+
+  /**
+   * The target queue name for the message to be delivered to.
+   *
+   * @example MyQueue
+   * @example MyTopic
+   */
+  ATTR_MESSAGING_DESTINATION_NAME: 'messaging.destination.name',
+
+  /**
+   * Target messaging system name.
+   *
+   * @example kafka
+   * @see https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/
+   */
+  ATTR_MESSAGING_SYSTEM: 'messaging.system',
+
+  /**
+   * The collection being accessed.
+   */
+  ATTR_MONGODB_COLLECTION: 'db.mongodb.collection',
+
+  /**
+   * Remote host name.
+   */
+  ATTR_NET_PEER_NAME: 'net.peer.name',
+
+  /**
+   * Remote port number.
+   */
+  ATTR_NET_PEER_PORT: 'net.peer.port',
+
+  /**
+   * The name of the remote method being invoked.
+   */
+  ATTR_RPC_METHOD: 'rpc.method',
+
+  /**
+   * The logical name of the service being called.
+   *
+   * @example myservice.EchoService
+   */
+  ATTR_RPC_SERVICE: 'rpc.service',
+
+  /**
+   * Defines the RPC technology being instrumented. Will be a string name
+   * for a known RPC system.
+   *
+   * @example grpc
+   * @see https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/
+   */
+  ATTR_RPC_SYSTEM: 'rpc.system',
+
+  /**
+   * Logical name of the local service being instrumented.
+   */
+  ATTR_SERVICE_NAME: 'service.name',
+
+  /**
+   * URL path component, e.g. `/foo` in `http://example.com/foo`. This is
+   * the fully realized path. See {@link ATTR_HTTP_ROUTE} for the framework
+   * representation.
+   */
+  ATTR_URL_PATH: 'url.path',
+
+  /* !!! Miscellaneous !!! */
+  /**
+   * Database system names.
+   *
+   * @example mysql
+   */
+  DB_SYSTEM_VALUES: {
+    ADABAS: 'adabas',
+    CACHE: 'cache',
+    CASSANDRA: 'cassandra',
+    CLOUDSCAPE: 'cloudscape',
+    COCKROACHDB: 'cockroachdb',
+    COLDFUSION: 'coldfusion',
+    COSMOSDB: 'cosmosdb',
+    COUCHBASE: 'couchbase',
+    COUCHDB: 'couchdb',
+    DB2: 'DB2',
+    DERBY: 'derby',
+    DYNAMODB: 'dynamodb',
+    EDB: 'edb',
+    ELASTICSEARCH: 'elasticsearch',
+    FILEMAKER: 'filemaker',
+    FIREBIRD: 'firebird',
+    FIRSTSQL: 'firstsql',
+    GEODE: 'geode',
+    H2: 'h2',
+    HANADB: 'handadb',
+    HBASE: 'hbase',
+    HIVE: 'hive',
+    HSQLDB: 'hsqldb',
+    INFORMIX: 'informix',
+    INGRESS: 'ingres',
+    INSTANTDB: 'instantdb',
+    INTERBASE: 'interbase',
+    MARIADB: 'mariadb',
+    MAXDB: 'maxdb',
+    MEMCACHED: 'memcached',
+    MONGODB: 'mongodb',
+    MSSQL: 'mssql',
+    MYSQL: 'mysql',
+    NEO4J: 'neo4j',
+    NETEZZA: 'netezza',
+    ORACLE: 'oracle',
+    OTHER_SQL: 'other_sql',
+    PERVASIVE: 'pervasive',
+    POINTBASE: 'pointbase',
+    POSTGRESQL: 'postgresql',
+    PROGRESS: 'progress',
+    REDIS: 'redis',
+    REDSHIFT: 'redshift',
+    SQLITE: 'sqlite',
+    SYBASE: 'sybase',
+    TERADATA: 'teradata',
+    VERTICA: 'vertica',
+  },
+
+  /**
+   * Kinds of messaging system destinations.
+   */
+  MESSAGING_SYSTEM_KIND_VALUES: {
+    QUEUE: 'queue',
+    TOPIC: 'topic'
+  }
+}

lib/otel/constants.js

@@ -16,18 +16,18 @@ const Transaction = require('../../transaction/')
 const { DESTINATIONS, TYPES } = Transaction
 
 const {
-  SEMATTRS_MESSAGING_SYSTEM,
-  SEMATTRS_MESSAGING_DESTINATION,
-  SEMATTRS_MESSAGING_DESTINATION_KIND
-} = require('@opentelemetry/semantic-conventions')
+  ATTR_MESSAGING_DESTINATION,
+  ATTR_MESSAGING_DESTINATION_KIND,
+  ATTR_MESSAGING_SYSTEM
+} = require('../constants')
 
 function createConsumerSegment(agent, otelSpan) {
   const transaction = new Transaction(agent)
   transaction.type = TYPES.BG
 
-  const system = otelSpan.attributes[SEMATTRS_MESSAGING_SYSTEM] ?? 'unknown'
-  const destination = otelSpan.attributes[SEMATTRS_MESSAGING_DESTINATION] ?? 'unknown'
-  const destKind = otelSpan.attributes[SEMATTRS_MESSAGING_DESTINATION_KIND] ?? 'unknown'
+  const system = otelSpan.attributes[ATTR_MESSAGING_SYSTEM] ?? 'unknown'
+  const destination = otelSpan.attributes[ATTR_MESSAGING_DESTINATION] ?? 'unknown'
+  const destKind = otelSpan.attributes[ATTR_MESSAGING_DESTINATION_KIND] ?? 'unknown'
   const segmentName = `OtherTransaction/Message/${system}/${destKind}/Named/${destination}`
 
   const txAttrs = transaction.trace.attributes

lib/otel/segments/consumer.js

@@ -4,26 +4,28 @@
  */
 
 'use strict'
-const {
-  SEMATTRS_DB_MONGODB_COLLECTION,
-  SEMATTRS_DB_SYSTEM,
-  SEMATTRS_DB_SQL_TABLE,
-  SEMATTRS_DB_OPERATION,
-  SEMATTRS_DB_STATEMENT,
-  DbSystemValues
-} = require('@opentelemetry/semantic-conventions')
+
 const parseSql = require('../../db/query-parsers/sql')
 const recordQueryMetrics = require('../../metrics/recorders/database')
 const recordOperationMetrics = require('../../metrics/recorders/database-operation')
 const ParsedStatement = require('../../db/parsed-statement')
 const metrics = require('../../metrics/names')
 
+const {
+  ATTR_DB_OPERATION,
+  ATTR_DB_SQL_TABLE,
+  ATTR_DB_STATEMENT,
+  ATTR_DB_SYSTEM,
+  ATTR_MONGODB_COLLECTION,
+  DB_SYSTEM_VALUES
+} = require('../constants')
+
 // TODO: This probably has some holes
 // I did analysis and tried to apply the best logic
 // to extract table/operation
 module.exports = function createDbSegment(agent, otelSpan) {
   const context = agent.tracer.getContext()
-  const system = otelSpan.attributes[SEMATTRS_DB_SYSTEM]
+  const system = otelSpan.attributes[ATTR_DB_SYSTEM]
   const parsed = parseStatement(agent.config, otelSpan, system)
   const { name, operation } = setName(parsed)
   const segment = agent.tracer.createSegment({
@@ -74,9 +76,9 @@ function getRecorder({ parsed, operation, system }) {
  * @returns {ParsedStatement} instance of parsed statement
  */
 function parseStatement(config, otelSpan, system) {
-  let table = otelSpan.attributes[SEMATTRS_DB_SQL_TABLE]
-  let operation = otelSpan.attributes[SEMATTRS_DB_OPERATION]
-  let statement = otelSpan.attributes[SEMATTRS_DB_STATEMENT]
+  let table = otelSpan.attributes[ATTR_DB_SQL_TABLE]
+  let operation = otelSpan.attributes[ATTR_DB_OPERATION]
+  let statement = otelSpan.attributes[ATTR_DB_STATEMENT]
   if (statement && !(table || operation)) {
     const parsed = parseSql({ sql: statement })
     if (parsed.operation && !operation) {
@@ -88,11 +90,11 @@ function parseStatement(config, otelSpan, system) {
     }
     statement = parsed.query
   }
-  if (system === DbSystemValues.MONGODB) {
-    table = otelSpan.attributes[SEMATTRS_DB_MONGODB_COLLECTION]
+  if (system === DB_SYSTEM_VALUES.MONGODB) {
+    table = otelSpan.attributes[ATTR_MONGODB_COLLECTION]
   }
 
-  if (system === DbSystemValues.REDIS && statement) {
+  if (system === DB_SYSTEM_VALUES.REDIS && statement) {
     ;[operation] = statement.split(' ')
   }
 
@@ -121,7 +123,7 @@ function setName(parsed) {
   let operation = false
   let name = `Datastore/statement/${parsed.type}/${parsed.collection}/${parsed.operation}`
   // All segment name shapes are same except redis/memcached
-  if (parsed.type === DbSystemValues.REDIS || parsed.type === DbSystemValues.MEMCACHED) {
+  if (parsed.type === DB_SYSTEM_VALUES.REDIS || parsed.type === DB_SYSTEM_VALUES.MEMCACHED) {
     name = `Datastore/operation/${parsed.type}/${parsed.operation}`
     operation = true
   }

lib/otel/segments/database.js

@@ -4,13 +4,17 @@
  */
 
 'use strict'
+
 const NAMES = require('../../metrics/names')
-const { SEMATTRS_HTTP_HOST } = require('@opentelemetry/semantic-conventions')
 const recordExternal = require('../../metrics/recorders/http_external')
 
+const {
+  ATTR_HTTP_HOST
+} = require('../constants')
+
 module.exports = function createHttpExternalSegment(agent, otelSpan) {
   const context = agent.tracer.getContext()
-  const host = otelSpan.attributes[SEMATTRS_HTTP_HOST] || 'Unknown'
+  const host = otelSpan.attributes[ATTR_HTTP_HOST] || 'Unknown'
   const name = NAMES.EXTERNAL.PREFIX + host
   const segment = agent.tracer.createSegment({
     name,

lib/otel/segments/http-external.js

@@ -4,11 +4,12 @@
  */
 
 'use strict'
+
 const {
-  SEMATTRS_MESSAGING_SYSTEM,
-  SEMATTRS_MESSAGING_DESTINATION,
-  SEMATTRS_MESSAGING_DESTINATION_KIND
-} = require('@opentelemetry/semantic-conventions')
+  ATTR_MESSAGING_DESTINATION,
+  ATTR_MESSAGING_DESTINATION_KIND,
+  ATTR_MESSAGING_SYSTEM
+} = require('../constants')
 
 module.exports = function createProducerSegment(agent, otelSpan) {
   const context = agent.tracer.getContext()
@@ -22,8 +23,8 @@ module.exports = function createProducerSegment(agent, otelSpan) {
 }
 
 function setName(otelSpan) {
-  const system = otelSpan.attributes[SEMATTRS_MESSAGING_SYSTEM] || 'Unknown'
-  const destKind = otelSpan.attributes[SEMATTRS_MESSAGING_DESTINATION_KIND] || 'Unknown'
-  const destination = otelSpan.attributes[SEMATTRS_MESSAGING_DESTINATION] || 'Unknown'
+  const system = otelSpan.attributes[ATTR_MESSAGING_SYSTEM] || 'Unknown'
+  const destKind = otelSpan.attributes[ATTR_MESSAGING_DESTINATION_KIND] || 'Unknown'
+  const destination = otelSpan.attributes[ATTR_MESSAGING_DESTINATION] || 'Unknown'
   return `MessageBroker/${system}/${destKind}/Produce/Named/${destination}`
 }