@mfeflow/telemetry 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @mfeflow/telemetry
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Telemetry for micro-frontends behind one provider interface. The shell starts it once; remotes take a tracer. Ships an OpenTelemetry web provider (OTLP/HTTP export, `fetch` tracing, Core Web Vitals) meant to load after first render.
+
+## Install
+
+```sh
+pnpm add @mfeflow/telemetry
+```
+
+In a project made with mfeflow, `mfeflow add telemetry-otel` does all of this.
+
+## Usage
+
+```ts
+// shell, once: the SDK is a separate chunk, loaded after the first paint
+import { initTelemetry } from '@mfeflow/telemetry';
+
+initTelemetry(async () => {
+  const { createOtelProvider } = await import('@mfeflow/telemetry/otel');
+  return createOtelProvider({
+    serviceName: 'shell',
+    version: '1.0.0',
+    environment: 'prod',
+    otlpEndpoint: 'https://collector.example.com/v1/traces',
+  });
+});
+```
+
+```ts
+// a remote
+import { getTracer } from '@mfeflow/telemetry';
+
+const tracer = getTracer('cart'); // every span carries mfe.name = cart
+tracer.startActiveSpan('cart.click', (span) => {
+  void fetch('/api/orders').finally(() => span.end()); // start the fetch before any await
+});
+```
+
+Remote failures reported by `@mfeflow/runtime` are forwarded through the `window` event it fires; nothing to wire.
+
+## Module Federation sharing
+
+Bucket: **singleton**. Share `@mfeflow/telemetry` (`@mfeflow/rsbuild` does). `@mfeflow/telemetry/otel` is imported by the shell only, through a dynamic `import()`. Its exporter and instrumentation packages are 0.x (experimental) OpenTelemetry releases.
+
+## Links
+
+- [mfeflow repository](https://github.com/mfeflow/mfeflow) and its README
+- [Documentation](https://mfeflow.github.io/mfeflow/)
+
+MIT licensed.

package/dist/core.d.ts

@@ -0,0 +1,33 @@
+import type { ErrorContext, TelemetryProvider, Tracer, WebVitalMetric } from './types.js';
+export type ProviderSource = TelemetryProvider | (() => Promise<TelemetryProvider>);
+export interface InitOptions {
+    /**
+     * When to load a provider that comes from a function. `idle` (default) waits for the page to
+     * finish loading, the first paint and an idle browser, so the SDK never competes with first render.
+     * `now` loads it immediately.
+     */
+    when?: 'idle' | 'now';
+    /** Called when the provider fails to load or start. The noop provider stays in place. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Starts telemetry. Only the shell calls this, and only once: later calls return false.
+ * A provider given as a function is loaded after first render; `reportError` and
+ * `recordWebVitals` calls made until it is ready are kept (the last 50) and replayed, including the
+ * remote failures `@mfeflow/runtime` reported before this ran. Spans started before that are not recorded.
+ */
+export declare function initTelemetry(source: ProviderSource, options?: InitOptions): boolean;
+/** Resolves when the provider is ready, or has failed to load. */
+export declare function telemetryReady(): Promise<void>;
+export declare function isTelemetryReady(): boolean;
+/** Sends whatever the provider has buffered. For tests and `pagehide` handlers. */
+export declare function flushTelemetry(): Promise<void>;
+/**
+ * The tracer for one remote. Every span it starts carries `mfe.name`. Take it once at import time:
+ * it follows the provider, so it records as soon as telemetry is ready.
+ */
+export declare function getTracer(mfeName: string, mfeVersion?: string): Tracer;
+export declare function reportError(error: unknown, context: ErrorContext): void;
+export declare function recordWebVitals(metric: WebVitalMetric): void;
+/** Only for tests. */
+export declare function resetTelemetryForTests(): void;

package/dist/core.js

@@ -0,0 +1,107 @@
+import { connectRemoteErrors, disconnectRemoteErrors } from "./errors.js";
+import { noopProvider } from "./noop.js";
+import { MfeTracer } from "./tracer.js";
+const KEY = Symbol.for('mfeflow.telemetry');
+const QUEUE_LIMIT = 50;
+function isState(value) {
+    return 'object' == typeof value && null !== value && 'queue' in value && 'provider' in value;
+}
+function state() {
+    const existing = Reflect.get(globalThis, KEY);
+    if (isState(existing)) return existing;
+    const fresh = {
+        provider: noopProvider,
+        started: false,
+        queue: [],
+        ready: Promise.resolve()
+    };
+    Reflect.set(globalThis, KEY, fresh);
+    return fresh;
+}
+const PAINT_WAIT_MS = 3000;
+function afterFirstPaint() {
+    return new Promise((resolve)=>{
+        let started = false;
+        const idle = ()=>{
+            if ('function' == typeof requestIdleCallback) requestIdleCallback(()=>{
+                resolve();
+            }, {
+                timeout: 2000
+            });
+            else setTimeout(resolve, 200);
+        };
+        const afterPaint = ()=>{
+            if (started) return;
+            started = true;
+            idle();
+        };
+        const painted = ()=>{
+            requestAnimationFrame(()=>{
+                setTimeout(afterPaint, 0);
+            });
+            setTimeout(afterPaint, PAINT_WAIT_MS);
+        };
+        if ('complete' === document.readyState) painted();
+        else addEventListener('load', painted, {
+            once: true
+        });
+    });
+}
+function initTelemetry(source, options = {}) {
+    const s = state();
+    if (s.started) return false;
+    s.started = true;
+    connectRemoteErrors(reportError);
+    const activate = async ()=>{
+        try {
+            const provider = 'function' == typeof source ? await source() : source;
+            await provider.init();
+            s.provider = provider;
+            for (const call of s.queue.splice(0))call(provider);
+        } catch (error) {
+            s.queue.length = 0;
+            options.onError?.(error);
+        }
+    };
+    const start = 'function' == typeof source && 'now' !== options.when ? afterFirstPaint().then(activate) : activate();
+    s.ready = start;
+    return true;
+}
+function telemetryReady() {
+    return state().ready;
+}
+function isTelemetryReady() {
+    return state().provider !== noopProvider;
+}
+async function flushTelemetry() {
+    await state().provider.flush?.();
+}
+function send(call) {
+    const s = state();
+    if (s.provider !== noopProvider) return void call(s.provider);
+    if (s.queue.length >= QUEUE_LIMIT) s.queue.shift();
+    s.queue.push(call);
+}
+function getTracer(mfeName, mfeVersion) {
+    return new MfeTracer(()=>state().provider.getTracer(mfeName), {
+        'mfe.name': mfeName,
+        ...void 0 === mfeVersion ? {} : {
+            'mfe.version': mfeVersion
+        }
+    });
+}
+function reportError(error, context) {
+    send((p)=>{
+        p.reportError(error, context);
+    });
+}
+function recordWebVitals(metric) {
+    send((p)=>{
+        p.recordWebVitals(metric);
+    });
+}
+function resetTelemetryForTests() {
+    disconnectRemoteErrors();
+    Reflect.deleteProperty(globalThis, KEY);
+}
+export { flushTelemetry, getTracer, initTelemetry, isTelemetryReady, recordWebVitals, reportError, resetTelemetryForTests, telemetryReady };

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+import type { ErrorContext } from './types.js';
+/**
+ * Sends every remote failure to `report`: the ones already recorded in `globalThis.mfeflowReports`
+ * and each one that follows. Connecting twice (StrictMode, a second copy) does not report twice.
+ * Returns a function that disconnects.
+ */
+export declare function connectRemoteErrors(report: (error: unknown, context: ErrorContext) => void): () => void;
+/** Disconnects whatever `connectRemoteErrors` connected on this page. */
+export declare function disconnectRemoteErrors(): void;

package/dist/errors.js

@@ -0,0 +1,34 @@
+const EVENT = 'mfeflow:remote-error';
+const CONNECTED = Symbol.for('mfeflow.telemetry.errors');
+const isFunction = (value)=>'function' == typeof value;
+function isRemoteReport(value) {
+    return 'object' == typeof value && null !== value && 'string' == typeof Reflect.get(value, 'mfe') && 'string' == typeof Reflect.get(value, 'where') && 'string' == typeof Reflect.get(value, 'message');
+}
+function connectRemoteErrors(report) {
+    if ("u" < typeof window || isFunction(Reflect.get(window, CONNECTED))) return ()=>{};
+    const forward = (item)=>{
+        if (!isRemoteReport(item)) return;
+        report(new Error(item.message), {
+            mfe: item.mfe,
+            where: item.where
+        });
+    };
+    const earlier = Reflect.get(globalThis, 'mfeflowReports');
+    if (Array.isArray(earlier)) for (const item of earlier)forward(item);
+    const onEvent = (event)=>{
+        forward(event instanceof CustomEvent ? event.detail : void 0);
+    };
+    window.addEventListener(EVENT, onEvent);
+    const disconnect = ()=>{
+        window.removeEventListener(EVENT, onEvent);
+        Reflect.deleteProperty(window, CONNECTED);
+    };
+    Reflect.set(window, CONNECTED, disconnect);
+    return disconnect;
+}
+function disconnectRemoteErrors() {
+    if ("u" < typeof window) return;
+    const disconnect = Reflect.get(window, CONNECTED);
+    if (isFunction(disconnect)) disconnect();
+}
+export { connectRemoteErrors, disconnectRemoteErrors };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { flushTelemetry, getTracer, initTelemetry, isTelemetryReady, recordWebVitals, reportError, resetTelemetryForTests, telemetryReady, type InitOptions, type ProviderSource, } from './core.js';
+export { connectRemoteErrors } from './errors.js';
+export { createRecordingProvider, noopProvider, type RecordedTelemetry } from './noop.js';
+export { MfeTracer } from './tracer.js';
+export type { Attributes, ErrorContext, Span, SpanOptions, TelemetryProvider, Tracer, WebVitalMetric, } from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { flushTelemetry, getTracer, initTelemetry, isTelemetryReady, recordWebVitals, reportError, resetTelemetryForTests, telemetryReady } from "./core.js";
+export { connectRemoteErrors } from "./errors.js";
+export { createRecordingProvider, noopProvider } from "./noop.js";
+export { MfeTracer } from "./tracer.js";

package/dist/noop.d.ts

@@ -0,0 +1,14 @@
+import type { ErrorContext, TelemetryProvider, WebVitalMetric } from './types.js';
+export declare const noopProvider: TelemetryProvider;
+export type RecordedTelemetry = {
+    type: 'error';
+    error: unknown;
+    context: ErrorContext;
+} | {
+    type: 'web-vital';
+    metric: WebVitalMetric;
+};
+/** A provider for tests: it sends nothing and remembers errors and web vitals in order. */
+export declare function createRecordingProvider(): TelemetryProvider & {
+    calls: RecordedTelemetry[];
+};

package/dist/noop.js

@@ -0,0 +1,31 @@
+import { trace } from "@opentelemetry/api";
+const noopProvider = {
+    name: 'noop',
+    init () {},
+    getTracer: (mfeName)=>trace.getTracer(mfeName),
+    reportError () {},
+    recordWebVitals () {}
+};
+function createRecordingProvider() {
+    const calls = [];
+    return {
+        name: 'recording',
+        calls,
+        init () {},
+        getTracer: (mfeName)=>trace.getTracer(mfeName),
+        reportError (error, context) {
+            calls.push({
+                type: 'error',
+                error,
+                context
+            });
+        },
+        recordWebVitals (metric) {
+            calls.push({
+                type: 'web-vital',
+                metric
+            });
+        }
+    };
+}
+export { createRecordingProvider, noopProvider };

package/dist/otel.d.ts

@@ -0,0 +1,73 @@
+import { type Context, type Span } from '@opentelemetry/api';
+import { type ReadableSpan, type SpanExporter, type SpanProcessor } from '@opentelemetry/sdk-trace';
+import type { TelemetryProvider } from './types.js';
+export interface OtelOptions {
+    /** `service.name`, e.g. `storefront-shell`. */
+    serviceName: string;
+    /** `service.version`: the shell's build version. */
+    version: string;
+    /** `deployment.environment.name`, e.g. `prod`. */
+    environment: string;
+    /** Full OTLP/HTTP traces URL, e.g. `https://collector.example.com/v1/traces`. From the runtime config. */
+    otlpEndpoint: string;
+    /** Share of traces to record, 0 to 1. A trace that starts elsewhere keeps its parent's decision. Default 1. */
+    sampleRatio?: number | undefined;
+    /**
+     * Cross-origin URL prefixes that get a `traceparent` header on `fetch`, e.g. `https://api.example.com`.
+     * Same-origin requests always get it. The server must allow the header in CORS.
+     */
+    propagateTraceHeaderCorsUrls?: readonly string[] | undefined;
+    /**
+     * Keep the query string on `url.full`. Off by default: queries carry tokens and personal data.
+     * Userinfo (`user:pass@`) and the fragment are removed either way.
+     */
+    recordQuery?: boolean | undefined;
+    /** Record Core Web Vitals as spans. Default true. */
+    webVitals?: boolean | undefined;
+    /** How long spans wait for a batch, in milliseconds. Default 5000. */
+    exportDelayMs?: number | undefined;
+    /** Replaces the OTLP exporter, e.g. with a console exporter while developing. */
+    exporter?: SpanExporter | undefined;
+}
+/**
+ * A URL prefix as an anchored pattern (the fetch instrumentation compares plain strings for
+ * equality). A prefix that does not end in `/` must be followed by a path, a query, a fragment or the
+ * end, so `https://api.example.com` does not match `https://api.example.com.evil.test`.
+ */
+export declare const prefixPattern: (prefix: string) => RegExp;
+export declare function clampRatio(ratio: number | undefined): number;
+/** Gives a span without `mfe.name` its parent's, so the `fetch` a remote makes inside its span carries the tag too. */
+export declare class MfeNameProcessor implements SpanProcessor {
+    onStart(span: ReadableSpan & Span, parentContext: Context): void;
+    onEnd(): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/** The longest message or stack a reported error may carry to the backend. */
+export declare const MAX_ERROR_TEXT = 4096;
+export declare function clip(text: string, max?: number): string;
+/** Origin and path of a URL, plus the query when asked. Never userinfo, never the fragment. */
+export declare function scrubUrl(value: string, recordQuery: boolean): string;
+/**
+ * Rewrites the URL attributes of every finished span before the batch processor sees it, so a token
+ * in `?token=` or `user:pass@` never reaches the exporter. It runs on end, not in the fetch
+ * instrumentation's own hook, because that hook is skipped when the request fails early.
+ */
+export declare class UrlScrubProcessor implements SpanProcessor {
+    private readonly recordQuery;
+    constructor(recordQuery: boolean);
+    onStart(): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * OpenTelemetry for the browser: one `TracerProvider` with the resource attributes, an OTLP/HTTP
+ * batch exporter, `fetch` tracing and Core Web Vitals. The shell loads this module after first
+ * render with a dynamic `import()`, so none of it is on the critical path.
+ *
+ * The context manager is the stack one: it follows synchronous calls, so a `fetch` started inside
+ * `startActiveSpan` is a child of that span. It does not follow `await` or timers; see the docs
+ * (zone.js was measured and does not follow native `await` either).
+ */
+export declare function createOtelProvider(options: OtelOptions): TelemetryProvider;

package/dist/otel.js

@@ -0,0 +1,189 @@
+import { SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchSpanProcessor, ParentBasedSampler, StackContextManager, TraceIdRatioBasedSampler, TracerProvider } from "@opentelemetry/sdk-trace";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+const otel_escape = (text)=>text.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+const prefixPattern = (prefix)=>new RegExp(`^${otel_escape(prefix)}${prefix.endsWith('/') ? '' : '(?:$|[/?#])'}`);
+function clampRatio(ratio) {
+    if (void 0 === ratio || Number.isNaN(ratio)) return 1;
+    return Math.min(1, Math.max(0, ratio));
+}
+function mfeNameOf(span) {
+    const attributes = span ? Reflect.get(span, 'attributes') : void 0;
+    return 'object' == typeof attributes && null !== attributes ? Reflect.get(attributes, 'mfe.name') : void 0;
+}
+class MfeNameProcessor {
+    onStart(span, parentContext) {
+        if (void 0 !== mfeNameOf(span)) return;
+        const name = mfeNameOf(trace.getSpan(parentContext));
+        if ('string' == typeof name) span.setAttribute('mfe.name', name);
+    }
+    onEnd() {}
+    forceFlush() {
+        return Promise.resolve();
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}
+const URL_ATTRIBUTES = [
+    'url.full',
+    'http.url'
+];
+const QUERY_ATTRIBUTES = [
+    'url.query',
+    'http.target'
+];
+const MAX_ERROR_TEXT = 4096;
+function clip(text, max = MAX_ERROR_TEXT) {
+    return text.length > max ? `${text.slice(0, max)}...[truncated]` : text;
+}
+function scrubUrl(value, recordQuery) {
+    try {
+        const url = new URL(value);
+        url.username = '';
+        url.password = '';
+        url.hash = '';
+        if (!recordQuery) url.search = '';
+        return url.href;
+    } catch  {
+        const cut = value.search(/[?#]/);
+        return -1 === cut ? value : value.slice(0, cut);
+    }
+}
+class UrlScrubProcessor {
+    recordQuery;
+    constructor(recordQuery){
+        this.recordQuery = recordQuery;
+    }
+    onStart() {}
+    onEnd(span) {
+        const attributes = span.attributes;
+        for (const key of URL_ATTRIBUTES){
+            const value = attributes[key];
+            if ('string' == typeof value) attributes[key] = scrubUrl(value, this.recordQuery);
+        }
+        if (!this.recordQuery) {
+            for (const key of QUERY_ATTRIBUTES){
+                const value = attributes[key];
+                if ('string' == typeof value) {
+                    const cut = value.indexOf('?');
+                    if (-1 === cut) continue;
+                    attributes[key] = value.slice(0, cut);
+                }
+            }
+            delete attributes['url.query'];
+        }
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}
+async function watchWebVitals(record) {
+    const { onCLS, onFCP, onINP, onLCP, onTTFB } = await import("web-vitals");
+    const forward = (metric)=>{
+        record({
+            name: metric.name,
+            value: metric.value,
+            rating: metric.rating,
+            id: metric.id
+        });
+    };
+    onCLS(forward);
+    onFCP(forward);
+    onINP(forward);
+    onLCP(forward);
+    onTTFB(forward);
+}
+function createOtelProvider(options) {
+    const exporter = options.exporter ?? new OTLPTraceExporter({
+        url: options.otlpEndpoint
+    });
+    const batch = new BatchSpanProcessor({
+        exporter,
+        scheduledDelayMillis: options.exportDelayMs ?? 5000
+    });
+    const provider = new TracerProvider({
+        resource: resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: options.serviceName,
+            [ATTR_SERVICE_VERSION]: options.version,
+            'deployment.environment.name': options.environment
+        }),
+        sampler: new ParentBasedSampler({
+            root: new TraceIdRatioBasedSampler(clampRatio(options.sampleRatio))
+        }),
+        spanProcessors: [
+            new MfeNameProcessor(),
+            new UrlScrubProcessor(true === options.recordQuery),
+            batch
+        ]
+    });
+    const recordWebVitals = (metric)=>{
+        const span = provider.getTracer('web-vitals').startSpan(`web_vital.${metric.name}`, {
+            attributes: {
+                'mfe.name': 'shell',
+                'web_vital.name': metric.name,
+                'web_vital.value': metric.value,
+                'web_vital.rating': metric.rating,
+                'web_vital.id': metric.id
+            }
+        });
+        span.end();
+    };
+    return {
+        name: 'otel',
+        init () {
+            trace.setGlobalTracerProvider(provider);
+            context.setGlobalContextManager(new StackContextManager().enable());
+            propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+            registerInstrumentations({
+                tracerProvider: provider,
+                instrumentations: [
+                    new FetchInstrumentation({
+                        ignoreUrls: [
+                            prefixPattern(options.otlpEndpoint)
+                        ],
+                        propagateTraceHeaderCorsUrls: (options.propagateTraceHeaderCorsUrls ?? []).map(prefixPattern)
+                    })
+                ]
+            });
+            if (false !== options.webVitals) watchWebVitals(recordWebVitals).catch((error)=>{
+                console.error('[mfeflow/telemetry] web vitals are not recorded', error);
+            });
+        },
+        getTracer: (mfeName)=>provider.getTracer(mfeName),
+        reportError (error, errorContext) {
+            const span = provider.getTracer(errorContext.mfe).startSpan('mfe.error', {
+                attributes: {
+                    'mfe.name': errorContext.mfe,
+                    ...void 0 === errorContext.where ? {} : {
+                        'mfe.error.where': errorContext.where
+                    }
+                }
+            });
+            const message = clip(error instanceof Error ? error.message : String(error));
+            span.recordException({
+                name: error instanceof Error ? error.name : 'Error',
+                message,
+                ...error instanceof Error && void 0 !== error.stack ? {
+                    stack: clip(error.stack)
+                } : {}
+            });
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message
+            });
+            span.end();
+        },
+        recordWebVitals,
+        flush: ()=>provider.forceFlush()
+    };
+}
+export { MAX_ERROR_TEXT, MfeNameProcessor, UrlScrubProcessor, clampRatio, clip, createOtelProvider, prefixPattern, scrubUrl };

package/dist/tracer.d.ts

@@ -0,0 +1,13 @@
+import type { Attributes, Context, Span, SpanOptions, Tracer } from '@opentelemetry/api';
+/**
+ * A tracer that looks up the real one on every call, so a tracer a remote took at import time
+ * starts recording once the provider is ready, and stamps `mfe.name` on every span it starts.
+ */
+export declare class MfeTracer implements Tracer {
+    #private;
+    constructor(resolve: () => Tracer, tags: Attributes);
+    startSpan(name: string, options?: SpanOptions, context?: Context): Span;
+    startActiveSpan<F extends (span: Span) => ReturnType<F>>(name: string, fn: F): ReturnType<F>;
+    startActiveSpan<F extends (span: Span) => ReturnType<F>>(name: string, options: SpanOptions, fn: F): ReturnType<F>;
+    startActiveSpan<F extends (span: Span) => ReturnType<F>>(name: string, options: SpanOptions, context: Context, fn: F): ReturnType<F>;
+}

package/dist/tracer.js

@@ -0,0 +1,28 @@
+class MfeTracer {
+    #resolve;
+    #tags;
+    constructor(resolve, tags){
+        this.#resolve = resolve;
+        this.#tags = tags;
+    }
+    #tagged(options) {
+        return {
+            ...options,
+            attributes: {
+                ...this.#tags,
+                ...options?.attributes
+            }
+        };
+    }
+    startSpan(name, options, context) {
+        return this.#resolve().startSpan(name, this.#tagged(options), context);
+    }
+    startActiveSpan(name, a, b, c) {
+        const tracer = this.#resolve();
+        if ('function' == typeof a) return tracer.startActiveSpan(name, this.#tagged(void 0), a);
+        if ('function' == typeof b) return tracer.startActiveSpan(name, this.#tagged(a), b);
+        if (void 0 === b || void 0 === c) throw new TypeError('startActiveSpan needs a function to run inside the span');
+        return tracer.startActiveSpan(name, this.#tagged(a), b, c);
+    }
+}
+export { MfeTracer };

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+import type { Tracer } from '@opentelemetry/api';
+export type { Attributes, Span, SpanOptions, Tracer } from '@opentelemetry/api';
+export interface ErrorContext {
+    /** The remote the error came from. */
+    mfe: string;
+    /** Where it failed, e.g. `render`, `load`, `registry`. */
+    where?: string | undefined;
+}
+/** The fields of a web-vitals metric the platform records. */
+export interface WebVitalMetric {
+    name: string;
+    value: number;
+    rating: 'good' | 'needs-improvement' | 'poor';
+    id: string;
+}
+export interface TelemetryProvider {
+    readonly name: string;
+    init(): void | Promise<void>;
+    getTracer(mfeName: string): Tracer;
+    reportError(error: unknown, context: ErrorContext): void;
+    recordWebVitals(metric: WebVitalMetric): void;
+    /** Sends what is buffered now. Tests call this instead of waiting for the batch timer. */
+    flush?: () => Promise<void>;
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@mfeflow/telemetry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Telemetry for micro-frontends behind one provider interface: a tracer per remote tagged with mfe.name, error reporting wired to remote failures, and an OpenTelemetry web provider loaded after first render.",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "opentelemetry",
+    "tracing",
+    "web-vitals"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/telemetry"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./otel": {
+      "types": "./dist/otel.d.ts",
+      "import": "./dist/otel.js",
+      "default": "./dist/otel.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@opentelemetry/api": "1.10.0",
+    "@opentelemetry/core": "3.0.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.300.0",
+    "@opentelemetry/instrumentation": "0.300.0",
+    "@opentelemetry/instrumentation-fetch": "0.300.0",
+    "@opentelemetry/resources": "3.0.0",
+    "@opentelemetry/sdk-trace": "3.0.0",
+    "@opentelemetry/semantic-conventions": "1.44.0",
+    "web-vitals": "6.2.3"
+  },
+  "devDependencies": {
+    "@rsbuild/plugin-react": "2.1.1",
+    "@rslib/core": "1.0.5",
+    "@types/node": "26.6.6",
+    "jsdom": "30.1.3",
+    "typescript": "7.0.2"
+  },
+  "mfeflow": {
+    "bucket": "singleton"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }