@superblocksteam/telemetry 2.0.83-next.1

package/dist-esm/common/policy-evaluator.js

@@ -0,0 +1,196 @@
+/**
+ * Policy Evaluator
+ *
+ * Evaluates telemetry routing decisions based on policy configuration.
+ */
+import { TelemetryTier, EnforcementMode, } from "../types/policy.js";
+/**
+ * Evaluator for telemetry policy decisions.
+ *
+ * IMPORTANT: This evaluator determines ROUTING eligibility, not trace sampling.
+ *
+ * For TRACES: Sampling must be handled by the OTel SDK Sampler (parent-based,
+ * trace-ID ratio) to ensure trace consistency.
+ *
+ * For METRICS/LOGS: sampleRate applies with deterministic trace-ID-based logic.
+ */
+export class TelemetryPolicyEvaluator {
+    policy;
+    constructor(policy) {
+        this.policy = policy;
+    }
+    /**
+     * Get the current policy.
+     */
+    getPolicy() {
+        return this.policy;
+    }
+    /**
+     * Evaluate whether a telemetry signal should be processed/exported.
+     *
+     * @param tier - The tier this signal belongs to
+     * @param orgId - Optional org ID for org-specific overrides
+     * @param traceId - Optional trace ID for deterministic sampling
+     * @returns PolicyDecision
+     */
+    evaluate(tier, orgId, traceId) {
+        const effectivePolicy = this.getEffectivePolicy(orgId);
+        const tierConfig = effectivePolicy.tiers[tier];
+        if (!tierConfig.enabled) {
+            return {
+                retainLocal: false,
+                export: false,
+                sampled: false,
+                blockReason: `Tier ${tier} is disabled`,
+            };
+        }
+        // Use trace-ID-based deterministic sampling (NOT Math.random)
+        // This ensures same trace ID = same decision across all services.
+        //
+        // SAMPLING FALLBACK BEHAVIOR:
+        // When no traceId is provided (e.g., for standalone metrics or logs),
+        // we only sample if sampleRate >= 1.0. This is intentionally conservative:
+        // - For traces: traceId should always be available from span context
+        // - For metrics: typically want 100% capture (sampleRate = 1.0) or explicit control
+        // - For logs: same as metrics
+        //
+        // If probabilistic sampling without traceId is needed, callers should generate
+        // a synthetic traceId or use a different sampling mechanism.
+        const sampled = traceId
+            ? this.traceIdBasedSample(traceId, tierConfig.sampleRate)
+            : tierConfig.sampleRate >= 1.0;
+        return {
+            retainLocal: tierConfig.enabled,
+            export: tierConfig.exportEnabled && sampled,
+            sampled,
+        };
+    }
+    /**
+     * Check if export infrastructure should be created for a tier.
+     *
+     * This checks ONLY whether export is enabled in policy configuration.
+     * It does NOT apply sampling - use this for SDK initialization decisions.
+     *
+     * @param tier - The tier to check
+     * @param orgId - Optional org ID for org-specific overrides
+     * @returns true if export infrastructure should be created
+     */
+    isExportEnabled(tier, orgId) {
+        const effectivePolicy = this.getEffectivePolicy(orgId);
+        const tierConfig = effectivePolicy.tiers[tier];
+        return tierConfig.enabled && tierConfig.exportEnabled;
+    }
+    /**
+     * Check if an export attempt is allowed (includes sampling).
+     *
+     * This applies sampling logic and should be used for per-span/per-signal
+     * decisions at runtime, NOT for infrastructure initialization.
+     *
+     * @param tier - The tier to check
+     * @param orgId - Optional org ID for org-specific overrides
+     * @param traceId - Optional trace ID for deterministic sampling
+     * @returns true if export is allowed for this specific signal
+     */
+    canExport(tier, orgId, traceId) {
+        const decision = this.evaluate(tier, orgId, traceId);
+        return decision.export;
+    }
+    /**
+     * Assert export is allowed, throwing or logging based on enforcement mode.
+     *
+     * @param tier - The tier to check
+     * @param orgId - Optional org ID for org-specific overrides
+     * @throws Error if in ENFORCE mode and export is blocked
+     */
+    assertCanExport(tier, orgId) {
+        if (!this.canExport(tier, orgId)) {
+            const msg = `Export blocked for tier ${tier}`;
+            if (this.policy.enforcementMode === EnforcementMode.ENFORCE) {
+                throw new Error(msg);
+            }
+            else {
+                console.warn(`[AUDIT] ${msg}`);
+            }
+        }
+    }
+    /**
+     * Check if Tier 3 content export is enabled.
+     *
+     * @returns true if Tier 3 prompts/responses can be exported
+     */
+    canExportTier3Content() {
+        return (this.canExport(TelemetryTier.TIER_3_AI_EXPERIENCE) &&
+            this.policy.tier3Content.contentExportEnabled);
+    }
+    /**
+     * Get the effective policy for an org (applying overrides if present).
+     *
+     * Performs deep merge for nested objects (tiers, tier3Content) to ensure
+     * partial overrides don't clobber unspecified configurations.
+     *
+     * @param orgId - Optional org ID
+     * @returns Effective policy
+     */
+    getEffectivePolicy(orgId) {
+        if (!orgId || !this.policy.orgOverrides?.[orgId]) {
+            return this.policy;
+        }
+        const override = this.policy.orgOverrides[orgId];
+        // Valid tier keys for filtering
+        const validTiers = new Set(Object.values(TelemetryTier));
+        // Deep merge tiers: only override specified tiers, preserve others
+        // Filter out invalid tier keys and null/undefined configs
+        const mergedTiers = override.tiers
+            ? {
+                ...this.policy.tiers,
+                ...Object.fromEntries(Object.entries(override.tiers)
+                    .filter(([tier, config]) => validTiers.has(tier) && config != null)
+                    .map(([tier, config]) => [
+                    tier,
+                    { ...this.policy.tiers[tier], ...config },
+                ])),
+            }
+            : this.policy.tiers;
+        // Deep merge tier3Content if present and not null
+        const mergedTier3Content = override.tier3Content != null
+            ? { ...this.policy.tier3Content, ...override.tier3Content }
+            : this.policy.tier3Content;
+        return {
+            ...this.policy,
+            ...override,
+            tiers: mergedTiers,
+            tier3Content: mergedTier3Content,
+        };
+    }
+    /**
+     * Deterministic sampling based on trace ID (W3C TraceContext recommendation).
+     * Uses last 8 hex chars for uniform distribution in [0, 1).
+     *
+     * @param traceId - The trace ID (must be at least 8 hex characters)
+     * @param sampleRate - Sample rate (0.0 - 1.0)
+     * @returns true if sampled
+     */
+    traceIdBasedSample(traceId, sampleRate) {
+        if (sampleRate >= 1.0)
+            return true;
+        if (sampleRate <= 0.0)
+            return false;
+        // Validate trace ID has sufficient hex characters
+        if (!traceId || traceId.length < 8) {
+            // Malformed trace ID - fail safe by not sampling
+            return false;
+        }
+        const sampleHex = traceId.slice(-8);
+        // Validate hex characters
+        if (!/^[0-9a-fA-F]{8}$/.test(sampleHex)) {
+            // Non-hex characters in trace ID - fail safe by not sampling
+            return false;
+        }
+        // Parse last 8 hex chars as 32-bit unsigned int (range: 0 to 0xFFFFFFFF)
+        // Divide by 2^32 (0x100000000) to get uniform distribution in [0, 1)
+        // Using 0xFFFFFFFF would incorrectly produce 1.0 for max trace IDs
+        const sampleValue = parseInt(sampleHex, 16) / 0x100000000;
+        return sampleValue < sampleRate;
+    }
+}
+//# sourceMappingURL=policy-evaluator.js.map

