# Upgrading To Telemetry V2 (`0.3.0-beta.x`)

This release introduces a deliberate breaking change in the client-observed metrics surface.

For a full interface migration reference with field-by-field mappings, see [INTERFACE_MIGRATION_V1_TO_V2.md](/Users/gabriel/Projects/lib.sofya.transcription/docs/INTERFACE_MIGRATION_V1_TO_V2.md).

## Breaking API Changes

Removed:

- `getMetrics()`
- `getTranscriptUiMetrics()`
- `getSessionMetrics()`
- `getConnectionMetrics()`
- `getRecoveryMetrics()`
- `getBufferingMetrics()`
- `getBrowserNetworkMetrics()`
- `getAudioCaptureMetrics()`
- `metrics` event

Added:

- `getTelemetrySnapshot()`
- `getTelemetryRows()`
- `clearTelemetryRows()`
- `resetTelemetry()`
- `telemetry` event
- `telemetry_row` event

## Telemetry Snapshot Model

The snapshot now uses:

- `schemaVersion: 2`
- `window`
- `status`
- flat `counters`, `gauges`, `histograms`
- `derived` metrics

## Row Buffer

Telemetry rows are retained in a fixed in-memory ring buffer (`2000` rows by default).

Use rows for export pipelines (CSV/Sheets/BI) and snapshot for dashboard state.

## OpenTelemetry Bridge

A new explicit bridge is available in the metrics module:

- `attachOpenTelemetryBridge(...)`

The bridge is opt-in. OTel SDK/exporter configuration remains app-side.

## Debug Report

Debug report schema moved to `2`.

- `report.schemaVersion = 2`

The report remains presentation-focused and keeps raw runtime telemetry bounded.

## Migration Example

```typescript
transcriber.on("telemetry", (snapshot) => {
  const finals = snapshot.counters["tx.final.received"] ?? 0;
  console.log("final segments", finals);
});

transcriber.on("telemetry_row", (row) => {
  console.log(row.metric, row.value);
});

const snapshot = transcriber.getTelemetrySnapshot();
const rows = transcriber.getTelemetryRows();
```