Detector e problemi canonici

Come i Detector trasformano la telemetria in riscontri e i Canon trasformano i riscontri in problemi gestiti: classi di Detector, gate di qualità dei dati, catalogo dei Canon e analisi della qualità dei Detector.

Architettura dei Detector

Detector

Un Detector è un algoritmo che analizza un insieme di dati definito e produce un riscontro (finding) formalizzato.

Il Detector non gestisce l’esecuzione e non genera testo arbitrario. Il suo risultato ha un formato strutturato.

yaml

detector_id: archive.tail_gap.v3
detector_version: '3.2.1'
run_id: 'run-20260723-0400'
asset_id: 'station-5690'
observed_at: '2026-07-23T04:00:00Z'

finding:
  canon: no_hourly_archive
  detected: true
  severity: critical
  confidence: 0.98
  value: 73
  unit: 'hours'
  threshold: 24
  baseline: 0

evidence:
  last_valid_hour: '2026-07-20T03:00:00Z'
  expected_end: '2026-07-23T04:00:00Z'
  missing_hours: 73

Catena Detector → Canon → Issue

flowchart TD
  D["Detector"] -->|"classificazione"| C["Canon"]
  C -->|"gestione"| I["Operational Issue"]

Detector — un algoritmo specifico;
Canon — un tipo stabile di problema operativo;
Operational Issue — un’istanza del problema in un contesto specifico.

Più Detector diversi possono confermare lo stesso Canon.

Esempio:

flowchart TD
  D1["archive.tail_gap.v3"] --> CANON["no_hourly_archive"]
  D2["archive.coverage.v2"] --> CANON
  D3["archive.delivery_queue.v1"] --> CANON
  D4["session.freshness.v4"] --> CANON
  CANON --> ISSUE["OHM-2026-001842"]

Classi di Detector

Classe	Scopo
Connectivity	comunicazione, sessioni, disponibilità, segnale
Archive	completezza e consegna degli archivi
Data Quality	validità, lacune, contraddizioni
Metering	portata, volume, relazioni metrologiche
Pressure	intervalli, picchi, letture bloccate
Temperature	intervalli, tendenze, coerenza fisica
Power	batteria, alimentazione, degrado
Registry	registro, duplicati, oggetti ghost
Passport	completezza e correttezza del passaporto
Integrity	indizi di manomissione e violazioni dell’integrità
Security	eventi anomali di accesso e configurazione
Firmware	errori, incompatibilità, regressioni
Topology	dipendenze tra dispositivi, gateway e servizi
Operations	elementi scaduti, responsabile mancante, ricorrenza
Predictive	previsione di guasto o degrado

Schermata di riferimento con il catalogo di tutte le 69 verifiche dei report raggruppate per plugin: Detector, subscore, guard di qualità dei dati, gate e verifiche root-cause — Detector dei report: il catalogo completo delle 69 verifiche raggruppate per plugin — Detector, subscore, DQ-guard, gate, root-cause

Requisiti per ogni Detector

Ogni Detector in produzione dispone di:

un detector_id univoco;
una versione semantica;
uno scopo dichiarato;
un responsabile;
una descrizione dei dati di ingresso;
soglie controllate;
regole di esclusione;
requisiti di campione minimo;
DQ-gate;
una formula di severity;
una formula di confidence;
un Canon corrispondente;
un insieme di Evidence;
test;
un campione di controllo;
una stima dei false positive;
una data di messa in esercizio;
un registro delle modifiche;
una modalità di disattivazione e rollback.

Gate di qualità dei dati (DQ-gate)

Il Detector non deve produrre un livello di confidence elevato se i dati di origine sono incompleti o contraddittori.

Esempi di gate:

Condizione	Effetto sul Detector
Nessun `asset_id` valido	bloccare l’azione automatica
Storico insufficiente	abbassare la confidence
Errore di timestamp	non calcolare la freshness
Unità di misura assente	non confrontare con una soglia fisica
Campione troppo piccolo	non costruire una previsione
Oggetto ghost nel registro	rendere non-actionable gli Issue collegati

Salute dei Detector (Detector Health)

OHM monitora la qualità dei Detector stessi.

Indicatori principali:

numero di attivazioni;
quota di attivazioni confermate;
false positive rate;
quota di annullamenti manuali;
quota di riaperture;
distribuzione della confidence;
drift dei dati di ingresso;
variazione della struttura del campione;
tempo medio fino alla conferma;
versione dell’algoritmo;
numero di Issue attivi per versione.