package/dist-esm/common/policy-evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-evaluator.js","sourceRoot":"","sources":["../../src/common/policy-evaluator.ts"],"names":[],"mappings":"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"}

package/dist-esm/common/resource.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Resource Builder
+ *
+ * Standardized resource attributes for all Superblocks services.
+ *
+ * CRITICAL: Resource Attributes vs Span Attributes
+ *
+ * `service.name`, `service.version`, and `deployment.environment.name` MUST be set as
+ * **resource attributes** (once, at SDK initialization), NOT as span attributes (per-span).
+ *
+ * - Resource attributes: Set once, inherited by all spans/metrics/logs
+ * - Span attributes: Set per-span, for request-specific data
+ */
+import { type Resource } from "@opentelemetry/resources";
+import type { BaseTelemetryConfig } from '../types/index.js';
+/**
+ * Required RESOURCE attributes for correlation.
+ * These must NOT be added as span attributes (they're inherited from resource).
+ */
+export declare const REQUIRED_RESOURCE_ATTRIBUTES: readonly ["service.name", "service.version", "deployment.environment.name"];
+/**
+ * Attributes that should NEVER be set at span level (use resource instead).
+ * Used by linting/validation to catch misuse.
+ */
+export declare const RESOURCE_ONLY_ATTRIBUTES: Set<string>;
+/**
+ * Superblocks namespace for custom resource attributes.
+ */
+export declare const SUPERBLOCKS_NAMESPACE = "superblocks";
+/**
+ * Build standardized resource for a Superblocks service.
+ *
+ * IMPORTANT: These are RESOURCE attributes (set once at init), not span attributes.
+ * They are inherited by ALL telemetry from this SDK instance.
+ *
+ * Semantic conventions used:
+ * - service.name (required)
+ * - service.version (required)
+ * - deployment.environment.name (required)
+ * - superblocks.* (custom namespace)
+ *
+ * @param config - Service configuration
+ * @returns Resource with standardized attributes
+ */
+export declare function buildResource(config: BaseTelemetryConfig): Resource;
+/**
+ * Validate that a resource has all required attributes.
+ *
+ * @param resource - Resource to validate
+ * @throws Error if missing required attributes
+ */
+export declare function validateResource(resource: Resource): void;
+/**
+ * Assert that span attributes don't include resource-only attributes.
+ * Throws an error if resource-only attributes are present.
+ * For use in linting/CI or development mode.
+ *
+ * @param spanAttrs - Span attributes to validate
+ * @throws Error if resource-only attributes are present
+ */
+export declare function assertNoResourceAttributes(spanAttrs: Record<string, unknown>): void;
+//# sourceMappingURL=resource.d.ts.map

