@superblocksteam/telemetry 2.0.83-next.1

package/dist/common/tier-hints.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * Tier Policy Hints
+ *
+ * SDK-level hints that inform the OTEL Collector how to route spans.
+ * These are HINTS, not guarantees — the Collector makes final routing decisions.
+ *
+ * NOTE: This is different from tier TAGS (which indicate which pipeline processed
+ * a span). Hints are prescriptive ("please route this way"), tags are descriptive
+ * ("this was processed by Tier X"). The Collector adds tier tags; the SDK adds hints.
+ *
+ * See: engineering/projects/o11y-refactor/proposals/sdk-tier-policy-hints.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TierPolicyHint = exports.TIER_HINT_ATTRIBUTE = void 0;
+exports.setTierHint = setTierHint;
+exports.markSensitive = markSensitive;
+exports.markForAIAnalysis = markForAIAnalysis;
+exports.markDebugOnly = markDebugOnly;
+exports.getTierHint = getTierHint;
+exports.shouldSkipTier2 = shouldSkipTier2;
+exports.shouldIncludeTier3 = shouldIncludeTier3;
+/**
+ * The attribute key used for tier policy hints.
+ * Collector filters on this attribute to make routing decisions.
+ */
+exports.TIER_HINT_ATTRIBUTE = "superblocks.tier_hint";
+/**
+ * Tier policy hints that inform the Collector how to route spans.
+ *
+ * These are HINTS, not guarantees — the Collector makes final routing decisions
+ * based on its configuration. In cloud-prem deployments, the Collector respects
+ * these hints to control which tiers receive the span.
+ *
+ * @example
+ * ```typescript
+ * import { trace } from '@opentelemetry/api';
+ * import { TierPolicyHint, TIER_HINT_ATTRIBUTE } from '@superblocksteam/telemetry';
+ *
+ * const span = tracer.startSpan('sensitive_operation');
+ * span.setAttribute(TIER_HINT_ATTRIBUTE, TierPolicyHint.TIER1_ONLY);
+ * ```
+ */
+var TierPolicyHint;
+(function (TierPolicyHint) {
+    /**
+     * Route to Tier 1 only. Do not export to Tier 2 or Tier 3.
+     *
+     * Use for:
+     * - Spans containing customer secrets or credentials
+     * - Highly sensitive customer data that must not leave their environment
+     * - Debug/diagnostic spans that should remain local
+     *
+     * The span will be stored in the customer's Tier 1 backend (e.g., Tempo)
+     * but will NOT be exported to Superblocks (Tier 2) or AI analytics (Tier 3).
+     */
+    TierPolicyHint["TIER1_ONLY"] = "tier1_only";
+    /**
+     * Include in Tier 3 (AI quality analysis) in addition to Tier 1 and Tier 2.
+     *
+     * Use for:
+     * - GenAI spans that should be analyzed for quality metrics
+     * - AI/LLM operations where prompts and responses are valuable for analysis
+     * - Spans with AI quality signals (latency, token usage, etc.)
+     *
+     * The span will go to all tiers: Tier 1 (full fidelity), Tier 2 (sanitized),
+     * and Tier 3 (AI analytics with identity stripped).
+     */
+    TierPolicyHint["INCLUDE_TIER3"] = "include_tier3";
+    /**
+     * Skip all external export. Tier 1 (local) only, no Tier 2/3.
+     * Alias for TIER1_ONLY, kept for semantic clarity.
+     *
+     * Use for:
+     * - High-cardinality diagnostic spans (cost control)
+     * - Temporary debug spans that shouldn't persist
+     * - Spans that are only useful for local debugging
+     *
+     * This is functionally equivalent to TIER1_ONLY but communicates
+     * a different intent: "this is for cost/noise control" rather than
+     * "this contains sensitive data."
+     */
+    TierPolicyHint["SKIP_EXPORT"] = "skip_export";
+})(TierPolicyHint || (exports.TierPolicyHint = TierPolicyHint = {}));
+/**
+ * Set a tier policy hint on a span.
+ *
+ * This is a convenience function that sets the `superblocks.tier_hint` attribute.
+ * You can also set the attribute directly if preferred.
+ *
+ * @param span - The span to set the hint on
+ * @param hint - The tier policy hint
+ *
+ * @example
+ * ```typescript
+ * import { setTierHint, TierPolicyHint } from '@superblocksteam/telemetry';
+ *
+ * tracer.startActiveSpan('decrypt_secret', (span) => {
+ *   setTierHint(span, TierPolicyHint.TIER1_ONLY);
+ *   // ... perform operation
+ *   span.end();
+ * });
+ * ```
+ */
+function setTierHint(span, hint) {
+    span.setAttribute(exports.TIER_HINT_ATTRIBUTE, hint);
+}
+/**
+ * Mark a span as containing sensitive data that should not leave Tier 1.
+ *
+ * Use this for spans that handle customer secrets, credentials, or other
+ * highly sensitive data that must remain in the customer's environment.
+ *
+ * @param span - The span to mark as sensitive
+ *
+ * @example
+ * ```typescript
+ * import { markSensitive } from '@superblocksteam/telemetry';
+ *
+ * tracer.startActiveSpan('decrypt_customer_secret', (span) => {
+ *   markSensitive(span);
+ *   // ... decrypt operation
+ *   span.end();
+ * });
+ * ```
+ */
+function markSensitive(span) {
+    setTierHint(span, TierPolicyHint.TIER1_ONLY);
+}
+/**
+ * Mark a span for AI quality analysis (Tier 3).
+ *
+ * Use this for GenAI spans that should be analyzed for quality metrics.
+ * The span will go to all tiers, with Tier 3 receiving the content
+ * (prompts/responses) for AI quality analysis.
+ *
+ * @param span - The span to mark for AI analysis
+ *
+ * @example
+ * ```typescript
+ * import { markForAIAnalysis } from '@superblocksteam/telemetry';
+ *
+ * tracer.startActiveSpan('gen_ai.chat', (span) => {
+ *   markForAIAnalysis(span);
+ *   span.setAttribute('gen_ai.system', 'anthropic');
+ *   // ... LLM call
+ *   span.end();
+ * });
+ * ```
+ */
+function markForAIAnalysis(span) {
+    setTierHint(span, TierPolicyHint.INCLUDE_TIER3);
+}
+/**
+ * Mark a span as debug-only (no export to Tier 2/3).
+ *
+ * Use this for high-cardinality diagnostic spans where you want to
+ * control costs by preventing export to paid backends.
+ *
+ * @param span - The span to mark as debug-only
+ *
+ * @example
+ * ```typescript
+ * import { markDebugOnly } from '@superblocksteam/telemetry';
+ *
+ * tracer.startActiveSpan('debug.cache_lookup', (span) => {
+ *   markDebugOnly(span);
+ *   span.setAttribute('cache.key', cacheKey); // High cardinality OK
+ *   // ... lookup
+ *   span.end();
+ * });
+ * ```
+ */
+function markDebugOnly(span) {
+    setTierHint(span, TierPolicyHint.SKIP_EXPORT);
+}
+/**
+ * Check if a span has a tier hint set.
+ *
+ * @param span - The span to check (must be a ReadableSpan with attributes)
+ * @returns The tier hint if set, undefined otherwise
+ */
+function getTierHint(span) {
+    const hint = span.attributes?.[exports.TIER_HINT_ATTRIBUTE];
+    if (typeof hint === "string" &&
+        Object.values(TierPolicyHint).includes(hint)) {
+        return hint;
+    }
+    return undefined;
+}
+/**
+ * Check if a tier hint indicates the span should skip Tier 2 export.
+ *
+ * @param hint - The tier hint to check
+ * @returns true if Tier 2 should be skipped
+ */
+function shouldSkipTier2(hint) {
+    return (hint === TierPolicyHint.TIER1_ONLY || hint === TierPolicyHint.SKIP_EXPORT);
+}
+/**
+ * Check if a tier hint indicates the span should be included in Tier 3.
+ *
+ * @param hint - The tier hint to check
+ * @returns true if Tier 3 should be included
+ */
+function shouldIncludeTier3(hint) {
+    return hint === TierPolicyHint.INCLUDE_TIER3;
+}
+//# sourceMappingURL=tier-hints.js.map

