125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
|
# 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.
|