@contrail/telemetry 2.0.10 → 2.0.11-alpha-semantic-convention.0

package/CHANGELOG.md

@@ -7,6 +7,10 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- **`buildContrailAttrName` helper** — Centralizes the `contrail.*` namespace prefix for custom OTel attributes. Returns a typed template literal (`contrail.${T}`) and enforces lowercase input at compile time. Existing constants (`ATTR_CONTRAIL_SYSTEM`, `ATTR_CONTRAIL_USER`, `ATTR_LOG_MESSAGE`, `ATTR_LOG_BODY`, `ATTR_LOG_PAYLOAD`) now use this helper instead of hardcoded strings.
+
 ## [2.0.10] - 2026-04-21
 
 ### Added

package/lib/logger/semantic-conventions.d.ts

@@ -1,6 +1,3 @@
-/**
- * Log-specific semantic conventions.
- */
 /**
  * Attribute key for the log message body.
  */

package/lib/logger/semantic-conventions.js

@@ -1,19 +1,20 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATTR_LOG_PAYLOAD = exports.ATTR_LOG_BODY = exports.ATTR_LOG_MESSAGE = void 0;
 /**
  * Log-specific semantic conventions.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ATTR_LOG_PAYLOAD = exports.ATTR_LOG_BODY = exports.ATTR_LOG_MESSAGE = void 0;
+const semantic_conventions_1 = require("../semantic-conventions");
 /**
  * Attribute key for the log message body.
  */
-exports.ATTR_LOG_MESSAGE = 'contrail.message';
+exports.ATTR_LOG_MESSAGE = (0, semantic_conventions_1.buildContrailAttrName)('message');
 /**
  * Custom attribute that duplicates the log body so it is available for
  * grouping / filtering in observability UIs that only expose custom attributes.
  */
-exports.ATTR_LOG_BODY = 'contrail.log.body';
+exports.ATTR_LOG_BODY = (0, semantic_conventions_1.buildContrailAttrName)('log.body');
 /**
  * Attribute key for user-provided log payload objects.
  */
-exports.ATTR_LOG_PAYLOAD = 'contrail.payload';
+exports.ATTR_LOG_PAYLOAD = (0, semantic_conventions_1.buildContrailAttrName)('payload');

package/lib/semantic-conventions.d.ts

@@ -22,6 +22,11 @@ export declare const ATTR_USER_ROLES: "user.roles";
  * @see https://opentelemetry.io/docs/specs/semconv/resource/deployment-environment/
  */
 export declare const ATTR_DEPLOYMENT_ENVIRONMENT_NAME: "deployment.environment.name";
+/**
+ * Builds a custom attribute name with the platform namespace prefix.
+ * @example buildContrailAttrName('event_workflow.task.id') // => 'contrail.event_workflow.task.id'
+ */
+export declare function buildContrailAttrName<T extends string>(name: T & Lowercase<T>): `contrail.${T}`;
 /**
  * Namespace for Contrail platform context.
  */

package/lib/semantic-conventions.js

@@ -9,6 +9,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ATTR_CONTRAIL_USER = exports.ATTR_CONTRAIL_SYSTEM = exports.ATTR_DEPLOYMENT_ENVIRONMENT_NAME = exports.ATTR_USER_ROLES = exports.ATTR_USER_EMAIL = exports.ATTR_USER_ID = void 0;
+exports.buildContrailAttrName = buildContrailAttrName;
 // ---------------------------------------------------------------------------
 // OTel-spec attributes not yet in the SDK
 // ---------------------------------------------------------------------------
@@ -31,11 +32,18 @@ exports.ATTR_DEPLOYMENT_ENVIRONMENT_NAME = 'deployment.environment.name';
 // ---------------------------------------------------------------------------
 // Contrail-custom attributes
 // ---------------------------------------------------------------------------
+/**
+ * Builds a custom attribute name with the platform namespace prefix.
+ * @example buildContrailAttrName('event_workflow.task.id') // => 'contrail.event_workflow.task.id'
+ */
+function buildContrailAttrName(name) {
+    return `contrail.${name}`;
+}
 /**
  * Namespace for Contrail platform context.
  */
-exports.ATTR_CONTRAIL_SYSTEM = 'contrail.system';
+exports.ATTR_CONTRAIL_SYSTEM = buildContrailAttrName('system');
 /**
  * Namespace for Contrail-custom user attributes (not in OTel spec).
  */
-exports.ATTR_CONTRAIL_USER = 'contrail.user';
+exports.ATTR_CONTRAIL_USER = buildContrailAttrName('user');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/telemetry",
-  "version": "2.0.10",
+  "version": "2.0.11-alpha-semantic-convention.0",
   "description": "Telemetry and monitoring utilities for contrail services",
   "main": "lib/index.js",
   "browser": "lib/index.browser.js",