up

docs/dev/kisa_connector_notes.md

@@ -0,0 +1,45 @@
+# KISA Connector Observability & Localisation
+
+The KISA/KNVD connector now ships with structured telemetry, richer logging, and a localisation brief so Docs/QA can extend operator material without reverse-engineering the source.
+
+## Telemetry counters
+
+All metrics are emitted from `KisaDiagnostics` (`Meter` name `StellaOps.Feedser.Source.Kisa`).
+
+| Metric | Description | Tags |
+| --- | --- | --- |
+| `kisa.feed.attempts` | RSS fetch attempts per scheduled job. | — |
+| `kisa.feed.success` | Successful RSS fetches (increments even when no new items). | — |
+| `kisa.feed.failures` | RSS fetch failures. | `reason` (exception type) |
+| `kisa.feed.items` | Number of items returned by the RSS window. | — |
+| `kisa.detail.attempts` | Advisory detail fetch attempts. | `category` (Hangul category from RSS) |
+| `kisa.detail.success` | Detail payloads fetched and persisted. | `category` |
+| `kisa.detail.unchanged` | HTTP 304 responses reused from cache. | `category` |
+| `kisa.detail.failures` | Detail fetch failures or empty payloads. | `category`, `reason` |
+| `kisa.parse.attempts` | Documents pulled from Mongo for parsing. | `category` |
+| `kisa.parse.success` | Documents parsed into DTOs. | `category` |
+| `kisa.parse.failures` | Download or JSON parse failures. | `category`, `reason` |
+| `kisa.map.success` | Canonical advisories persisted. | `severity` (e.g. `High`, `unknown`) |
+| `kisa.map.failures` | Mapping or DTO hydration failures. | `severity`, `reason` |
+| `kisa.cursor.updates` | Published cursor advanced after ingest. | — |
+
+> `category` tags surface the original Hangul labels (for example `취약점정보`), normalised to NFC. Downstream dashboards should render them as-is; do not transliterate or trim.
+
+## Logging patterns
+
+- `Information` level summary when the RSS feed completes (`ItemCount`), on each persisted detail document (IDX, category, documentId), and when a canonical advisory is written (IDX/severity).
+- `Debug` level logs capture cache hits (304) and cursor movements (`Published` timestamp).
+- `Warning` level emits when a document or DTO is missing so operators can correlate with parse/map counters.
+- `Error` level retains exception context for feed/detail/parse/map failures; state repository backoffs are still applied.
+
+The messages use structured properties (`Idx`, `Category`, `DocumentId`, `Severity`) so Grafana/Loki dashboards can filter without regex.
+
+## Localisation notes for Docs & QA
+
+- Hangul fields (`title`, `summary`, `category`, `reference.label`, product vendor/name) are normalised to NFC before storage. Sample category `취약점정보` roughly translates to “vulnerability information”.
+- Advisory HTML is sanitised via `HtmlContentSanitizer`, stripping script/style while preserving inline anchors for translation pipelines.
+- Metrics carry Hangul `category` tags and logging keeps Hangul strings intact; this ensures air-gapped operators can validate native-language content without relying on MT.
+- Fixtures live under `src/StellaOps.Feedser.Source.Kisa.Tests/Fixtures/`. Regenerate with `UPDATE_KISA_FIXTURES=1 dotnet test src/StellaOps.Feedser.Source.Kisa.Tests/StellaOps.Feedser.Source.Kisa.Tests.csproj`.
+- The regression suite asserts canonical mapping, state cleanup, and telemetry counters (`KisaConnectorTests.Telemetry_RecordsMetrics`) so QA can track instrumentation drift.
+
+For operator docs, link to this brief when documenting Hangul handling or counter dashboards so localisation reviewers have a single reference point.