package/dist-esm/common/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/common/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAOlC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAK7D;;;GAGG;AACH,eAAO,MAAM,4BAA4B,6EAI/B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,wBAAwB,aAKnC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,QAAQ,CAiBnE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAOzD;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CASnF"}

package/dist-esm/common/resource.js

@@ -0,0 +1,100 @@
+/**
+ * Resource Builder
+ *
+ * Standardized resource attributes for all Superblocks services.
+ *
+ * CRITICAL: Resource Attributes vs Span Attributes
+ *
+ * `service.name`, `service.version`, and `deployment.environment.name` MUST be set as
+ * **resource attributes** (once, at SDK initialization), NOT as span attributes (per-span).
+ *
+ * - Resource attributes: Set once, inherited by all spans/metrics/logs
+ * - Span attributes: Set per-span, for request-specific data
+ */
+import { resourceFromAttributes, defaultResource, } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
+/** OTEL semantic convention for deployment environment. */
+const ATTR_DEPLOYMENT_ENVIRONMENT_NAME = "deployment.environment.name";
+/**
+ * Required RESOURCE attributes for correlation.
+ * These must NOT be added as span attributes (they're inherited from resource).
+ */
+export const REQUIRED_RESOURCE_ATTRIBUTES = [
+    "service.name",
+    "service.version",
+    "deployment.environment.name",
+];
+/**
+ * Attributes that should NEVER be set at span level (use resource instead).
+ * Used by linting/validation to catch misuse.
+ */
+export const RESOURCE_ONLY_ATTRIBUTES = new Set([
+    "service.name",
+    "service.version",
+    "deployment.environment.name",
+    "superblocks.environment",
+]);
+/**
+ * Superblocks namespace for custom resource attributes.
+ */
+export const SUPERBLOCKS_NAMESPACE = 'superblocks';
+/**
+ * Build standardized resource for a Superblocks service.
+ *
+ * IMPORTANT: These are RESOURCE attributes (set once at init), not span attributes.
+ * They are inherited by ALL telemetry from this SDK instance.
+ *
+ * Semantic conventions used:
+ * - service.name (required)
+ * - service.version (required)
+ * - deployment.environment.name (required)
+ * - superblocks.* (custom namespace)
+ *
+ * @param config - Service configuration
+ * @returns Resource with standardized attributes
+ */
+export function buildResource(config) {
+    const baseAttributes = {
+        // OTEL semantic conventions — RESOURCE level, not span level
+        [ATTR_SERVICE_NAME]: config.serviceName,
+        [ATTR_SERVICE_VERSION]: config.serviceVersion,
+        [ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: config.environment,
+        // Superblocks namespace for compatibility
+        [`${SUPERBLOCKS_NAMESPACE}.environment`]: config.environment,
+    };
+    return defaultResource().merge(resourceFromAttributes({
+        ...baseAttributes,
+        ...config.resourceAttributes,
+    }));
+}
+/**
+ * Validate that a resource has all required attributes.
+ *
+ * @param resource - Resource to validate
+ * @throws Error if missing required attributes
+ */
+export function validateResource(resource) {
+    const attributes = resource.attributes;
+    for (const attr of REQUIRED_RESOURCE_ATTRIBUTES) {
+        if (!attributes[attr]) {
+            throw new Error(`Missing required resource attribute: ${attr}`);
+        }
+    }
+}
+/**
+ * Assert that span attributes don't include resource-only attributes.
+ * Throws an error if resource-only attributes are present.
+ * For use in linting/CI or development mode.
+ *
+ * @param spanAttrs - Span attributes to validate
+ * @throws Error if resource-only attributes are present
+ */
+export function assertNoResourceAttributes(spanAttrs) {
+    for (const key of Object.keys(spanAttrs)) {
+        if (RESOURCE_ONLY_ATTRIBUTES.has(key)) {
+            throw new Error(`Attribute '${key}' should be a RESOURCE attribute, not a span attribute. ` +
+                `Set it in ResourceConfig at SDK init, not per-span.`);
+        }
+    }
+}
+//# sourceMappingURL=resource.js.map

package/dist-esm/common/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/common/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,sBAAsB,EACtB,eAAe,GAEhB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,qCAAqC,CAAC;AAI7C,2DAA2D;AAC3D,MAAM,gCAAgC,GAAG,6BAA6B,CAAC;AAEvE;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,cAAc;IACd,iBAAiB;IACjB,6BAA6B;CACrB,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC;IAC9C,cAAc;IACd,iBAAiB;IACjB,6BAA6B;IAC7B,yBAAyB;CAC1B,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,MAA2B;IACvD,MAAM,cAAc,GAAe;QACjC,6DAA6D;QAC7D,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,WAAW;QACvC,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC,cAAc;QAC7C,CAAC,gCAAgC,CAAC,EAAE,MAAM,CAAC,WAAW;QAEtD,0CAA0C;QAC1C,CAAC,GAAG,qBAAqB,cAAc,CAAC,EAAE,MAAM,CAAC,WAAW;KAC7D,CAAC;IAEF,OAAO,eAAe,EAAE,CAAC,KAAK,CAC5B,sBAAsB,CAAC;QACrB,GAAG,cAAc;QACjB,GAAG,MAAM,CAAC,kBAAkB;KAC7B,CAAC,CACH,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAkB;IACjD,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,4BAA4B,EAAE,CAAC;QAChD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,wCAAwC,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,SAAkC;IAC3E,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACzC,IAAI,wBAAwB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,cAAc,GAAG,0DAA0D;gBACzE,qDAAqD,CACxD,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist-esm/common/tier-hints.d.ts

@@ -0,0 +1,182 @@
+/**
+ * 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
+ */
+import type { Span } from "@opentelemetry/api";
+/**
+ * The attribute key used for tier policy hints.
+ * Collector filters on this attribute to make routing decisions.
+ */
+export declare const 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);
+ * ```
+ */
+export declare enum 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).
+     */
+    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).
+     */
+    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."
+     */
+    SKIP_EXPORT = "skip_export"
+}
+/**
+ * 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();
+ * });
+ * ```
+ */
+export declare function setTierHint(span: Span, hint: TierPolicyHint): void;
+/**
+ * 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();
+ * });
+ * ```
+ */
+export declare function markSensitive(span: Span): void;
+/**
+ * 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();
+ * });
+ * ```
+ */
+export declare function markForAIAnalysis(span: Span): void;
+/**
+ * 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();
+ * });
+ * ```
+ */
+export declare function markDebugOnly(span: Span): void;
+/**
+ * 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
+ */
+export declare function getTierHint(span: {
+    attributes?: Record<string, unknown>;
+}): TierPolicyHint | 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
+ */
+export declare function shouldSkipTier2(hint: TierPolicyHint | undefined): boolean;
+/**
+ * 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
+ */
+export declare function shouldIncludeTier3(hint: TierPolicyHint | undefined): boolean;
+//# sourceMappingURL=tier-hints.d.ts.map

package/dist-esm/common/tier-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier-hints.d.ts","sourceRoot":"","sources":["../../src/common/tier-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,oBAAY,cAAc;IACxB;;;;;;;;;;OAUG;IACH,UAAU,eAAe;IAEzB;;;;;;;;;;OAUG;IACH,aAAa,kBAAkB;IAE/B;;;;;;;;;;;;OAYG;IACH,WAAW,gBAAgB;CAC5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAElE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAE9C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAElD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,GAAG,cAAc,GAAG,SAAS,CAS7B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,GAAG,OAAO,CAIzE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,GAAG,OAAO,CAE5E"}