package/dist/common/tier-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier-hints.js","sourceRoot":"","sources":["../../src/common/tier-hints.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAyFH,kCAEC;AAqBD,sCAEC;AAuBD,8CAEC;AAsBD,sCAEC;AAQD,kCAWC;AAQD,0CAIC;AAQD,gDAEC;AAxMD;;;GAGG;AACU,QAAA,mBAAmB,GAAG,uBAAuB,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,IAAY,cAyCX;AAzCD,WAAY,cAAc;IACxB;;;;;;;;;;OAUG;IACH,2CAAyB,CAAA;IAEzB;;;;;;;;;;OAUG;IACH,iDAA+B,CAAA;IAE/B;;;;;;;;;;;;OAYG;IACH,6CAA2B,CAAA;AAC7B,CAAC,EAzCW,cAAc,8BAAd,cAAc,QAyCzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,WAAW,CAAC,IAAU,EAAE,IAAoB;IAC1D,IAAI,CAAC,YAAY,CAAC,2BAAmB,EAAE,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,aAAa,CAAC,IAAU;IACtC,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,iBAAiB,CAAC,IAAU;IAC1C,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,aAAa,CAAC,IAAU;IACtC,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,IAE3B;IACC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,2BAAmB,CAAC,CAAC;IACpD,IACE,OAAO,IAAI,KAAK,QAAQ;QACxB,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,IAAsB,CAAC,EAC9D,CAAC;QACD,OAAO,IAAsB,CAAC;IAChC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,IAAgC;IAC9D,OAAO,CACL,IAAI,KAAK,cAAc,CAAC,UAAU,IAAI,IAAI,KAAK,cAAc,CAAC,WAAW,CAC1E,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,IAAgC;IACjE,OAAO,IAAI,KAAK,cAAc,CAAC,aAAa,CAAC;AAC/C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @superblocksteam/telemetry
+ *
+ * Canonical telemetry bootstrap package for all Superblocks services.
+ * Provides policy-aware OpenTelemetry initialization with tier-based routing.
+ *
+ * This package is the ONLY approved way to initialize telemetry.
+ * Direct usage of NodeSDK or WebTracerProvider is prohibited.
+ *
+ * ## Usage
+ *
+ * ### Node.js Services
+ *
+ * ```typescript
+ * import { initNodeTelemetry } from '@superblocksteam/telemetry/node';
+ * import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+ *
+ * const policy = getDefaultPolicy(DeploymentType.CLOUD_PREM);
+ * const telemetry = initNodeTelemetry({
+ *   serviceName: 'my-service',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ *   otlpUrl: 'http://localhost:4318',
+ * }, policy);
+ * ```
+ *
+ * ### Browser
+ *
+ * ```typescript
+ * import { initBrowserTelemetry } from '@superblocksteam/telemetry/browser';
+ * ```
+ *
+ * ### Testing
+ *
+ * ```typescript
+ * import { initTestTelemetry } from '@superblocksteam/telemetry/testing';
+ * ```
+ */
+export * from "./types/index.js";
+export * from "./common/index.js";
+export * from "./llmobs/index.js";
+export { initNodeTelemetry, getTelemetryInstance, isTelemetryInitialized, resetTelemetry, type NodeTelemetryInstance, MetricsClient, type Labels, type CounterHandle, type GaugeHandle, type HistogramHandle, TracedSocket, type TracedSocketConfig, type TracedSocketOptions, } from './node/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,EACd,KAAK,qBAAqB,EAC1B,aAAa,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * @superblocksteam/telemetry
+ *
+ * Canonical telemetry bootstrap package for all Superblocks services.
+ * Provides policy-aware OpenTelemetry initialization with tier-based routing.
+ *
+ * This package is the ONLY approved way to initialize telemetry.
+ * Direct usage of NodeSDK or WebTracerProvider is prohibited.
+ *
+ * ## Usage
+ *
+ * ### Node.js Services
+ *
+ * ```typescript
+ * import { initNodeTelemetry } from '@superblocksteam/telemetry/node';
+ * import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+ *
+ * const policy = getDefaultPolicy(DeploymentType.CLOUD_PREM);
+ * const telemetry = initNodeTelemetry({
+ *   serviceName: 'my-service',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ *   otlpUrl: 'http://localhost:4318',
+ * }, policy);
+ * ```
+ *
+ * ### Browser
+ *
+ * ```typescript
+ * import { initBrowserTelemetry } from '@superblocksteam/telemetry/browser';
+ * ```
+ *
+ * ### Testing
+ *
+ * ```typescript
+ * import { initTestTelemetry } from '@superblocksteam/telemetry/testing';
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TracedSocket = exports.MetricsClient = exports.resetTelemetry = exports.isTelemetryInitialized = exports.getTelemetryInstance = exports.initNodeTelemetry = void 0;
+// Re-export types
+__exportStar(require("./types/index.js"), exports);
+// Re-export common utilities
+__exportStar(require("./common/index.js"), exports);
+// Re-export LLMObs tiered telemetry
+__exportStar(require("./llmobs/index.js"), exports);
+// Re-export Node.js telemetry functions for convenience
+// This allows imports like: import { initNodeTelemetry } from '@superblocksteam/telemetry'
+var index_js_1 = require("./node/index.js");
+Object.defineProperty(exports, "initNodeTelemetry", { enumerable: true, get: function () { return index_js_1.initNodeTelemetry; } });
+Object.defineProperty(exports, "getTelemetryInstance", { enumerable: true, get: function () { return index_js_1.getTelemetryInstance; } });
+Object.defineProperty(exports, "isTelemetryInitialized", { enumerable: true, get: function () { return index_js_1.isTelemetryInitialized; } });
+Object.defineProperty(exports, "resetTelemetry", { enumerable: true, get: function () { return index_js_1.resetTelemetry; } });
+Object.defineProperty(exports, "MetricsClient", { enumerable: true, get: function () { return index_js_1.MetricsClient; } });
+Object.defineProperty(exports, "TracedSocket", { enumerable: true, get: function () { return index_js_1.TracedSocket; } });
+// Note: Browser and Testing modules are still exported via package.json subpath exports
+// Import them as:
+//   - @superblocksteam/telemetry/browser
+//   - @superblocksteam/telemetry/testing
+//   - @superblocksteam/telemetry/llmobs
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;;;;;;;;;;;;;;;;AAEH,kBAAkB;AAClB,mDAAiC;AAEjC,6BAA6B;AAC7B,oDAAkC;AAElC,oCAAoC;AACpC,oDAAkC;AAElC,wDAAwD;AACxD,2FAA2F;AAC3F,4CAcyB;AAbvB,6GAAA,iBAAiB,OAAA;AACjB,gHAAA,oBAAoB,OAAA;AACpB,kHAAA,sBAAsB,OAAA;AACtB,0GAAA,cAAc,OAAA;AAEd,yGAAA,aAAa,OAAA;AAKb,wGAAA,YAAY,OAAA;AAKd,wFAAwF;AACxF,kBAAkB;AAClB,yCAAyC;AACzC,yCAAyC;AACzC,wCAAwC"}

package/dist/lint/forbidden-attributes.d.ts

@@ -0,0 +1,149 @@
+/**
+ * ESLint Rule: No Forbidden Telemetry Attributes
+ *
+ * This rule detects usage of forbidden attributes in span/metric instrumentation.
+ * It catches common leak paths before code is merged.
+ *
+ * Usage in eslint.config.js:
+ * ```
+ * import { noForbiddenTelemetryAttributes } from '@superblocksteam/telemetry/lint';
+ *
+ * export default [
+ *   {
+ *     plugins: {
+ *       telemetry: { rules: { 'no-forbidden-attributes': noForbiddenTelemetryAttributes } }
+ *     },
+ *     rules: {
+ *       'telemetry/no-forbidden-attributes': 'error'
+ *     }
+ *   }
+ * ];
+ * ```
+ */
+/**
+ * Forbidden attribute patterns for static analysis.
+ */
+export declare const FORBIDDEN_ATTRIBUTE_PATTERNS: string[];
+/**
+ * ESLint rule metadata.
+ */
+export declare const noForbiddenTelemetryAttributesMeta: {
+    type: string;
+    docs: {
+        description: string;
+        category: string;
+        recommended: boolean;
+    };
+    messages: {
+        forbiddenAttribute: string;
+        resourceOnlyAttribute: string;
+    };
+    schema: never[];
+};
+/**
+ * ESLint rule implementation.
+ *
+ * Detects patterns like:
+ * - span.setAttribute('prompt', value)
+ * - span.setAttributes({ prompt: value })
+ * - { 'prompt': value }
+ */
+export declare function noForbiddenTelemetryAttributesCreate(context: any): {
+    CallExpression(node: any): void;
+    Property(node: any): void;
+};
+/**
+ * Complete ESLint rule export.
+ */
+export declare const noForbiddenTelemetryAttributes: {
+    meta: {
+        type: string;
+        docs: {
+            description: string;
+            category: string;
+            recommended: boolean;
+        };
+        messages: {
+            forbiddenAttribute: string;
+            resourceOnlyAttribute: string;
+        };
+        schema: never[];
+    };
+    create: typeof noForbiddenTelemetryAttributesCreate;
+};
+/**
+ * ESLint rule: No Direct OTEL SDK Usage
+ *
+ * Detects direct usage of NodeSDK or WebTracerProvider outside the telemetry package.
+ */
+export declare const noDirectOtelSdkMeta: {
+    type: string;
+    docs: {
+        description: string;
+        category: string;
+        recommended: boolean;
+    };
+    messages: {
+        directSdkUsage: string;
+    };
+    schema: never[];
+};
+export declare function noDirectOtelSdkCreate(context: any): {
+    ImportSpecifier?: undefined;
+    CallExpression?: undefined;
+} | {
+    ImportSpecifier(node: any): void;
+    CallExpression(node: any): void;
+};
+export declare const noDirectOtelSdk: {
+    meta: {
+        type: string;
+        docs: {
+            description: string;
+            category: string;
+            recommended: boolean;
+        };
+        messages: {
+            directSdkUsage: string;
+        };
+        schema: never[];
+    };
+    create: typeof noDirectOtelSdkCreate;
+};
+/**
+ * All telemetry ESLint rules.
+ */
+export declare const telemetryRules: {
+    'no-forbidden-attributes': {
+        meta: {
+            type: string;
+            docs: {
+                description: string;
+                category: string;
+                recommended: boolean;
+            };
+            messages: {
+                forbiddenAttribute: string;
+                resourceOnlyAttribute: string;
+            };
+            schema: never[];
+        };
+        create: typeof noForbiddenTelemetryAttributesCreate;
+    };
+    'no-direct-otel-sdk': {
+        meta: {
+            type: string;
+            docs: {
+                description: string;
+                category: string;
+                recommended: boolean;
+            };
+            messages: {
+                directSdkUsage: string;
+            };
+            schema: never[];
+        };
+        create: typeof noDirectOtelSdkCreate;
+    };
+};
+//# sourceMappingURL=forbidden-attributes.d.ts.map

package/dist/lint/forbidden-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forbidden-attributes.d.ts","sourceRoot":"","sources":["../../src/lint/forbidden-attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH;;GAEG;AACH,eAAO,MAAM,4BAA4B,UAKxC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;CAgB9C,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,oCAAoC,CAAC,OAAO,EAAE,GAAG;yBAsBxC,GAAG;mBA6BT,GAAG;EAuBrB;AAED;;GAEG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;CAG1C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;CAa/B,CAAC;AAYF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,GAAG;;;;0BASxB,GAAG;yBAYJ,GAAG;EAsB3B;AAED,eAAO,MAAM,eAAe;;;;;;;;;;;;;;CAG3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAG1B,CAAC"}