autotel-playwright 0.4.61 → 0.5.0

package/README.md

@@ -121,6 +121,8 @@ test('user flow', async ({ page }) => {
 - **`expect`** - Re-exported from `@playwright/test`.
 - **`createGlobalSetup(opts?)`** - Returns an async function that calls `autotel.init(opts)` for use as `globalSetup`.
 - **`AUTOTEL_ATTRIBUTE_ANNOTATION`** - Annotation type string for custom span attributes (`key=value` in description).
+- **`withBrowserSession(context, run, options?)`** (`autotel-playwright/session`) - Runs `run` inside a `browser.session` span that records the session's CPU, heap, network bytes, pages and console errors. See [Browser sessions outside tests](#browser-sessions-outside-tests).
+- **`BROWSER_SESSION_ATTRIBUTES`** (`autotel-playwright/session`) - The attribute names that span carries.
 
 ### Optional: reporter (test + step spans from runner)
 
@@ -138,6 +140,57 @@ export default defineConfig({
 
 Reporter creates one span per test (`e2e:${title}`) and one per step (`step:${title}`) as children. For a single trace that includes **test → API** (worker), use the fixture only; the reporter adds a parallel view from the runner.
 
+## Browser sessions outside tests
+
+`withBrowserSession()` puts a span around a whole browser session and records
+what the session cost. It takes a Playwright `BrowserContext`, so it works for
+agents and scrapers driving a browser in production, not only for tests.
+
+```ts
+import { chromium } from 'playwright';
+import { init } from 'autotel';
+import { withBrowserSession } from 'autotel-playwright/session';
+
+init({ service: 'browser-agent' });
+
+const context = await (await chromium.launch()).newContext();
+
+await withBrowserSession(context, async ({ sessionId }) => {
+  const page = await context.newPage();
+  await page.goto('https://example.com');
+  // Anything started in here joins the session's trace, including work whose
+  // RPC or HTTP calls carry W3C trace context.
+});
+```
+
+One `browser.session` span per session, carrying:
+
+| attribute                        | what it answers                                         |
+| -------------------------------- | ------------------------------------------------------- |
+| `session.id`                     | your id, or the span id when you pass none              |
+| `browser.session.cpu.time`       | seconds of browser CPU, summed over the session's pages |
+| `browser.session.memory.usage`   | peak JS heap in bytes                                   |
+| `browser.session.network.io`     | bytes on the wire, headers and bodies, both directions  |
+| `browser.session.pages`          | pages the session opened                                |
+| `browser.session.console.errors` | console errors plus uncaught page exceptions            |
+
+Console output arrives as `browser.console` span events (`error` and `warning`
+by default, `consoleLevels` to widen), and every uncaught page exception is
+recorded on the span. CPU and heap come from CDP and so are Chromium-only;
+network, console and timing work on every browser Playwright drives.
+
+```ts
+await withBrowserSession(context, run, {
+  sessionId: myWorkflowId,
+  consoleLevels: ['error', 'warning', 'info'],
+  attributes: { 'workflow.name': 'checkout-audit' },
+});
+```
+
+Pair it with `context.tracing.start({ screenshots: true, snapshots: true })` and
+pass the trace path in `attributes` when you want a replay to open from the span
+at [trace.playwright.dev](https://trace.playwright.dev).
+
 ## Configuration and troubleshooting
 
 ### API base URL with a path

package/dist/session.cjs

@@ -0,0 +1,120 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let autotel = require("autotel");
+//#region src/session.ts
+const TRACER_NAME = "autotel-playwright";
+const TRACER_VERSION = "0.1.0";
+/** Console levels recorded as span events when the caller names none. */
+const DEFAULT_CONSOLE_LEVELS = ["error", "warning"];
+/**
+* Session totals. `session.id` is canonical; the rest extend `browser.*`,
+* which OpenTelemetry defines for the browser but not for the driver.
+*/
+const BROWSER_SESSION_ATTRIBUTES = {
+	SESSION_ID: "session.id",
+	/** Seconds of browser CPU, summed over the session's pages. */
+	CPU_TIME: "browser.session.cpu.time",
+	/** Peak JS heap in bytes across the session's pages. */
+	MEMORY_USAGE: "browser.session.memory.usage",
+	/** Bytes on the wire, request and response, headers and bodies. */
+	NETWORK_IO: "browser.session.network.io",
+	PAGES: "browser.session.pages",
+	CONSOLE_ERRORS: "browser.session.console.errors",
+	CONSOLE_LEVEL: "browser.console.level",
+	CONSOLE_MESSAGE: "browser.console.message"
+};
+/**
+* Runs `run` inside a `browser.session` span and records what the session cost.
+* The span is active for the callback, so any instrumented work started inside
+* it - including an agent whose RPC propagates trace context - joins the trace.
+*/
+async function withBrowserSession(browserContext, run, options = {}) {
+	const levels = new Set(options.consoleLevels ?? DEFAULT_CONSOLE_LEVELS);
+	const span = (0, autotel.getTracer)(TRACER_NAME, TRACER_VERSION).startSpan("browser.session", { attributes: { ...options.attributes } });
+	const sessionId = options.sessionId ?? span.spanContext().spanId;
+	span.setAttribute(BROWSER_SESSION_ATTRIBUTES.SESSION_ID, sessionId);
+	const totals = {
+		consoleErrors: 0,
+		cpuTime: 0,
+		memoryUsage: 0,
+		networkIo: 0,
+		pages: 0
+	};
+	const pending = /* @__PURE__ */ new Set();
+	const cdpSessions = /* @__PURE__ */ new Map();
+	const track = (work) => {
+		pending.add(work);
+		work.finally(() => pending.delete(work));
+	};
+	/**
+	* CPU is cumulative per target, so one read at the end is the whole story;
+	* the heap read is a point in time, which is why closing pages are sampled
+	* too rather than only the ones still open when the session ends.
+	*/
+	const sample = async (page) => {
+		const session = cdpSessions.get(page);
+		cdpSessions.delete(page);
+		try {
+			const cdp = await session;
+			if (!cdp) return;
+			const { metrics } = await cdp.send("Performance.getMetrics");
+			const read = (name) => metrics.find((metric) => metric.name === name)?.value ?? 0;
+			totals.cpuTime += read("TaskDuration");
+			totals.memoryUsage = Math.max(totals.memoryUsage, read("JSHeapUsedSize"));
+		} catch {}
+	};
+	const addBytes = async (request) => {
+		try {
+			const sizes = await request.sizes();
+			totals.networkIo += sizes.requestBodySize + sizes.requestHeadersSize + sizes.responseBodySize + sizes.responseHeadersSize;
+		} catch {}
+	};
+	const attach = (page) => {
+		totals.pages += 1;
+		cdpSessions.set(page, browserContext.newCDPSession(page).then(async (cdp) => {
+			await cdp.send("Performance.enable");
+			return cdp;
+		}).catch(() => void 0));
+		page.on("console", (message) => {
+			const level = message.type();
+			if (level === "error") totals.consoleErrors += 1;
+			if (!levels.has(level)) return;
+			span.addEvent("browser.console", {
+				[BROWSER_SESSION_ATTRIBUTES.CONSOLE_LEVEL]: level,
+				[BROWSER_SESSION_ATTRIBUTES.CONSOLE_MESSAGE]: message.text()
+			});
+		});
+		page.on("pageerror", (error) => {
+			totals.consoleErrors += 1;
+			span.recordException(error);
+		});
+		page.on("requestfinished", (request) => track(addBytes(request)));
+		page.on("close", () => track(sample(page)));
+	};
+	browserContext.on("page", attach);
+	for (const page of browserContext.pages()) attach(page);
+	try {
+		return await autotel.context.with(autotel.otelTrace.setSpan(autotel.context.active(), span), () => run({ sessionId }));
+	} catch (error) {
+		span.recordException(error);
+		span.setStatus({
+			code: autotel.SpanStatusCode.ERROR,
+			message: error instanceof Error ? error.message : String(error)
+		});
+		throw error;
+	} finally {
+		browserContext.off("page", attach);
+		for (const page of cdpSessions.keys()) track(sample(page));
+		await Promise.allSettled([...pending]);
+		span.setAttributes({
+			[BROWSER_SESSION_ATTRIBUTES.CONSOLE_ERRORS]: totals.consoleErrors,
+			[BROWSER_SESSION_ATTRIBUTES.CPU_TIME]: totals.cpuTime,
+			[BROWSER_SESSION_ATTRIBUTES.MEMORY_USAGE]: totals.memoryUsage,
+			[BROWSER_SESSION_ATTRIBUTES.NETWORK_IO]: totals.networkIo,
+			[BROWSER_SESSION_ATTRIBUTES.PAGES]: totals.pages
+		});
+		span.end();
+	}
+}
+//#endregion
+exports.BROWSER_SESSION_ATTRIBUTES = BROWSER_SESSION_ATTRIBUTES;
+exports.withBrowserSession = withBrowserSession;

package/dist/session.d.cts

@@ -0,0 +1,37 @@
+import { BrowserContext } from "@playwright/test";
+//#region src/session.d.ts
+/**
+ * Session totals. `session.id` is canonical; the rest extend `browser.*`,
+ * which OpenTelemetry defines for the browser but not for the driver.
+ */
+declare const BROWSER_SESSION_ATTRIBUTES: {
+  readonly SESSION_ID: "session.id";
+  /** Seconds of browser CPU, summed over the session's pages. */
+  readonly CPU_TIME: "browser.session.cpu.time";
+  /** Peak JS heap in bytes across the session's pages. */
+  readonly MEMORY_USAGE: "browser.session.memory.usage";
+  /** Bytes on the wire, request and response, headers and bodies. */
+  readonly NETWORK_IO: "browser.session.network.io";
+  readonly PAGES: "browser.session.pages";
+  readonly CONSOLE_ERRORS: "browser.session.console.errors";
+  readonly CONSOLE_LEVEL: "browser.console.level";
+  readonly CONSOLE_MESSAGE: "browser.console.message";
+};
+interface BrowserSessionOptions {
+  /** Your own session identifier. Defaults to the session span's id. */
+  sessionId?: string;
+  /** Playwright console levels kept as span events. Default: error, warning. */
+  consoleLevels?: readonly string[];
+  /** Extra session attributes, e.g. a workflow or customer id. */
+  attributes?: Record<string, string | number | boolean>;
+}
+/**
+ * Runs `run` inside a `browser.session` span and records what the session cost.
+ * The span is active for the callback, so any instrumented work started inside
+ * it - including an agent whose RPC propagates trace context - joins the trace.
+ */
+declare function withBrowserSession<T>(browserContext: BrowserContext, run: (session: {
+  sessionId: string;
+}) => Promise<T>, options?: BrowserSessionOptions): Promise<T>;
+//#endregion
+export { BROWSER_SESSION_ATTRIBUTES, BrowserSessionOptions, withBrowserSession };

package/dist/session.d.ts

@@ -0,0 +1,37 @@
+import { BrowserContext } from "@playwright/test";
+//#region src/session.d.ts
+/**
+ * Session totals. `session.id` is canonical; the rest extend `browser.*`,
+ * which OpenTelemetry defines for the browser but not for the driver.
+ */
+declare const BROWSER_SESSION_ATTRIBUTES: {
+  readonly SESSION_ID: "session.id";
+  /** Seconds of browser CPU, summed over the session's pages. */
+  readonly CPU_TIME: "browser.session.cpu.time";
+  /** Peak JS heap in bytes across the session's pages. */
+  readonly MEMORY_USAGE: "browser.session.memory.usage";
+  /** Bytes on the wire, request and response, headers and bodies. */
+  readonly NETWORK_IO: "browser.session.network.io";
+  readonly PAGES: "browser.session.pages";
+  readonly CONSOLE_ERRORS: "browser.session.console.errors";
+  readonly CONSOLE_LEVEL: "browser.console.level";
+  readonly CONSOLE_MESSAGE: "browser.console.message";
+};
+interface BrowserSessionOptions {
+  /** Your own session identifier. Defaults to the session span's id. */
+  sessionId?: string;
+  /** Playwright console levels kept as span events. Default: error, warning. */
+  consoleLevels?: readonly string[];
+  /** Extra session attributes, e.g. a workflow or customer id. */
+  attributes?: Record<string, string | number | boolean>;
+}
+/**
+ * Runs `run` inside a `browser.session` span and records what the session cost.
+ * The span is active for the callback, so any instrumented work started inside
+ * it - including an agent whose RPC propagates trace context - joins the trace.
+ */
+declare function withBrowserSession<T>(browserContext: BrowserContext, run: (session: {
+  sessionId: string;
+}) => Promise<T>, options?: BrowserSessionOptions): Promise<T>;
+//#endregion
+export { BROWSER_SESSION_ATTRIBUTES, BrowserSessionOptions, withBrowserSession };

package/dist/session.js

@@ -0,0 +1,118 @@
+import { SpanStatusCode, context, getTracer, otelTrace } from "autotel";
+//#region src/session.ts
+const TRACER_NAME = "autotel-playwright";
+const TRACER_VERSION = "0.1.0";
+/** Console levels recorded as span events when the caller names none. */
+const DEFAULT_CONSOLE_LEVELS = ["error", "warning"];
+/**
+* Session totals. `session.id` is canonical; the rest extend `browser.*`,
+* which OpenTelemetry defines for the browser but not for the driver.
+*/
+const BROWSER_SESSION_ATTRIBUTES = {
+	SESSION_ID: "session.id",
+	/** Seconds of browser CPU, summed over the session's pages. */
+	CPU_TIME: "browser.session.cpu.time",
+	/** Peak JS heap in bytes across the session's pages. */
+	MEMORY_USAGE: "browser.session.memory.usage",
+	/** Bytes on the wire, request and response, headers and bodies. */
+	NETWORK_IO: "browser.session.network.io",
+	PAGES: "browser.session.pages",
+	CONSOLE_ERRORS: "browser.session.console.errors",
+	CONSOLE_LEVEL: "browser.console.level",
+	CONSOLE_MESSAGE: "browser.console.message"
+};
+/**
+* Runs `run` inside a `browser.session` span and records what the session cost.
+* The span is active for the callback, so any instrumented work started inside
+* it - including an agent whose RPC propagates trace context - joins the trace.
+*/
+async function withBrowserSession(browserContext, run, options = {}) {
+	const levels = new Set(options.consoleLevels ?? DEFAULT_CONSOLE_LEVELS);
+	const span = getTracer(TRACER_NAME, TRACER_VERSION).startSpan("browser.session", { attributes: { ...options.attributes } });
+	const sessionId = options.sessionId ?? span.spanContext().spanId;
+	span.setAttribute(BROWSER_SESSION_ATTRIBUTES.SESSION_ID, sessionId);
+	const totals = {
+		consoleErrors: 0,
+		cpuTime: 0,
+		memoryUsage: 0,
+		networkIo: 0,
+		pages: 0
+	};
+	const pending = /* @__PURE__ */ new Set();
+	const cdpSessions = /* @__PURE__ */ new Map();
+	const track = (work) => {
+		pending.add(work);
+		work.finally(() => pending.delete(work));
+	};
+	/**
+	* CPU is cumulative per target, so one read at the end is the whole story;
+	* the heap read is a point in time, which is why closing pages are sampled
+	* too rather than only the ones still open when the session ends.
+	*/
+	const sample = async (page) => {
+		const session = cdpSessions.get(page);
+		cdpSessions.delete(page);
+		try {
+			const cdp = await session;
+			if (!cdp) return;
+			const { metrics } = await cdp.send("Performance.getMetrics");
+			const read = (name) => metrics.find((metric) => metric.name === name)?.value ?? 0;
+			totals.cpuTime += read("TaskDuration");
+			totals.memoryUsage = Math.max(totals.memoryUsage, read("JSHeapUsedSize"));
+		} catch {}
+	};
+	const addBytes = async (request) => {
+		try {
+			const sizes = await request.sizes();
+			totals.networkIo += sizes.requestBodySize + sizes.requestHeadersSize + sizes.responseBodySize + sizes.responseHeadersSize;
+		} catch {}
+	};
+	const attach = (page) => {
+		totals.pages += 1;
+		cdpSessions.set(page, browserContext.newCDPSession(page).then(async (cdp) => {
+			await cdp.send("Performance.enable");
+			return cdp;
+		}).catch(() => void 0));
+		page.on("console", (message) => {
+			const level = message.type();
+			if (level === "error") totals.consoleErrors += 1;
+			if (!levels.has(level)) return;
+			span.addEvent("browser.console", {
+				[BROWSER_SESSION_ATTRIBUTES.CONSOLE_LEVEL]: level,
+				[BROWSER_SESSION_ATTRIBUTES.CONSOLE_MESSAGE]: message.text()
+			});
+		});
+		page.on("pageerror", (error) => {
+			totals.consoleErrors += 1;
+			span.recordException(error);
+		});
+		page.on("requestfinished", (request) => track(addBytes(request)));
+		page.on("close", () => track(sample(page)));
+	};
+	browserContext.on("page", attach);
+	for (const page of browserContext.pages()) attach(page);
+	try {
+		return await context.with(otelTrace.setSpan(context.active(), span), () => run({ sessionId }));
+	} catch (error) {
+		span.recordException(error);
+		span.setStatus({
+			code: SpanStatusCode.ERROR,
+			message: error instanceof Error ? error.message : String(error)
+		});
+		throw error;
+	} finally {
+		browserContext.off("page", attach);
+		for (const page of cdpSessions.keys()) track(sample(page));
+		await Promise.allSettled([...pending]);
+		span.setAttributes({
+			[BROWSER_SESSION_ATTRIBUTES.CONSOLE_ERRORS]: totals.consoleErrors,
+			[BROWSER_SESSION_ATTRIBUTES.CPU_TIME]: totals.cpuTime,
+			[BROWSER_SESSION_ATTRIBUTES.MEMORY_USAGE]: totals.memoryUsage,
+			[BROWSER_SESSION_ATTRIBUTES.NETWORK_IO]: totals.networkIo,
+			[BROWSER_SESSION_ATTRIBUTES.PAGES]: totals.pages
+		});
+		span.end();
+	}
+}
+//#endregion
+export { BROWSER_SESSION_ATTRIBUTES, withBrowserSession };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-playwright",
-  "version": "0.4.61",
+  "version": "0.5.0",
   "description": "Playwright fixture for OpenTelemetry: one span per test and trace context injected into API requests",
   "license": "Apache-2.0",
   "type": "module",
@@ -17,6 +17,11 @@
       "types": "./dist/reporter.d.ts",
       "import": "./dist/reporter.js",
       "require": "./dist/reporter.cjs"
+    },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "import": "./dist/session.js",
+      "require": "./dist/session.cjs"
     }
   },
   "files": [
@@ -24,7 +29,7 @@
     "README.md"
   ],
   "dependencies": {
-    "autotel": "7.4.0"
+    "autotel": "7.6.0"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.62.0"