Skip to content

Latest commit

 

History

History

trace-api

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 

README.md

@playwright-opentelemetry/trace-api

npm version license

H3-based API library for storing and serving Playwright OpenTelemetry traces in S3-compatible object storage.

Installation

npm install @playwright-opentelemetry/trace-api

Introduction

The Trace API is a customizable library that can be deployed to Cloudflare Workers, Deno, Bun, Node.js, or any platform supporting web-standard Request/Response handlers. It provides endpoints for writing OTLP trace data, registering expected Playwright trace IDs, and Playwright screenshots, then serves them in a format compatible with the trace viewer. Test metadata is stored on the root playwright.test span.

Reporter uploads follow Playwright trace retention by default. If Playwright does not produce or retain a trace for a test, no remote trace data is uploaded for that test and viewer read endpoints may return 404. Configure use.playwrightOpentelemetry.trace to override that decision for OpenTelemetry output independently of Playwright's own use.trace setting.

Usage

Basic Usage

import { createTraceApi } from "@playwright-opentelemetry/trace-api";

const api = createTraceApi({
	storageConfig: {
		bucket: "my-traces",
		endpoint: "https://xxx.r2.cloudflarestorage.com",
		accessKeyId: env.R2_ACCESS_KEY_ID,
		secretAccessKey: env.R2_SECRET_ACCESS_KEY,
		region: "auto",
	},
});

export default {
	fetch: api.fetch,
};

Low-Level Building Blocks with Authentication

For maximum flexibility, compose your own API using individual handlers:

import { H3, getHeader, getQuery, createError } from "h3";
import {
	createS3Storage,
	createOtlpHandler,
	createPlaywrightHandler,
	createViewerHandler,
	OTLP_TRACES_WRITE_PATH,
	PLAYWRIGHT_REPORTER_WRITE_PATH,
	TRACE_VIEWER_READ_PATH,
} from "@playwright-opentelemetry/trace-api";

const storage = createS3Storage({
	bucket: "my-traces",
	endpoint: env.R2_ENDPOINT,
	accessKeyId: env.R2_ACCESS_KEY_ID,
	secretAccessKey: env.R2_SECRET_ACCESS_KEY,
});

const app = new H3();

// Authentication middleware for write endpoints
const authMiddleware = async (event) => {
	const token = getHeader(event, "authorization")?.replace("Bearer ", "");
	if (!token || !(await validateToken(token))) {
		throw createError({ statusCode: 401, message: "Unauthorized" });
	}
};

// Authentication middleware for read endpoints. The trace viewer can't set
// headers on these requests, so it passes its token in the query string.
const readAuthMiddleware = async (event) => {
	const { traceToken } = getQuery(event);
	if (typeof traceToken !== "string" || !(await validateToken(traceToken))) {
		throw createError({ statusCode: 401, message: "Unauthorized" });
	}
};

// Apply auth to write and read endpoints
app.use(OTLP_TRACES_WRITE_PATH, authMiddleware);
app.use(PLAYWRIGHT_REPORTER_WRITE_PATH, authMiddleware);
app.use(TRACE_VIEWER_READ_PATH, readAuthMiddleware);

// Add handlers
// /v1/traces/
app.post(OTLP_TRACES_WRITE_PATH, createOtlpHandler({ storage }));
// /playwright-otel-reporter/v1/**
app.put(PLAYWRIGHT_REPORTER_WRITE_PATH, createPlaywrightHandler({ storage }));
// /playwright-otel-trace-viewer/v1/**
app.get(TRACE_VIEWER_READ_PATH, createViewerHandler({ storage }));

export default {
	fetch: app.fetch,
};

Other Runtimes

Deno:

import { createTraceApi } from '@playwright-opentelemetry/trace-api';

const api = createTraceApi({ storageConfig: { ... } });

Deno.serve({ port: 3000 }, api.fetch);

Bun:

import { createTraceApi } from '@playwright-opentelemetry/trace-api';

const api = createTraceApi({ storageConfig: { ... } });

