@superblocksteam/telemetry 2.0.83-next.1

package/LICENSE.txt

@@ -0,0 +1,87 @@
+Superblocks Community Software License
+
+This Superblocks Community License Agreement (the “Agreement”) sets forth the terms on which DayZero
+Software, Inc. d/b/a Superblocks (“Superblocks”) makes available certain software made available by Superblocks
+under this Agreement (the “Software”). BY INSTALLING, DOWNLOADING, ACCESSING, USING OR
+DISTRIBUTING ANY OF THE SOFTWARE, YOU AGREE TO THE TERMS AND CONDITIONS OF THIS
+AGREEMENT.IF YOU DO NOT AGREE TO SUCH TERMS AND CONDITIONS, YOU MUST NOT USE THE
+SOFTWARE. IF YOU ARE RECEIVING THE SOFTWARE ON BEHALF OF A LEGAL ENTITY, YOU
+REPRESENT AND WARRANT THAT YOU HAVE THE ACTUAL AUTHORITY TO AGREE TO THE
+TERMS AND CONDITIONS OF THIS AGREEMENT ON BEHALF OF SUCH ENTITY. “Licensee” means you,
+an individual, or the entity on whose behalf you are receiving the Software.
+
+1. LICENSE GRANT AND CONDITIONS.
+
+1.1 License. Subject to the terms and conditions of this Agreement, Superblocks hereby grants to Licensee a
+non-exclusive, royalty-free, worldwide, non-transferable, non-sublicenseable license during the term of this
+Agreement to: (a) use the Software; (b) prepare modifications and derivative works of the Software; (c)
+distribute the Software (including without limitation in source code or object code form); and (d) reproduce
+copies of the Software (the “License”). Licensee is not granted the right to, and Licensee shall not, exercise the
+License for an Excluded Purpose. For purposes of this Agreement, “Excluded Purpose” means making
+available any software-as-a-service, platform-as-a-service, infrastructure-as-a-service or other similar online
+service that competes with Superblocks’ products or services.
+
+1.2 Conditions. In consideration of the License, Licensee’s distribution of the Software is subject to the
+following conditions:
+
+  a. Licensee must cause any Software modified by Licensee to carry prominent notices stating that Licensee
+  modified the Software.
+  b. On each Software copy, Licensee shall reproduce and not remove or alter all Superblocks or third party
+  copyright or other proprietary notices contained in the Software, and Licensee must provide the notice
+  below with each copy.
+
+  “This software is made available by DayZero Software, Inc. d/b/a Superblocks, under the terms of the
+  Superblocks Community License Agreement. © 2022 DayZero Software, Inc.”
+
+1.3 Licensee Modifications. Licensee may add its own copyright notices to modifications made by Licensee
+and may provide additional or different license terms and conditions for use, reproduction, or distribution of
+Licensee’s modifications. While redistributing the Software or modifications thereof, Licensee may choose to
+offer, for a fee or free of charge, support, warranty, indemnity, or other obligations. Licensee, and not
+Superblocks, will be responsible for any such obligations.
+
+1.4 No Sublicensing. The License does not include the right to sublicense the Software, however, each recipient
+to which Licensee provides the Software may exercise the Licenses so long as such recipient agrees to the terms
+and conditions of this Agreement.
+
+2. TERM AND TERMINATION. This Agreement will continue unless and until earlier terminated as set forth
+herein. If Licensee breaches any of its conditions or obligations under this Agreement, this Agreement will
+terminate automatically and the License will terminate automatically and permanently.
+
+3. INTELLECTUAL PROPERTY. As between the parties, Superblocks will retain all right, title, and interest in
+the Software, and all intellectual property rights therein. Superblocks hereby reserves all rights not expressly
+granted to Licensee in this Agreement. Superblocks hereby reserves all rights in its trademarks and service
+marks, and no licenses therein are granted in this Agreement.
+
+4. DISCLAIMER. SUPERBLOCKS HEREBY DISCLAIMS ANY AND ALL WARRANTIES AND
+CONDITIONS, EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, AND SPECIFICALLY
+DISCLAIMS ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE, WITH RESPECT TO THE SOFTWARE.
+
+5. LIMITATION OF LIABILITY. SUPERBLOCKS WILL NOT BE LIABLE FOR ANY DAMAGES OF
+ANY KIND, INCLUDING BUT NOT LIMITED TO, LOST PROFITS OR ANY CONSEQUENTIAL,
+SPECIAL, INCIDENTAL, INDIRECT, OR DIRECT DAMAGES, HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, ARISING OUT OF THIS AGREEMENT. THE FOREGOING SHALL APPLY TO
+THE EXTENT PERMITTED BY APPLICABLE LAW.
+
+6. GENERAL.
+
+6.1  Governing Law. This Agreement will be governed by and interpreted in accordance with the laws of the
+state of California, without reference to its conflict of laws principles. If Licensee is located within the United
+States, all disputes arising out of this Agreement are subject to the exclusive jurisdiction of courts located in San
+Mateo County, California. USA. If Licensee is located outside of the United States, any dispute, controversy or
+claim arising out of or relating to this Agreement will be referred to and finally determined by arbitration in
+accordance with the JAMS International Arbitration Rules. The tribunal will consist of one neutral arbitrator.
+The place of arbitration will be Palo Alto, California. The language to be used in the arbitral proceedings will be
+English. Judgment upon the award rendered by the arbitrator may be entered in any court having jurisdiction
+thereof.
+
+6.2.  Assignment. Licensee may not assign its rights under this Agreement to any third party. Superblocks may
+freely assign its rights under this Agreement to any third party.
+
+6.3.  Other.  This Agreement is the entire agreement between the parties regarding the subject matter hereof.
+No amendment or modification of this Agreement will be valid or binding upon the parties unless made in
+writing and signed by the duly authorized representatives of both parties. In the event that any provision,
+including without limitation any condition, of this Agreement is held to be unenforceable, this Agreement and
+all licenses and rights granted hereunder will immediately terminate. Waiver by Superblocks of a breach of any
+provision of this Agreement or the failure by Superblocks to exercise any right hereunder will not be construed
+as a waiver of any subsequent breach of that right or as a waiver of any other right.

