# Shade V3.4 — Observability v2 (OpenTelemetry)

**Status:** Implementert (2026-05-02) — `@shade/observability` 0.1.0,
hekt inn i sdk/transfer/server/files/core. Off by default; flip
`SHADE_OTEL_ENABLED=1` for å aktivere.
**Effort:** M (2–4 uker)
**Forrige:** V3.1
**Adresserer:** V2.3 §4

---

## Mål

Gi produksjonsteam **distribuerte spor** rundt `TransferEngine`,
prekey-routes og `@shade/files` — uten å lekke plaintext-adresser, payloads
eller eksakte chunk-størrelser. Bygger videre på Prometheus-metrics som
allerede finnes.

---

## Scope

### Inn

- Opt-in OpenTelemetry-instrumentasjon via `@opentelemetry/api`.
- Spans rundt:
  - `TransferEngine.upload` / `.download` (med lane-tags, retry-counts).
  - `ShadeSessionManager.encrypt` / `.decrypt` (per-peer mutex-akkvisisjon,
    ratchet-step).
  - `createPrekeyRoutes` (per route, status-koder).
  - `@shade/files` op-handlers (har allerede `onMetric` — utvides til OTel).
- PII-policy-doc: hva som **aldri** logges, hva binnes, hva pseudonymiseres.
- Sample-policy default off; on med `SHADE_OTEL_ENABLED=1`.

### Ut

- Trace-eksport til SaaS-leverandører (det er deploy-konfig, ikke vår kode).
- Logg-aggregering — `@shade/server` har allerede strukturert JSON.

---

## Design

### Span-attributter

| Attribute | Verdi |
|-----------|-------|
| `shade.peer.hash` | `sha256(address).slice(0, 8)` — stabil pseudonym |
| `shade.bytes.bin` | binnet — `"≤4KB"`, `"4–64KB"`, `"64KB–1MB"`, `"≥1MB"` |
| `shade.lane.count` | 1 / 4 / 16 |
| `shade.retry.count` | int |
| `shade.error.code` | `SHADE_*`-kode |

**Aldri:** `shade.peer.address`, `shade.payload`, `shade.bytes.exact`.

### API

```ts
import { withTracer } from '@shade/observability';

const shade = await createShade({
  ...,
  observability: withTracer(myTracer, { sample: 0.1 }),
});
```

`withTracer()` er no-op hvis `tracer` er `undefined` eller
`SHADE_OTEL_ENABLED` ikke er satt.

---

## Leveranser

### Pakker

- Ny submodul `@shade/observability` (peer-dep `@opentelemetry/api`).
- Hooks i `@shade/sdk`, `@shade/transfer`, `@shade/server`, `@shade/files`.

### Tester

- Span emitteres med riktige attributter (mock tracer).
- Sample-rate respekteres.
- Off-by-default verifisert.
- Regex-grep mot recorder fanger plaintext-PII.

### Dokumentasjon

- `docs/observability.md` — setup + PII-policy.
- `docs/DEPLOYMENT.md` — environment-variabler.

---

## Akseptansekriterier

- [x] Default deploy uten OTel: ingen performance-regresjon (`withTracer`
      returnerer delt `NOOP_HOOK` når `SHADE_OTEL_ENABLED` ikke er satt).
- [x] Med OTel på: spans for upload/download (`shade.transfer.upload`,
      `shade.transfer.download`), prekey-routes (`shade.prekey.request`),
      session encrypt/decrypt (`shade.session.{encrypt,decrypt}`), og
      `@shade/files` ops (`shade.files.op`).
- [x] Automatisert grep-test fanger plaintext-PII i spans
      (`packages/shade-observability/tests/integration-pii.test.ts` +
      `packages/shade-transfer/tests/observability.test.ts`,
      `safeAttribute()` blokkerer fra-utvikler-introduksert PII).

---

## Avhengigheter

- V3.1 — basis-docs.

---

## Risiko

- **Performance-overhead.** Mitiger ved aggressiv default-off + sampling.
- **PII-lekkasje** hvis utviklere legger til egne attributter. Mitiger ved
  å publisere "safe attribute"-helpers og PII-linter.

---

## Migrasjon

Ingen — opt-in.