export default {
  port: 3000,
  fetch: api.fetch,
};

Node.js:

import { serve } from 'h3/node';
import { createTraceApi } from '@playwright-opentelemetry/trace-api';

const api = createTraceApi({ storageConfig: { ... } });

serve(api, { port: 3000 });

API Reference

Configuration

interface TraceApiConfig {
	storage?: TraceStorage;
	storageConfig?: {
		bucket: string;
		endpoint: string;
		accessKeyId: string;
		secretAccessKey: string;
		region?: string; // Default: 'auto'
	};
	resolvePath?: (event: H3Event, path: string) => Promise<string> | string;
	corsOrigin?: string | false;
}

Provide either storage for a custom TraceStorage implementation or storageConfig to create the built-in S3-compatible storage.

corsOrigin defaults to false. To let a trace viewer in a sandboxed iframe read traces, set it to "*": the frame's origin is null, so allowing only the viewer's own origin won't match. Only the read endpoints need it, so you can pass it to createViewerHandler alone:

app.get(
	TRACE_VIEWER_READ_PATH,
	createViewerHandler({ storage, corsOrigin: "*" }),
);

With "*", any website can read whatever these endpoints return, and the Trace API doesn't authenticate them for you. The viewer sends traceToken as a query parameter, but nothing here checks it, so validate it yourself as in the example above. A rejection from that middleware has no CORS headers, so a sandboxed viewer can't read it and reports a failed fetch. To show the viewer's page for a refused link there, reply with Access-Control-Allow-Origin and a code.

Endpoints

Write Endpoints:

POST /v1/traces
Content-Type: application/json
Body: Standard OTLP JSON payload

Partitions OTLP spans by trace ID and writes OTLP-shaped fragments to traces/{traceId}/traces/{requestId}.json. The fragment filename is a unique request ID, not a service name or span ID.

OTLP requests from the Playwright reporter include X-Playwright-Otel-Source: reporter and are stored directly. Other OTLP requests are only stored when traces/{traceId}/.expected already exists. Unknown trace IDs are silently dropped with HTTP 200, so exporters do not retry unrelated telemetry.

PUT /playwright-otel-reporter/v1/expected-trace
X-Trace-Id: {traceId}

Writes a zero-byte expected-trace marker to traces/{traceId}/.expected. The Playwright fixture sends this as the test starts, without waiting for it, when trace header propagation is enabled and the configured trace mode could retain the current attempt. This allows app-under-test telemetry that received the propagated traceparent header to be admitted.

PUT /playwright-otel-reporter/v1/screenshots.zip
X-Trace-Id: {traceId}
Body: ZIP containing manifest.json and screenshots/*

Writes the screenshot bundle to traces/{traceId}/screenshots.zip.

Read Endpoints:

GET /playwright-otel-trace-viewer/v1/{traceId}/traces
GET /playwright-otel-trace-viewer/v1/{traceId}/screenshots.zip

Serves merged OTLP trace data and the stored screenshot ZIP expected by the trace viewer. The trace endpoint returns 404 when no trace fragments exist. A missing screenshot ZIP returns 404; the viewer treats that as no screenshots.

Storage Setup

Configure your S3-compatible bucket with a lifecycle rule to expire traces after the desired retention period.

AWS S3

aws s3api put-bucket-lifecycle-configuration \
  --bucket my-traces \
  --lifecycle-configuration '{
    "Rules": [{
      "ID": "ExpireTraces",
      "Status": "Enabled",
      "Filter": { "Prefix": "traces/" },
      "Expiration": { "Days": 30 }
    }]
  }'

Cloudflare R2

wrangler r2 bucket lifecycle set my-traces --rules '[{
  "id": "expire-traces",
  "enabled": true,
  "conditions": { "prefix": "traces/" },
  "deleteObjectsTransition": { "daysAfterUpload": 30 }
}]'

Storage Structure

s3://bucket/
└── traces/
	└── {traceId}/
		├── .expected
		├── traces/
		│   └── {requestId}.json
		└── screenshots.zip