This package is an OpenTelemetry wrapper used throughout the Cypress monorepo to instrument the app for performance insights and regression detection. It provides singleton telemetry instances for the server (Node.js), child process (IPC-based), and browser (WebSocket-based) contexts.

**Key Commands**

```bash
# Build all outputs (ESM, CJS, browser rollup bundle)
yarn workspace @packages/telemetry build

# Run a specific test file
yarn workspace @packages/telemetry test -- <path-to-spec>

# Run tests matching a glob pattern
yarn workspace @packages/telemetry test -- "<glob-pattern>"

# Type-check
yarn workspace @packages/telemetry check-ts
```

**Architecture**

- `src/node.ts` — Node.js telemetry singleton entry point
- `src/client.ts` — Browser telemetry singleton entry point
- `src/telemetry/index.ts` — Core span management, initialization, and context propagation
- `src/span-exporters/` — Exporters for different transport mechanisms:
  - `cloud-span-exporter.ts` — Sends encrypted spans via HTTP to Cypress Cloud
  - `ipc-span-exporter.ts` — Sends spans via IPC from child process to server
  - `websocket-span-exporter.ts` — Sends spans via WebSocket from browser to server
  - `console-trace-link-exporter.ts` — Debug exporter that logs a trace link
- `src/processors/on-start-span-processor.ts` — Hooks span start lifecycle
- `src/detectors/` — CI environment detectors (CircleCI, GitHub Actions) for resource attribution

**Gotchas / Notes**

- Telemetry is **disabled by default**. Enable with `CYPRESS_INTERNAL_ENABLE_TELEMETRY=true`.
- Verbose (high-volume) telemetry (e.g., from `@packages/proxy`) requires `CYPRESS_INTERNAL_ENABLE_TELEMETRY_VERBOSE=true` in addition.
- Data is forwarded to Honeycomb only for the internal Cypress Cloud project; all other projects' data is discarded.
- To develop locally with your own Honeycomb instance, override the exporter URL and supply an `x-honeycomb-team` header.
- All processes must call `telemetry.shutdown()` before exit or page refresh to ensure in-flight spans are flushed.
- Duplicate span names are not deduplicated; `getSpan()` will return only the first match.
- The browser rollup bundle ships with the binary; the ESM node build is currently unused in production.

**Integration Points**

- Initialized by `@packages/server` for the main process and coordinated across the child process and browser via IPC and WebSocket transports.
- `@packages/proxy` instruments request/response spans (gated behind the verbose flag).

**Auto-Generated Files**

- `cjs/`, `esm/`, `browser/` — Generated by `tsc` / rollup; do not edit by hand.