Problemi canonici

Il Canon è una classificazione di business stabile del problema, indipendente dalla specifica implementazione del Detector.

Perché servono i Canon

Senza i Canon un sistema analitico degenera rapidamente in un insieme di messaggi incoerenti:

archive_missing
no_archive
archive_gap
hourly_data_absent
delivery_error

Il Canon unifica tutti questi segnali equivalenti sotto un unico identificatore: canon: no_hourly_archive.

Questo garantisce:

un workflow unico;
un SLA unico;
un’analisi chiara;
KPI stabili;
una Knowledge Base comune;
comparabilità tra le versioni;
traduzione dell’interfaccia senza modifiche alla logica;
integrazione con sistemi esterni.

Struttura di un Canon

yaml

canon_id: no_hourly_archive
name: 'Hourly archive is missing'
domain: archive
default_owner_zone: backend_integration
default_priority: P1
actionable: true
verification_mode: data
sla_policy: archive_p1
suppression_group: communication_archive
knowledge_tags:
  - archive
  - delivery
  - communication

Insieme base dei Canon

Canon	Significato	Zona principale
`no_sessions_in_period`	nessuna sessione nel periodo analizzato	integrazione / comunicazione
`stale_communication`	il dispositivo non comunica da molto tempo	campo / comunicazione
`no_hourly_archive`	archivio orario assente	backend / integration
`archive_delivery_failure`	archivio generato ma non consegnato	backend / integration
`archive_incomplete`	archivio incompleto	servizio di misura
`abnormal_session_length`	durata anomala delle sessioni	comunicazione / integrazione
`battery_low`	risorsa della batteria criticamente bassa	servizio
`battery_unknown`	stato della batteria sconosciuto	servizio / integrazione
`passport_incomplete`	dati di passaporto incompleti	metrologia
`registry_ghost`	l’oggetto esiste logicamente ma non è confermato fisicamente	registro
`registry_duplicate`	conflitto o duplicato di identificatori	registro
`pressure_out_of_range`	pressione fuori dall’intervallo ammesso	esercizio
`pressure_sensor_stuck`	il sensore di pressione non varia con la dinamica attesa	metrologia / servizio
`temperature_out_of_range`	temperatura fuori dall’intervallo ammesso	esercizio
`data_quality_degraded`	la qualità dei dati non consente un’analisi affidabile	integration
`firmware_regression`	i problemi sono legati a una versione del firmware	firmware / backend
`tampering_suspected`	rilevati segni di possibile manomissione	sicurezza / metrologia
`leak_suspected`	rilevati segni indiretti di una possibile perdita	esercizio
`topology_dependency_failure`	i sintomi sono causati dal guasto di un componente condiviso da cui dipendono	backend / infrastructure

Schermata di riferimento con l'elenco di tutti i 19 Canon dei Detector: codici, descrizioni, zone di responsabilità, politiche SLA, flag actionable e collegamenti alla Knowledge Base — Riferimento dei Canon: tutti i 19 Canon dei Detector con codici, descrizioni, zone, SLA, flag e collegamenti alla Knowledge Base

Versionamento dei Canon

La modifica del testo o della traduzione non richiede la modifica dell’identificatore.

Una nuova versione del Canon è necessaria quando cambia:

il significato di business;
la regola di assegnazione;
il criterio di actionability;
il metodo di verifica;
il principio SLA;
la logica di unione con altri problemi.

Analisi della qualità dei Detector

L’Operational Health Matrix valuta non solo le apparecchiature, ma anche la qualità dei propri algoritmi analitici.

Per ogni Detector il sistema calcola:

Accuracy;
Precision;
Recall;
False Positive Rate;
False Negative Rate;
confidence media;
Drift;
Stability;
tempo medio di verifica;
quota di raccomandazioni accettate.

Questo approccio consente di migliorare con continuità il modello analitico della Piattaforma IIoT senza compromettere la riproducibilità dei risultati.

Lo stesso portafoglio di Detector evolve secondo una roadmap a fasi: i nuovi Detector vengono introdotti a ondate e ogni ondata si apre con la disponibilità delle relative API della piattaforma.

Schermata di riferimento con la roadmap a fasi dei Detector: circa 113 Detector pianificati e raggruppati in ondate, ciascuna con l'indicazione dello stato di disponibilità delle API — Roadmap dei Detector: ~113 Detector pianificati per ondate con lo stato di disponibilità delle API

Argomenti correlati

Questa pagina è stata utile?