git.stella-ops.org/docs/dev/kisa_connector_notes.md

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.