package/README.md

@@ -0,0 +1,155 @@
+# @superblocksteam/telemetry
+
+Canonical telemetry bootstrap package for all Superblocks services. This package provides policy-aware OpenTelemetry initialization with tier-based routing and sanitization.
+
+## Overview
+
+This is the **ONLY approved way** to initialize OpenTelemetry in Superblocks services. Direct usage of `NodeSDK` or `WebTracerProvider` outside this package is prohibited.
+
+## Tiered Telemetry Model
+
+| Tier | Description | Egress |
+|------|-------------|--------|
+| **Tier 1** | Full fidelity debugging (code, prompts, stack traces) | Local only (cloud-prem) |
+| **Tier 2** | Sanitized operational telemetry (latency, errors, token usage) | Exported by default |
+| **Tier 3** | AI experience telemetry (prompts, responses, quality signals) | Exported by default |
+
+## 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: process.env.NODE_ENV ?? 'development',
+  otlpUrl: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+}, policy);
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await telemetry.shutdown();
+});
+```
+
+### Browser
+
+```typescript
+import { initBrowserTelemetry } from '@superblocksteam/telemetry/browser';
+import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+
+const policy = getDefaultPolicy(DeploymentType.CLOUD);
+
+initBrowserTelemetry({
+  serviceName: 'superblocks-ui',
+  serviceVersion: '1.0.0',
+  environment: 'production',
+  otlpUrl: 'https://app.superblocks.com/api/v1/traces',
+}, policy);
+```
+
+### Testing
+
+```typescript
+import { initTestTelemetry } from '@superblocksteam/telemetry/testing';
+
+describe('MyService', () => {
+  const { spanExporter, reset } = initTestTelemetry();
+
+  beforeEach(() => reset());
+
+  it('creates expected spans', async () => {
+    await myService.doSomething();
+
+    const spans = spanExporter.getSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0].name).toBe('doSomething');
+  });
+
+  it('does not leak Tier 1 data', async () => {
+    await myService.processWithSensitiveData();
+
+    spanExporter.assertNoAttribute('prompt', /.*/);
+    spanExporter.assertNoAttribute('code', /.*/);
+  });
+});
+```
+
+## Tier Policy Hints
+
+Use tier policy hints to inform the Collector how to route specific spans. This is useful when the SDK knows something the Collector can't infer from attributes alone.
+
+```typescript
+import { trace } from '@opentelemetry/api';
+import { markSensitive, markForAIAnalysis, markDebugOnly } from '@superblocksteam/telemetry';
+
+const tracer = trace.getTracer('my-service');
+
+// Span containing secrets — Tier 1 only, never exported
+tracer.startActiveSpan('decrypt_customer_secret', (span) => {
+  markSensitive(span);
+  // ... decrypt operation
+  span.end();
+});
+
+// GenAI span for quality analysis — include in Tier 3
+tracer.startActiveSpan('gen_ai.chat', (span) => {
+  markForAIAnalysis(span);
+  span.setAttribute('gen_ai.system', 'anthropic');
+  // ... LLM call
+  span.end();
+});
+
+// High-cardinality debug span — skip export (cost control)
+tracer.startActiveSpan('debug.cache_lookup', (span) => {
+  markDebugOnly(span);
+  span.setAttribute('cache.key', cacheKey);
+  // ... lookup
+  span.end();
+});
+```
+
+### Available Hints
+
+| Helper | Hint Value | Effect |
+|--------|------------|--------|
+| `markSensitive(span)` | `tier1_only` | Tier 1 only, skip Tier 2/3 |
+| `markForAIAnalysis(span)` | `include_tier3` | Include in Tier 3 (AI analytics) |
+| `markDebugOnly(span)` | `skip_export` | Tier 1 only, skip all export |
+
+You can also set hints directly:
+
+```typescript
+import { TIER_HINT_ATTRIBUTE, TierPolicyHint } from '@superblocksteam/telemetry';
+
+span.setAttribute(TIER_HINT_ATTRIBUTE, TierPolicyHint.TIER1_ONLY);
+```
+
+## Key Principles
+
+1. **Policy Required** — Cannot initialize telemetry without a `TelemetryPolicy`
+2. **Tier Enforcement** — Exporters are automatically enabled/disabled based on policy
+3. **Sanitization at Source** — Tier 2/3 payloads are sanitized before export
+4. **Fire-and-Forget** — Export failures never block core request paths
+5. **Consistent Resources** — All services emit standardized resource attributes
+
+## Package Structure
+
+```
+@superblocksteam/telemetry
+├── /node          # Node.js bootstrap (initNodeTelemetry)
+├── /browser       # Browser bootstrap (initBrowserTelemetry)  
+├── /testing       # Test utilities (in-memory exporters)
+└── /common        # Shared utilities (resource, router, sanitizer)
+```
+
+## Related Documentation
+
+- [O11y Refactor Project](../../engineering/projects/o11y-refactor/README.md)
+- [Telemetry Policy Schema](../../engineering/projects/o11y-refactor/epics/epic-a1-telemetry-policy.md)
+- [Tier 2 Traces Contract](https://github.com/superblocksteam/engineering/blob/main/projects/o11y-refactor/contracts/tier2-traces.v0.3.0.json)

package/dist/browser/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser Telemetry Bootstrap
+ *
+ * This is the ONLY approved way to initialize telemetry in browser contexts.
+ */
+export { initBrowserTelemetry, getBrowserTelemetryInstance, isBrowserTelemetryInitialized, resetBrowserTelemetry, getEnvironmentFromHostname, type BrowserTelemetryInstance, } from './init.js';
+export { getDefaultPolicy, DeploymentType } from '../types/policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,6BAA6B,EAC7B,qBAAqB,EACrB,0BAA0B,EAC1B,KAAK,wBAAwB,GAC9B,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/browser/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Browser Telemetry Bootstrap
+ *
+ * This is the ONLY approved way to initialize telemetry in browser contexts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeploymentType = exports.getDefaultPolicy = exports.getEnvironmentFromHostname = exports.resetBrowserTelemetry = exports.isBrowserTelemetryInitialized = exports.getBrowserTelemetryInstance = exports.initBrowserTelemetry = void 0;
+var init_js_1 = require("./init.js");
+Object.defineProperty(exports, "initBrowserTelemetry", { enumerable: true, get: function () { return init_js_1.initBrowserTelemetry; } });
+Object.defineProperty(exports, "getBrowserTelemetryInstance", { enumerable: true, get: function () { return init_js_1.getBrowserTelemetryInstance; } });
+Object.defineProperty(exports, "isBrowserTelemetryInitialized", { enumerable: true, get: function () { return init_js_1.isBrowserTelemetryInitialized; } });
+Object.defineProperty(exports, "resetBrowserTelemetry", { enumerable: true, get: function () { return init_js_1.resetBrowserTelemetry; } });
+Object.defineProperty(exports, "getEnvironmentFromHostname", { enumerable: true, get: function () { return init_js_1.getEnvironmentFromHostname; } });
+// Re-export policy utilities for convenience
+var policy_js_1 = require("../types/policy.js");
+Object.defineProperty(exports, "getDefaultPolicy", { enumerable: true, get: function () { return policy_js_1.getDefaultPolicy; } });
+Object.defineProperty(exports, "DeploymentType", { enumerable: true, get: function () { return policy_js_1.DeploymentType; } });
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,qCAOmB;AANjB,+GAAA,oBAAoB,OAAA;AACpB,sHAAA,2BAA2B,OAAA;AAC3B,wHAAA,6BAA6B,OAAA;AAC7B,gHAAA,qBAAqB,OAAA;AACrB,qHAAA,0BAA0B,OAAA;AAI5B,6CAA6C;AAC7C,gDAAsE;AAA7D,6GAAA,gBAAgB,OAAA;AAAE,2GAAA,cAAc,OAAA"}

package/dist/browser/init.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Browser Telemetry Bootstrap
+ *
+ * This is the ONLY approved way to initialize telemetry in browser contexts.
+ * Direct WebTracerProvider usage outside this package is prohibited.
+ */
+import { Tracer } from "@opentelemetry/api";
+import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
+import { TelemetryPolicyEvaluator } from "../common/policy-evaluator.js";
+import type { BrowserTelemetryConfig } from "../types/index.js";
+import { TelemetryPolicy } from "../types/policy.js";
+/**
+ * Browser telemetry instance.
+ */
+export interface BrowserTelemetryInstance {
+    /** The underlying WebTracerProvider */
+    provider: WebTracerProvider;
+    /** Policy evaluator for runtime decisions */
+    policyEvaluator: TelemetryPolicyEvaluator;
+    /** Get a tracer */
+    getTracer: (name?: string) => Tracer;
+    /** Graceful shutdown */
+    shutdown: () => Promise<void>;
+}
+/**
+ * Initialize browser telemetry with policy enforcement.
+ *
+ * Browser telemetry is always sanitized (Tier 2) since it runs in untrusted context.
+ * Full fidelity Tier 1 data should never be emitted from the browser.
+ *
+ * @param config - Browser configuration
+ * @param policy - Telemetry policy (REQUIRED)
+ * @returns Browser telemetry instance
+ *
+ * @example
+ * ```typescript
+ * import { initBrowserTelemetry } from '@superblocksteam/telemetry/browser';
+ * import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+ *
+ * const policy = getDefaultPolicy(DeploymentType.CLOUD);
+ * const telemetry = initBrowserTelemetry({
+ *   serviceName: 'superblocks-ui',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ *   otlpUrl: 'https://app.superblocks.com/api/v1/traces',
+ * }, policy);
+ *
+ * const tracer = telemetry.getTracer();
+ * ```
+ */
+export declare function initBrowserTelemetry(config: BrowserTelemetryConfig, policy: TelemetryPolicy): BrowserTelemetryInstance;
+/**
+ * Get the current browser telemetry instance.
+ *
+ * @throws Error if not initialized
+ */
+export declare function getBrowserTelemetryInstance(): BrowserTelemetryInstance;
+/**
+ * Check if browser telemetry is initialized.
+ */
+export declare function isBrowserTelemetryInitialized(): boolean;
+/**
+ * Reset browser telemetry (for testing only).
+ * @internal
+ */
+export declare function resetBrowserTelemetry(): void;
+/**
+ * Derive environment from hostname.
+ * Utility for browser context where env vars aren't available.
+ *
+ * @param hostname - The hostname to analyze
+ * @returns Environment string
+ */
+export declare function getEnvironmentFromHostname(hostname: string): string;
+//# sourceMappingURL=init.d.ts.map

package/dist/browser/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/browser/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAS,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAUjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAiB,MAAM,oBAAoB,CAAC;AAGpE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,uCAAuC;IACvC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,6CAA6C;IAC7C,eAAe,EAAE,wBAAwB,CAAC;IAC1C,mBAAmB;IACnB,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,wBAAwB;IACxB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAmCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,sBAAsB,EAC9B,MAAM,EAAE,eAAe,GACtB,wBAAwB,CAkE1B;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,wBAAwB,CAOtE;AAED;;GAEG;AACH,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWnE"}

package/dist/browser/init.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Browser Telemetry Bootstrap
+ *
+ * This is the ONLY approved way to initialize telemetry in browser contexts.
+ * Direct WebTracerProvider usage outside this package is prohibited.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initBrowserTelemetry = initBrowserTelemetry;
+exports.getBrowserTelemetryInstance = getBrowserTelemetryInstance;
+exports.isBrowserTelemetryInitialized = isBrowserTelemetryInitialized;
+exports.resetBrowserTelemetry = resetBrowserTelemetry;
+exports.getEnvironmentFromHostname = getEnvironmentFromHostname;
+const api_1 = require("@opentelemetry/api");
+const sdk_trace_web_1 = require("@opentelemetry/sdk-trace-web");
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+const core_1 = require("@opentelemetry/core");
+const resource_js_1 = require("../common/resource.js");
+const policy_evaluator_js_1 = require("../common/policy-evaluator.js");
+const policy_js_1 = require("../types/policy.js");
+const resilient_exporter_js_1 = require("./resilient-exporter.js");
+// Singleton instance
+let instance;
+/**
+ * Validate browser telemetry configuration.
+ *
+ * @param config - Configuration to validate
+ * @throws Error if configuration is invalid
+ */
+function validateBrowserTelemetryConfig(config) {
+    if (!config.serviceName?.trim()) {
+        throw new Error("[Telemetry] serviceName is required and cannot be empty");
+    }
+    if (!config.serviceVersion?.trim()) {
+        throw new Error("[Telemetry] serviceVersion is required and cannot be empty");
+    }
+    if (!config.environment?.trim()) {
+        throw new Error("[Telemetry] environment is required and cannot be empty");
+    }
+    if (!config.otlpUrl?.trim()) {
+        throw new Error("[Telemetry] otlpUrl is required for browser telemetry");
+    }
+    try {
+        new URL(config.otlpUrl);
+    }
+    catch (error) {
+        throw new Error(`[Telemetry] Invalid otlpUrl: ${config.otlpUrl} (${error.message})`);
+    }
+}
+/**
+ * Initialize browser telemetry with policy enforcement.
+ *
+ * Browser telemetry is always sanitized (Tier 2) since it runs in untrusted context.
+ * Full fidelity Tier 1 data should never be emitted from the browser.
+ *
+ * @param config - Browser configuration
+ * @param policy - Telemetry policy (REQUIRED)
+ * @returns Browser telemetry instance
+ *
+ * @example
+ * ```typescript
+ * import { initBrowserTelemetry } from '@superblocksteam/telemetry/browser';
+ * import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+ *
+ * const policy = getDefaultPolicy(DeploymentType.CLOUD);
+ * const telemetry = initBrowserTelemetry({
+ *   serviceName: 'superblocks-ui',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ *   otlpUrl: 'https://app.superblocks.com/api/v1/traces',
+ * }, policy);
+ *
+ * const tracer = telemetry.getTracer();
+ * ```
+ */
+function initBrowserTelemetry(config, policy) {
+    // Policy is required
+    if (!policy) {
+        throw new Error("[Telemetry] Policy is required. Cannot initialize telemetry without a policy.");
+    }
+    // Validate config
+    validateBrowserTelemetryConfig(config);
+    // Return existing instance if already initialized
+    if (instance) {
+        console.warn("[Telemetry] Browser provider already initialized");
+        return instance;
+    }
+    const policyEvaluator = new policy_evaluator_js_1.TelemetryPolicyEvaluator(policy);
+    const resource = (0, resource_js_1.buildResource)(config);
+    // Build span processors based on policy
+    // Use isExportEnabled (not canExport) - sampling applies at runtime, not initialization
+    const spanProcessors = policyEvaluator.isExportEnabled(policy_js_1.TelemetryTier.TIER_2_OPERATIONAL)
+        ? [
+            new sdk_trace_base_1.BatchSpanProcessor(new resilient_exporter_js_1.BrowserResilientExporter({
+                delegate: new exporter_trace_otlp_http_1.OTLPTraceExporter({ url: config.otlpUrl }),
+            })),
+        ]
+        : [];
+    // Create provider with span processors in constructor (OTEL v2.x API)
+    const provider = new sdk_trace_web_1.WebTracerProvider({
+        resource,
+        spanProcessors,
+    });
+    // Register with composite propagator for W3C TraceContext and Baggage
+    provider.register({
+        propagator: new core_1.CompositePropagator({
+            propagators: [
+                new core_1.W3CBaggagePropagator(),
+                new core_1.W3CTraceContextPropagator(),
+            ],
+        }),
+    });
+    console.debug(`[Telemetry] Browser tracing initialized for ${config.serviceName} (${policy.deploymentType})`);
+    instance = {
+        provider,
+        policyEvaluator,
+        getTracer: (name) => api_1.trace.getTracer(name ?? config.serviceName, config.serviceVersion),
+        shutdown: async () => {
+            await provider.shutdown();
+            instance = undefined;
+        },
+    };
+    return instance;
+}
+/**
+ * Get the current browser telemetry instance.
+ *
+ * @throws Error if not initialized
+ */
+function getBrowserTelemetryInstance() {
+    if (!instance) {
+        throw new Error("[Telemetry] Not initialized. Call initBrowserTelemetry() first.");
+    }
+    return instance;
+}
+/**
+ * Check if browser telemetry is initialized.
+ */
+function isBrowserTelemetryInitialized() {
+    return instance !== undefined;
+}
+/**
+ * Reset browser telemetry (for testing only).
+ * @internal
+ */
+function resetBrowserTelemetry() {
+    instance = undefined;
+}
+/**
+ * Derive environment from hostname.
+ * Utility for browser context where env vars aren't available.
+ *
+ * @param hostname - The hostname to analyze
+ * @returns Environment string
+ */
+function getEnvironmentFromHostname(hostname) {
+    if (hostname.includes("localhost") || hostname.includes("127.0.0.1")) {
+        return "local";
+    }
+    if (hostname.includes("staging") || hostname.includes("stg")) {
+        return "staging";
+    }
+    if (hostname.includes("dev") || hostname.includes("development")) {
+        return "development";
+    }
+    return "production";
+}
+//# sourceMappingURL=init.js.map

package/dist/browser/init.js.map

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

package/dist/browser/resilient-exporter.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Browser Resilient Exporter
+ *
+ * Simplified resilient exporter for browser environments.
+ * Ensures export failures don't affect the main thread.
+ */
+import type { SpanExporter, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import { ExportResult } from "@opentelemetry/core";
+/**
+ * Configuration for the browser resilient exporter.
+ */
+export interface BrowserResilientExporterConfig {
+    /** Underlying exporter to wrap */
+    delegate: SpanExporter;
+    /** Max items to buffer before dropping (default: 512, lower than Node for memory) */
+    maxQueueSize?: number;
+    /** Export timeout in ms (default: 10000, shorter for browser) */
+    exportTimeoutMs?: number;
+    /** Callback when items are dropped */
+    onDrop?: (count: number, reason: "queue_full" | "export_failed" | "timeout") => void;
+}
+/**
+ * Browser-compatible resilient exporter.
+ *
+ * CRITICAL: Export failures must never block or affect the main thread.
+ * This wrapper catches all errors and timeouts.
+ */
+export declare class BrowserResilientExporter implements SpanExporter {
+    private readonly delegate;
+    private readonly maxQueueSize;
+    private readonly exportTimeoutMs;
+    private readonly onDrop;
+    private queuedCount;
+    private shuttingDown;
+    constructor(config: BrowserResilientExporterConfig);
+    /**
+     * Export spans with resilient error handling.
+     */
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+//# sourceMappingURL=resilient-exporter.d.ts.map

package/dist/browser/resilient-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilient-exporter.d.ts","sourceRoot":"","sources":["../../src/browser/resilient-exporter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,YAAY,EAAoB,MAAM,qBAAqB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,kCAAkC;IAClC,QAAQ,EAAE,YAAY,CAAC;IACvB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,eAAe,GAAG,SAAS,KAAK,IAAI,CAAC;CACtF;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGb;IAEV,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,8BAA8B;IAOlD;;OAEG;IACH,MAAM,CACJ,KAAK,EAAE,YAAY,EAAE,EACrB,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAC7C,IAAI;IAiDD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAKzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/browser/resilient-exporter.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Browser Resilient Exporter
+ *
+ * Simplified resilient exporter for browser environments.
+ * Ensures export failures don't affect the main thread.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserResilientExporter = void 0;
+const core_1 = require("@opentelemetry/core");
+/**
+ * Browser-compatible resilient exporter.
+ *
+ * CRITICAL: Export failures must never block or affect the main thread.
+ * This wrapper catches all errors and timeouts.
+ */
+class BrowserResilientExporter {
+    delegate;
+    maxQueueSize;
+    exportTimeoutMs;
+    onDrop;
+    queuedCount = 0;
+    shuttingDown = false;
+    constructor(config) {
+        this.delegate = config.delegate;
+        this.maxQueueSize = config.maxQueueSize ?? 512;
+        this.exportTimeoutMs = config.exportTimeoutMs ?? 10000;
+        this.onDrop = config.onDrop ?? (() => { });
+    }
+    /**
+     * Export spans with resilient error handling.
+     */
+    export(spans, resultCallback) {
+        // Reject during shutdown
+        if (this.shuttingDown) {
+            resultCallback({ code: core_1.ExportResultCode.SUCCESS });
+            return;
+        }
+        // Check backpressure
+        if (this.queuedCount + spans.length > this.maxQueueSize) {
+            this.onDrop(spans.length, "queue_full");
+            resultCallback({ code: core_1.ExportResultCode.SUCCESS });
+            return;
+        }
+        this.queuedCount += spans.length;
+        let completed = false;
+        // Timeout handler
+        const timeoutId = setTimeout(() => {
+            if (completed)
+                return;
+            completed = true;
+            this.queuedCount -= spans.length;
+            this.onDrop(spans.length, "timeout");
+            resultCallback({ code: core_1.ExportResultCode.SUCCESS });
+        }, this.exportTimeoutMs);
+        try {
+            this.delegate.export(spans, (result) => {
+                if (completed)
+                    return;
+                completed = true;
+                clearTimeout(timeoutId);
+                this.queuedCount -= spans.length;
+                if (result.code !== core_1.ExportResultCode.SUCCESS) {
+                    this.onDrop(spans.length, "export_failed");
+                }
+                resultCallback({ code: core_1.ExportResultCode.SUCCESS });
+            });
+        }
+        catch {
+            if (completed)
+                return;
+            completed = true;
+            clearTimeout(timeoutId);
+            this.queuedCount -= spans.length;
+            this.onDrop(spans.length, "export_failed");
+            resultCallback({ code: core_1.ExportResultCode.SUCCESS });
+        }
+    }
+    async shutdown() {
+        this.shuttingDown = true;
+        return this.delegate.shutdown();
+    }
+    async forceFlush() {
+        return this.delegate.forceFlush?.() ?? Promise.resolve();
+    }
+}
+exports.BrowserResilientExporter = BrowserResilientExporter;
+//# sourceMappingURL=resilient-exporter.js.map