canary-instrument

Canary Instrument

Correlate every outbound HTTP request in a Playwright run to the test that made it, using OTel span parent/child relationships. Zero required external dependencies to produce output — default file-based span export, no OTel collector needed.

Setup (two manual steps, once per suite)

This skill ships fixture files you wire into your own suite — it does not vendor OTel as a dependency of the canary package itself. Install these first:

npm install --save-dev \
  @opentelemetry/sdk-node @opentelemetry/api \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http

1. Bootstrap the OTel SDK before Playwright starts — add NODE_OPTIONS to your test command (or playwright.config.ts's webServer/CI step):

NODE_OPTIONS="--import ./node_modules/canary/agents/skills/claude-code/canary-instrument/scripts/otel_bootstrap/instrument.mjs" \
  npx playwright test

Copy otel_bootstrap/instrument.mjs into your repo (e.g. otel/instrument.mjs) if you'd rather not reference the path inside node_modules.

2. Merge the root-span fixture into your fixtures.ts:

import { test as base } from '@playwright/test';
import { withTestSpan } from './otel_bootstrap/playwright-fixture';

export const test = withTestSpan(base);

Every test using this test export now opens a root span carrying test.id/test.title/test.file, and every HTTP call the test makes nests under it automatically — no manual span code in individual tests.

Invocation

canary skills run canary-instrument -- \
  --spans test-results/trace --output test-results \
  [--suite-type e2e_ui]

# Usage and options (exits 0; --spans/--output are not required for --help):
canary skills run canary-instrument -- --help

An unknown flag, a missing required flag, and a value-flag left without its value are all usage errors (exit 2). --help short-circuits ahead of the required-argument check, so it never complains about --spans/--output.