# Telemetry And Report Guide (V2)

This guide describes the telemetry v2 API for realtime sessions and the debug audit report generated at the end of a session.

## Runtime Telemetry API

Use these entry points during a live session:

- `transcriber.getTelemetrySnapshot()`
- `transcriber.getTelemetryRows()`
- `transcriber.clearTelemetryRows()`
- `transcriber.resetTelemetry()`
- `transcriber.on("telemetry", listener)`
- `transcriber.on("telemetry_row", listener)`

Example:

```typescript
const transcriber = new SofyaTranscriber(connection);

transcriber.on("telemetry", (snapshot) => {
  console.log(snapshot.status.connectionState);
  console.log(snapshot.counters["tx.final.received"] ?? 0);
  console.log(snapshot.derived.delivery_rate);
});

transcriber.on("telemetry_row", (row) => {
  // Row format is export-ready for CSV/Sheets/BI.
  console.log(row.metric, row.value, row.tags);
});
```

Telemetry is browser-observed and session-oriented. It is intended for UX, diagnostics, and operational indicators, not server-side speech quality truth.

## Metric Names

Telemetry v2 uses flat metric names with four value classes:

- counters
- gauges
- histograms
- events

Main namespaces:

- `ws.*` for transport and websocket metrics
- `audio.*` for capture/send continuity
- `recovery.*` for reconnect and backlog/loss
- `tx.*` for transcript behavior and latency
- `browser.*` and `network.*` for browser/network hints

## Snapshot Shape

`getTelemetrySnapshot()` returns:

- `schemaVersion: 2`
- `window` (session timing)
- `status` (connection/recovery/buffer runtime state)
- `counters`, `gauges`, `histograms`
- `derived` ratios such as delivery and reconnect-success rates

## Row Export

`getTelemetryRows()` returns a bounded in-memory ring buffer (default: `2000` rows).

Each row includes:

- `ts`
- `sessionId`
- `metric`
- `value`
- `type`
- optional `tags`

## Audit-First Vendor Connector

The SDK also supports an optional vendor connector path based on exported audit JSON.

Configuration entry point:

- `connection.config.telemetry`

Current provider:

- `dynatrace` (via global runtime object, default key `dtrum`)

Dispatch behavior:

- source of truth is `getDebugAudit()` output
- auto-dispatch on terminal flows: `stop`, `error`, and terminal `disconnected`
- single active provider per transcriber instance
- no raw transcript text in normalized vendor payload
- missing vendor runtime is non-fatal and emitted as `telemetry_integration_warning`

Example:

```typescript
const transcriber = new SofyaTranscriber({
  provider: "sofya_as_service",
  endpoint: "wss://your-endpoint",
  config: {
    language: "en-US",
    telemetry: {
      enabled: true,
      provider: "dynatrace",
      dynatrace: {
        globalKey: "dtrum",
        actionName: "sofya transcription audit",
      },
    },
  },
});
```

## OpenTelemetry Bridge

Use `attachOpenTelemetryBridge(...)` from `src/services/transcription/metrics/openTelemetryBridge` to mirror telemetry rows to OTel instruments.

Notes:

- Bridge is opt-in.
- SDK/exporter configuration remains app-side.
- The library depends only on OTel API contracts for bridge wiring.

## End-of-Session Debug Report

`getDebugAudit()` and `downloadDebugAudit()` still produce a session report artifact.

Current report schema:

- `report.schemaVersion = 2`

The report remains dashboard-oriented and intentionally avoids exposing unbounded raw telemetry buffers.