ArcGIS Utility Network — Part 3: Advanced Network Tracing, Subnetworks & Enterprise Performance
ArcGIS Utility Network — Part 3
Advanced Network Tracing, Subnetworks, Associations, Dirty Areas & Enterprise Performance Engineering
Una Utility Network non è semplicemente un insieme di linee e punti collegati geometricamente. È un modello topologico capace di rappresentare infrastrutture, connessioni logiche, terminali, flussi, gerarchie e regole operative.
Ma è soltanto quando introduciamo il network tracing che questo modello diventa uno strumento di analisi.
Un gestore elettrico deve individuare le utenze a valle di un interruttore. Un acquedotto deve determinare quali valvole isolare per interrompere il flusso verso una tubazione danneggiata. Un operatore di telecomunicazioni deve identificare il percorso logico di un circuito attraverso apparati e connessioni non necessariamente rappresentate da geometrie contigue.
In tutti questi casi, il problema è attraversare correttamente un grafo la cui connettività dipende non solo dalla geometria, ma anche da attributi, associazioni, terminali e stato della rete.
Questa terza puntata affronta il tracing dal punto di vista dell'architettura interna, delle API e della gestione operativa in ArcGIS Enterprise.
1. Network Topology: il grafo realmente utilizzato dal motore
La prima distinzione riguarda i dati geografici e la topologia di rete.
Una feature class contiene geometrie e attributi. La network topology rappresenta invece le informazioni necessarie a interpretare e attraversare la connettività fra gli elementi.
Il motore di tracing utilizza la network topology abilitata e validata. Non esegue semplicemente una sequenza di interrogazioni spaziali sulle feature class alla ricerca di geometrie coincidenti.
Enterprise Geodatabase
|
+-- Domain Network Features
|
+-- Structure Network Features
|
+-- Junction / Edge Objects
|
+-- Network Attributes
|
+-- Associations
|
v
Network Topology
|
v
Trace Engine
|
+-- Connectivity
+-- Traversability
+-- Terminal Paths
+-- Barriers
+-- Functions
+-- Propagators
|
v
Trace Results
Il grafo che attraversiamo non coincide necessariamente con il grafo che potremmo ricostruire osservando esclusivamente le geometrie.
Due conduttori possono condividere la stessa posizione geometrica senza essere elettricamente connessi.
Due oggetti possono invece essere collegati attraverso una connectivity association anche quando non possiedono geometrie coincidenti.
Inoltre, una singola feature può rappresentare più elementi del grafo, soprattutto quando la connettività avviene lungo una linea o coinvolge terminali e oggetti non spaziali.
2. Connectivity vs Traversability
Uno degli errori più frequenti nell'interpretazione del tracing consiste nel confondere la connettività con la possibilità di attraversamento.
Connectivity significa che due elementi sono collegati secondo le regole della Utility Network.
Traversability significa che un determinato attraversamento è consentito dalle condizioni applicate al trace.
Consideriamo una rete elettrica:
Source
|
|
[Switch A: CLOSED]
|
+--------- Load 1
|
[Switch B: OPEN]
|
+--------- Load 2
Il grafo può contenere connessioni fisiche fra tutti gli elementi.
Ma una downstream trace configurata con una condition barrier sullo stato OPEN non attraverserà Switch B.
Questo comportamento non deriva da una modifica della connettività del grafo.
Deriva da una regola di traversability applicata durante l'esecuzione.
2.1 Formalizzazione
In termini astratti, possiamo rappresentare la rete con:
G = (V, E)
V = Junctions / Terminals
E = Edges / Traversable Relations
Per una determinata configurazione di trace, definiamo una funzione di ammissibilità:
T(element, state, configuration)
-> true | false
Il motore attraversa gli elementi consentiti dalla topologia e dalla configurazione.
Questa formalizzazione è concettuale: il runtime Esri utilizza strutture e regole interne più articolate, inclusi elementi di rete, associazioni, attributi di rete e vincoli dei terminali.
La traversability può essere applicata sia ai junction sia agli edge, oppure limitata a una delle due categorie.
Questa scelta diventa importante quando si configurano condition barriers su dispositivi o attributi associati alle linee.
3. Le principali tipologie di Trace
ArcGIS Utility Network mette a disposizione diversi algoritmi di attraversamento.
| Trace | Obiettivo | Scenario |
|---|---|---|
| Connected | Individuare elementi collegati | Analisi della connettività |
| Subnetwork | Esplorare una subnetwork | Individuazione degli asset di un circuito |
| Subnetwork Controllers | Individuare controller sorgente o sink | Identificazione degli alimentatori |
| Upstream | Attraversare la rete verso monte | Ricerca della sorgente |
| Downstream | Attraversare la rete verso valle | Identificazione delle utenze coinvolte |
| Loops | Identificare percorsi ciclici | Analisi di reti magliate |
| Isolation | Individuare dispositivi di isolamento | Gestione guasti e manutenzione |
| Path | Individuare percorsi validi | Routing lungo la rete |
| Circuit | Analizzare circuiti telecom | Reti fisiche e virtuali telecom |
Non tutte le tipologie condividono le stesse dipendenze dalle definizioni delle subnetworks.
In particolare, Connected e Loops non seguono la stessa logica delle tracce direzionali basate su tier e subnetwork controller.
Upstream, Downstream, Subnetwork e Isolation sono influenzate dalla configurazione della domain network e, nei casi applicabili, dalla definizione del tier.
3.1 Novità ArcGIS Enterprise 12.1: Path Trace
Con ArcGIS Enterprise 12.1, Esri ha deprecato la precedente operazione Shortest Path, raccomandando il nuovo tipo Path.
Path amplia le possibilità di individuare percorsi validi e può essere utilizzato anche per ottenere il percorso minimo fra specifiche posizioni di partenza e arresto.
La deprecazione non equivale a una rimozione immediata: Shortest Path continua a funzionare nella release 12.1, ma non rappresenta la scelta consigliata per i nuovi sviluppi.
Per le applicazioni che utilizzano direttamente UtilityNetworkServer REST API, la differenza deve essere gestita in base alle capacità effettivamente esposte dalla versione del server.
4. TraceConfiguration: il vero contratto dell'analisi
La tipologia di trace specifica l'algoritmo generale.
La TraceConfiguration determina invece molti aspetti del suo comportamento.
È quindi sbagliato considerare una downstream trace come un'operazione universalmente definita.
Due downstream trace con configurazioni differenti possono restituire risultati diversi pur partendo dallo stesso elemento.
Fra le principali proprietà troviamo:
- Condition barriers: condizioni di arresto basate su attributi o categorie.
- Function barriers: condizioni di arresto calcolate mediante funzioni.
- Functions: aggregazioni eseguite durante l'attraversamento.
- Propagators: trasferimento e combinazione di valori durante il percorso.
- Output filters: selezione dei risultati da restituire.
- Result types: struttura dei risultati richiesti.
- Traversability scope: applicazione delle condizioni a junction, edge o entrambi.
- Validate consistency: controllo delle dirty areas incontrate.
4.1 Condition Barriers
Supponiamo di avere un network attribute denominato Device Status.
Il valore 1 potrebbe rappresentare OPEN nel modello dati utilizzato.
La condition barrier può essere definita concettualmente come:
Network Attribute: Device Status
Operator: IS_EQUAL_TO
Type: SPECIFIC_VALUE
Value: 1
Quando il motore incontra un elemento che soddisfa questa condizione, l'attraversamento viene arrestato secondo le regole del trace.
Il significato del valore 1 deve essere verificato nella configurazione reale del network attribute: non esiste una codifica numerica universale valida per qualsiasi Utility Network.
4.2 Function Barriers
Le function barriers permettono di arrestare il trace quando una funzione aggregata raggiunge una condizione definita.
Un esempio può essere la somma progressiva della lunghezza attraversata.
Start
|
+-- Edge 100 m
|
+-- Edge 150 m
|
+-- Edge 200 m
|
X Threshold exceeded
Una funzione aggregata può essere utilizzata per controllare l'attraversamento in base a un costo o a una quantità.
Questa logica non deve però essere confusa con una simulazione idraulica o elettrica.
Somme e aggregazioni di network attributes non sostituiscono un solutore fisico capace di calcolare pressioni, portate, tensioni o perdite mediante equazioni di dominio.
4.3 Propagators
I propagators sono particolarmente interessanti nelle reti elettriche.
Permettono di trasportare informazioni lungo il trace e combinarle attraverso operatori specifici.
Per esempio, un attributo bitset può rappresentare le fasi disponibili.
Phase A = 001
Phase B = 010
Phase C = 100
ABC = 111
AB = 011
A = 001
Una propagazione bitwise può determinare quali fasi rimangono compatibili durante l'attraversamento di elementi caratterizzati da configurazioni differenti.
Il comportamento effettivo dipende dall'operatore scelto e dal network attribute configurato.
Questa funzionalità mostra perché il trace di una Utility Network non può essere ridotto a una semplice visita DFS o BFS del grafo geometrico.
5. Subnetworks: la dimensione operativa del grafo
Una subnetwork rappresenta un insieme di elementi connessi e delimitati secondo la configurazione della domain network.
Nelle reti tradizionali, il comportamento dipende dal tier e dai subnetwork controllers.
Un controller può rappresentare, per esempio, una sorgente di alimentazione elettrica o un punto di alimentazione idraulica.
Subnetwork Controller
|
v
Feeder
|
+----+----+
| |
Branch A Branch B
| |
Load A Load B
Il controller non è soltanto un elemento geografico collocato all'inizio della linea.
È una configurazione della rete che contribuisce a determinare il comportamento delle trace e delle subnetworks.
5.1 Partitioned e Hierarchical Tier Definitions
Le due modalità principali di organizzazione dei tier hanno implicazioni diverse.
Partitioned: le subnetworks rappresentano partizioni della rete nel contesto del tier.
Hierarchical: la rete può essere organizzata in una struttura gerarchica con differenti livelli.
La logica di attraversamento ai confini delle subnetworks dipende dalla definizione del tier.
Per esempio, in una rete gerarchica, un trace può essere configurato per attraversare i confini fra livelli tramite il parametro Target Tier, quando supportato dal tipo di analisi.
Non è quindi corretto applicare automaticamente le stesse impostazioni di tracing a una rete partitioned e a una hierarchical.
5.2 Subnetwork Name vs Starting Points
Nelle subnetwork trace è possibile specificare il nome della subnetwork invece di selezionare manualmente un punto di partenza.
Quando viene fornito un subnetworkName, il motore utilizza i controller associati alla subnetwork.
Questo permette di eseguire analisi ripetibili senza dipendere dalla selezione grafica di un elemento in mappa.
È particolarmente utile per servizi automatici di reportistica e controlli notturni.
6. Associations: il collegamento che non si vede sulla mappa
Le associations permettono di rappresentare relazioni fra elementi della Utility Network che non devono necessariamente essere coincidenti geometricamente.
Esistono tre categorie fondamentali.
| Tipo | Semantica | Esempio |
|---|---|---|
| Connectivity | Connessione utilizzabile nella rete | Collegamento fra terminali di dispositivi |
| Containment | Elemento contenuto in un altro | Apparecchiatura all'interno di un cabinet |
| Structural attachment | Relazione di supporto fisico | Cavo sostenuto da un palo |
6.1 Connectivity Associations
Le connectivity associations contribuiscono alla connettività del grafo.
Permettono di modellare connessioni fra network elements senza richiedere necessariamente geometrie coincidenti.
La loro validità dipende dalle connectivity rules e, quando applicabile, dai terminali interessati.
6.2 Containment Associations
Una containment association descrive una relazione gerarchica fra un container e il suo contenuto.
Substation
|
+-- Cabinet
| |
| +-- Breaker
| +-- Terminal
|
+-- Transformer
È importante distinguere il contenimento dalla connettività.
Un dispositivo contenuto in un cabinet non è automaticamente connesso elettricamente agli altri dispositivi presenti nello stesso cabinet.
Il contenimento può influenzare la rappresentazione, il recupero degli elementi e le opzioni di output del trace, ma non deve essere interpretato come una connessione funzionale implicita.
6.3 Structural Attachment Associations
Queste relazioni descrivono il supporto fisico di un elemento.
Per esempio, un palo può sostenere diversi conduttori.
La relazione di supporto non equivale a una connessione elettrica fra il palo e i conduttori.
In una trace è possibile richiedere l'inclusione delle strutture nei risultati, ma questo non modifica la semantica fisica dell'associazione.
7. Dirty Areas: il problema della consistenza topologica
La network topology non viene necessariamente aggiornata immediatamente quando si modifica una feature.
Le dirty areas identificano modifiche che devono ancora essere incorporate e verificate nella topologia.
Possono comparire dopo operazioni quali:
- creazione o eliminazione di elementi;
- modifica di geometrie;
- variazione di attributi rilevanti per la rete;
- creazione o modifica di associations;
- operazioni che producono errori di topologia.
È utile distinguere le dirty areas legate a modifiche da quelle associate a errori.
La validazione della topologia può eliminare le dirty areas di modifica quando gli elementi risultano coerenti.
Le situazioni che violano regole di rete richiedono invece un intervento correttivo.
7.1 Cosa accade se si esegue un trace prima della validazione?
Il trace utilizza la rappresentazione topologica disponibile.
Se questa non riflette le modifiche più recenti, il risultato potrebbe essere incoerente con gli attributi e le geometrie attuali.
La proprietà validateConsistency permette di richiedere un controllo delle dirty areas incontrate.
Quando il controllo è abilitato, il trace restituisce un errore se incontra condizioni di inconsistenza rilevanti.
La semantica della validazione va distinta dalla sua esecuzione: il controllo del trace non aggiorna automaticamente la topologia.
7.2 La sequenza corretta
Edit Features / Associations
|
v
Dirty Areas
|
v
Validate Network Topology
|
+-----+-----+
| |
Errors Clean
| |
v v
Fix Errors Update Subnetwork
|
v
Execute Trace
|
v
Verify Results
Questa è una sequenza operativa di riferimento. I dettagli dipendono dal tipo di rete, dalla configurazione dei tier e dalle politiche di gestione delle subnetworks.
8. Validate Network Topology e Update Subnetwork sono operazioni differenti
È importante non considerare queste due operazioni come intercambiabili.
Validate Network Topology aggiorna la rappresentazione topologica delle modifiche e verifica la conformità alle regole.
Update Subnetwork aggiorna informazioni e stato delle subnetworks, eseguendo i controlli previsti dalla configurazione.
Una subnetwork può essere marcata come dirty dopo la validazione topologica di modifiche che la interessano.
L'operazione Update Subnetwork serve quindi a portare la subnetwork in uno stato aggiornato, purché non siano presenti errori che impediscono il completamento.
Le operazioni possono inoltre aggiornare attributi di rete, informazioni di appartenenza alle subnetworks e dati specifici della SubnetLine e della Subnetworks table.
8.1 Strategia di gestione in Enterprise
In un ambiente con branch versioning può essere utile adottare il seguente workflow:
Named Version
|
v
Feature Editing
|
v
Validate Network Topology
|
v
Quality Control
|
v
Update Subnetwork
|
v
Trace Regression Tests
|
v
Reconcile / Post
Questo è un workflow progettuale. Non sostituisce la procedura Esri per reconcile, post, gestione dei conflitti e aggiornamento delle subnetworks, che dipende anche dalla versione di ArcGIS Enterprise e dalla configurazione della rete.
Per analisi critiche, è utile registrare la versione del geodatabase e il momento logico al quale il trace si riferisce.
9. Laboratorio REST — UtilityNetworkServer/trace
Passiamo all'implementazione.
Il servizio UtilityNetworkServer espone un endpoint dedicato alle operazioni di trace:
POST
https://server.example.com/server/rest/services/
ElectricNetwork/FeatureServer/
UtilityNetworkServer/trace
L'URL è illustrativo. Il percorso effettivo deve essere ricavato dalle risorse REST pubblicate dal servizio Utility Network dell'organizzazione.
Una richiesta può specificare:
- il tipo di trace;
- i punti di partenza e le barriere;
- la versione del geodatabase;
- la configurazione di trace;
- i tipi di risultato;
- il contesto temporale e di sessione, dove applicabile.
9.1 Connected Trace con configurazione esplicita
Il seguente esempio è un payload form-urlencoded rappresentato in forma leggibile.
f=json
gdbVersion=SDE.DEFAULT
traceType=connected
traceLocations=[
{
"traceLocationType": "startingPoint",
"globalId": "{11111111-1111-1111-1111-111111111111}",
"percentAlong": 0.5
}
]
traceConfiguration={
"includeContainers": false,
"includeContent": false,
"includeStructures": false,
"includeBarriers": true,
"validateConsistency": true,
"traversabilityScope": "junctionsAndEdges",
"conditionBarriers": [],
"functionBarriers": []
}
resultTypes=[
{
"type": "elements"
}
]
L'esempio utilizza un GlobalID fittizio e presuppone che l'elemento supporti una posizione lungo la linea.
Per una junction, l'indicazione della posizione lungo l'edge non è necessaria.
In produzione è indispensabile ricavare i GlobalID dagli elementi della rete e usare una trace location coerente con il tipo di elemento.
9.2 Perché utilizzare resultTypes?
Il parametro resultTypes permette di controllare quali informazioni vengono restituite.
Fra le opzioni supportate, in funzione della versione e del tipo di trace, troviamo:
Elements: identificativi degli elementi attraversati.
Aggregated Geometry: geometrie aggregate generate dai risultati.
Connectivity: rappresentazione delle relazioni di connettività, utile per ricostruire un grafo applicativo.
I result types più avanzati dipendono dalla versione del servizio e dalle capacità della rete. Non vanno richiesti indiscriminatamente a installazioni precedenti.
Per un'applicazione che deve soltanto contare gli asset coinvolti, richiedere geometrie dettagliate e attributi non necessari può aumentare il volume dei dati trasferiti e il lavoro di serializzazione.
10. Laboratorio C# — Client REST per Network Trace
Un'applicazione .NET può invocare il servizio utilizzando HttpClient.
È importante separare:
Autenticazione: ottenimento e gestione del token ArcGIS.
Configurazione: tipo di trace, posizioni e condizioni.
Trasporto: richiesta REST e gestione degli errori.
Elaborazione: interpretazione dei risultati e metriche.
10.1 Implementazione
using System.Net.Http.Headers;
using System.Text.Json;
public sealed class UtilityNetworkTraceClient
{
private readonly HttpClient _http;
public UtilityNetworkTraceClient(HttpClient http)
{
_http = http;
}
public async Task<JsonDocument> TraceAsync(
Uri traceEndpoint,
string accessToken,
Guid startGlobalId,
CancellationToken cancellationToken)
{
var locations = new[]
{
new
{
traceLocationType = "startingPoint",
globalId = startGlobalId
.ToString("B")
.ToUpperInvariant()
}
};
var configuration = new
{
includeContainers = false,
includeContent = false,
includeStructures = false,
includeBarriers = true,
validateConsistency = true,
traversabilityScope = "junctionsAndEdges",
conditionBarriers = Array.Empty<object>(),
functionBarriers = Array.Empty<object>()
};
var resultTypes = new[]
{
new { type = "elements" }
};
var parameters = new Dictionary<string, string>
{
["f"] = "json",
["gdbVersion"] = "SDE.DEFAULT",
["traceType"] = "connected",
["traceLocations"] =
JsonSerializer.Serialize(locations),
["traceConfiguration"] =
JsonSerializer.Serialize(configuration),
["resultTypes"] =
JsonSerializer.Serialize(resultTypes)
};
using var request = new HttpRequestMessage(
HttpMethod.Post, traceEndpoint);
request.Headers.Authorization =
new AuthenticationHeaderValue(
"Bearer", accessToken);
request.Content = new FormUrlEncodedContent(
parameters);
using var response = await _http.SendAsync(
request,
HttpCompletionOption.ResponseHeadersRead,
cancellationToken);
response.EnsureSuccessStatusCode();
await using var stream =
await response.Content.ReadAsStreamAsync(
cancellationToken);
var document = await JsonDocument.ParseAsync(
stream,
cancellationToken: cancellationToken);
if (document.RootElement.TryGetProperty(
"error", out var error))
{
var message = error.ToString();
document.Dispose();
throw new InvalidOperationException(
$"ArcGIS trace failed: {message}");
}
return document;
}
}
L'implementazione utilizza una trace location semplificata. Nelle reti con terminali, junction objects, edge objects o segmenti di linea è necessario costruire le posizioni secondo la specifica REST e i dati effettivi degli elementi.
Il client assume inoltre che il token sia già stato acquisito correttamente attraverso il meccanismo di autenticazione dell'organizzazione.
In ambienti Enterprise con autenticazione federata, il token e la sua audience devono essere compatibili con l'endpoint invocato.
10.2 Invocazione
using var http = new HttpClient
{
Timeout = TimeSpan.FromMinutes(2)
};
var client = new UtilityNetworkTraceClient(http);
using var result = await client.TraceAsync(
new Uri(
"https://server.example.com/server/rest/services/" +
"ElectricNetwork/FeatureServer/" +
"UtilityNetworkServer/trace"),
accessToken,
startGlobalId,
CancellationToken.None);
Console.WriteLine(
result.RootElement.ToString());
Il timeout di due minuti è illustrativo e deve essere dimensionato in funzione del servizio, della dimensione della rete e delle condizioni operative.
Per analisi particolarmente lunghe conviene valutare le capacità asincrone effettivamente offerte dal server e non lasciare indefinitamente aperta una richiesta HTTP sincrona.
11. ArcPy — Esecuzione di un trace riproducibile
ArcPy permette di eseguire lo strumento Trace da script Python, utilizzando il tool arcpy.un.Trace.
In un ambiente Enterprise, il layer Utility Network utilizzato dallo strumento deve provenire dal feature service, non semplicemente da una connessione diretta al database.
Il seguente esempio presuppone che il progetto ArcGIS Pro contenga il layer della Utility Network e che sia stata preparata una feature class di starting points conforme allo schema richiesto.
import arcpy
import time
arcpy.env.overwriteOutput = True
utility_network = "Electric Utility Network"
starting_points = (
r"C:\GIS\TraceWorkspace.gdb\StartingPoints"
)
start = time.perf_counter()
result = arcpy.un.Trace(
in_utility_network=utility_network,
trace_type="CONNECTED",
starting_points=starting_points,
validate_consistency="VALIDATE_CONSISTENCY",
result_types="SELECTION"
)
elapsed = time.perf_counter() - start
print(f"Trace completed in {elapsed:.3f} seconds")
print(result.getMessages())
Lo script dimostra l'invocazione dello strumento e la misurazione della durata.
Non crea automaticamente gli starting points: la feature class deve contenere i campi previsti da Esri, in particolare FEATUREGLOBALID, e le eventuali informazioni aggiuntive necessarie alla posizione sulla rete.
La scelta del tipo di risultato influenza anche il modo in cui gli elementi vengono restituiti.
11.1 Un dettaglio importante su ArcPy
Per le trace basate su subnetwork, la configurazione definita nel tier non viene sempre applicata automaticamente quando lo strumento è invocato attraverso Python.
La documentazione Esri richiede di prestare attenzione alla configurazione esplicita delle subnetwork trace.
Per evitare differenze fra risultati ottenuti manualmente e risultati ottenuti dagli script, è opportuno usare configurazioni nominate o riprodurre esplicitamente le impostazioni rilevanti, secondo le capacità della versione utilizzata.
12. ArcGIS Pro SDK: integrazione nel client desktop
In ArcGIS Pro, l'analisi può essere integrata in un add-in C#.
Il workflow tipico comprende:
ArcGIS Pro Add-in
|
v
QueuedTask / GIS Context
|
v
Locate Utility Network
|
v
Configure Trace
|
v
Execute Trace
|
v
Process Results
|
v
Update Selection / Graphics
Lo SDK espone classi per interagire con Utility Network, configurazioni di trace e risultati.
È tuttavia importante distinguere le API dell'SDK dalle API REST: pur rappresentando gli stessi concetti, non condividono necessariamente le stesse firme o gli stessi tipi.
Una strategia particolarmente utile consiste nel separare l'implementazione del trace dall'interfaccia dell'add-in.
12.1 Contratto applicativo
public sealed record TraceRequest(
Guid StartElement,
string TraceKind,
string? NamedConfigurationId);
public sealed record TraceSummary(
int ElementCount,
TimeSpan Duration,
bool Consistent);
public interface INetworkTraceService
{
Task<TraceSummary> ExecuteAsync(
TraceRequest request,
CancellationToken cancellationToken);
}
Questi tipi costituiscono un contratto applicativo personalizzato, non API Esri.
L'interfaccia può essere implementata utilizzando direttamente le classi ArcGIS Pro SDK, oppure tramite un servizio REST quando l'applicazione richiede un'architettura disaccoppiata.
Nel primo caso è necessario rispettare il threading model di ArcGIS Pro e le regole delle operazioni eseguite tramite QueuedTask.
Nel secondo caso il client deve gestire correttamente autenticazione Portal, branch versioning e sessioni.
13. Named Trace Configurations: il tracing come contratto versionato
Un problema frequente nelle applicazioni enterprise è la dispersione della logica di tracing.
Un add-in potrebbe utilizzare determinate condition barriers.
Un servizio web potrebbe utilizzare una configurazione leggermente differente.
Un processo ArcPy potrebbe applicare impostazioni ancora diverse.
Il risultato è che tre applicazioni dichiarano di eseguire una downstream trace, ma restituiscono asset differenti.
Le named trace configurations permettono di centralizzare configurazioni persistenti associate alla Utility Network.
Il servizio REST supporta il parametro traceConfigurationGlobalId, che consente di utilizzare una configurazione nominata.
Quando viene utilizzato, la configurazione nominata prevale sul parametro traceConfiguration fornito nella richiesta.
La configurazione contiene anche il tipo di trace, rendendo non determinante il valore del parametro traceType passato separatamente.
13.1 Strategia consigliata
In un'organizzazione con più applicazioni è utile definire configurazioni dedicate a specifici processi.
Trace Configurations
|
+-- Electric_Upstream_Protection
|
+-- Electric_Downstream_Loads
|
+-- Water_Isolation_Valves
|
+-- Telecom_Circuit_Path
Questi nomi sono esempi progettuali.
Per ogni configurazione dovrebbero essere documentati il GlobalID, la versione logica, il tier, le condizioni di traversability e le aspettative di output.
Una modifica alla configurazione può alterare il risultato di un processo anche senza modifiche al codice dell'applicazione.
È quindi utile trattarla come un cambiamento soggetto a controllo di versione e regression testing.
14. Network Tracing e concorrenza in ArcGIS Enterprise
In produzione, le prestazioni non dipendono soltanto dalla velocità del singolo algoritmo.
Occorre considerare il numero di richieste simultanee, il volume dei risultati, lo stato della topologia e le caratteristiche del servizio.
Una trace che completa in pochi secondi con un solo utente potrebbe avere una latenza molto superiore quando numerosi client eseguono contemporaneamente analisi complesse.
14.1 Dove si consuma il tempo
Client
|
| HTTP / Authentication
v
ArcGIS Server
|
| Request Processing
v
UtilityNetworkServer
|
| Trace Configuration
v
Topology Traversal
|
| Result Construction
v
Geometry / Attribute Serialization
|
| HTTP Response
v
Client Rendering
Il tempo totale può essere suddiviso concettualmente in:
Ttotal =
Tnetwork
+ Tserver
+ Ttrace
+ Tserialization
+ Ttransfer
+ Tclient
Questa è una scomposizione diagnostica, non una formula ufficiale Esri.
Un trace può essere veloce a livello topologico ma richiedere molto tempo per trasferire migliaia di geometrie complesse.
Analogamente, un client può introdurre latenza significativa nella visualizzazione di risultati molto grandi.
14.2 Una regola pratica
Richiedere soltanto le informazioni necessarie.
Se l'applicazione deve calcolare il numero degli elementi coinvolti, non è necessario richiedere sempre geometrie aggregate complete.
Se deve visualizzare una porzione di rete, potrebbe essere utile richiedere il risultato geometrico appropriato invece di recuperare separatamente tutti gli elementi e costruire localmente la geometria.
La scelta va misurata sul caso reale.
15. Benchmarking: misurare le prestazioni in modo corretto
Un benchmark affidabile deve controllare le condizioni del test.
Non è sufficiente eseguire una trace una volta e registrare il tempo.
Le differenze fra una chiamata e l'altra possono dipendere da cache, inizializzazione, concorrenza, latenza di rete e dimensione dei risultati.
Una matrice di test può includere:
| Dimensione | Variabili |
|---|---|
| Tipo di trace | Connected, Upstream, Downstream, Isolation, Path |
| Dimensione | Numero di elementi attraversati |
| Output | Elements, Aggregated Geometry, Connectivity |
| Consistenza | Topologia validata, test separati con dirty areas |
| Concorrenza | 1, 5, 10, 25 client |
| Versioning | Default e named versions |
| Topologia | Reti radiali e reti magliate |
I numeri di concorrenza sono livelli sperimentali, non capacità garantite di ArcGIS Enterprise.
15.1 Misurazioni consigliate
Le metriche principali sono:
- latenza P50, P95 e P99;
- throughput delle richieste;
- numero di elementi restituiti;
- dimensione della risposta HTTP;
- frequenza e tipologia degli errori;
- utilizzo di CPU e memoria dei processi ArcGIS Server;
- tempo di serializzazione e trasferimento;
- durata complessiva dell'elaborazione lato client.
È importante distinguere il tempo di esecuzione della trace dal tempo totale percepito dall'utente.
Per questo motivo, un benchmark enterprise dovrebbe combinare metriche applicative, log ArcGIS Server e misurazioni esterne.
16. Osservabilità e troubleshooting
Il troubleshooting di una trace errata richiede un approccio ordinato.
Un problema può dipendere da una configurazione incompleta, da attributi sbagliati, da una topologia non validata o da una relazione di rete modellata in modo non corretto.
16.1 Diagnosi funzionale
Quando una trace restituisce risultati inattesi, controllare nell'ordine:
- La corretta identificazione degli starting points.
- La disponibilità e validità della network topology.
- La presenza di dirty areas.
- La configurazione effettiva dei condition barriers.
- La definizione del tier e della subnetwork.
- I terminal paths e le terminal configurations.
- Le connectivity associations.
- Le opzioni di inclusione di container, content e structures.
- I result types richiesti.
- La versione del geodatabase sulla quale viene eseguita l'analisi.
16.2 Diagnosi prestazionale
Se invece la trace è corretta ma lenta, occorre distinguere tre problemi differenti.
Trace computation: il motore impiega molto tempo ad attraversare il grafo.
Result generation: la costruzione dell'output è costosa.
Service latency: il servizio risponde lentamente a causa di concorrenza, saturazione o condizioni infrastrutturali.
Per diagnosticarli è utile confrontare trace equivalenti con result types differenti e misurare separatamente l'elaborazione lato server e la durata complessiva HTTP.
17. Versioning: ArcGIS Pro e ArcGIS Enterprise
Un ambiente Utility Network enterprise deve essere valutato considerando contemporaneamente più versioni.
Le principali sono:
- ArcGIS Pro;
- ArcGIS Enterprise;
- geodatabase;
- Utility Network dataset version;
- versione delle API e delle funzionalità di tracing.
Non è sufficiente aggiornare ArcGIS Enterprise per ottenere automaticamente tutte le nuove funzionalità dei dataset Utility Network.
Il valore Utility Network Version rappresenta la versione dello schema della rete.
La compatibilità dipende dalla versione del client e dalla versione del server.
17.1 Alcune compatibilità fondamentali
| Utility Network Version | ArcGIS Pro minimo | ArcGIS Enterprise minimo |
|---|---|---|
| 5 | 2.7 | 10.9 |
| 6 | 3.0 | 11.0 |
| 7 | 3.3 | 11.3 |
Questa tabella riporta soltanto alcune versioni e i rispettivi requisiti minimi.
Non deve essere interpretata come una matrice completa di compatibilità delle funzionalità in ArcGIS Enterprise 12.1.
Le versioni più recenti di ArcGIS Pro ed Enterprise possono generalmente utilizzare reti create con schemi precedenti, ma alcune funzionalità richiedono versioni specifiche dello schema.
Per esempio, l'opzione Use Digitized Direction richiede Utility Network Version 7 o superiore e, in un ambiente Enterprise, ArcGIS Enterprise 11.3 o superiore.
Prima di aggiornare una Utility Network è quindi necessario verificare quali client, servizi e processi automatizzati dipendono dallo schema esistente.
18. Architettura di riferimento per applicazioni enterprise
Una soluzione enterprise potrebbe utilizzare un backend applicativo dedicato all'esecuzione e alla gestione delle trace.
ArcGIS Pro / Web Application
|
v
Application API
|
+------+------+
| |
v v
Authorization Trace Profiles
| |
+------+------+
|
v
Trace Orchestrator
|
v
UtilityNetworkServer
|
v
Network Topology
|
v
Trace Results
|
+------+------+
| |
v v
Result Cache Observability
|
v
Application Response
Questa è un'architettura progettuale, non un componente standard distribuito da Esri.
Il backend può svolgere funzioni utili:
- centralizzare le configurazioni applicative;
- controllare quali utenti possono richiedere determinate analisi;
- gestire timeout e cancellazioni;
- normalizzare gli output;
- registrare metriche prestazionali;
- evitare la duplicazione di richieste identiche;
- gestire il caching quando la consistenza dei dati lo consente.
18.1 Il problema del caching
Memorizzare i risultati delle trace può ridurre la pressione sul server.
Ma una cache non correttamente invalidata può diventare pericolosa.
Una modifica alle associazioni, allo stato di una valvola o alla topologia può alterare radicalmente il risultato.
Una chiave di cache dovrebbe quindi considerare almeno:
Cache Key =
Utility Network Identity
+ Trace Configuration Version
+ Trace Type
+ Starting Locations
+ Barriers
+ Geodatabase Version
+ Logical Data Revision
+ Result Types
+ Authorization Scope
Questa formula è una proposta architetturale.
Il problema più difficile è identificare una revisione logica dei dati capace di rappresentare correttamente tutte le modifiche rilevanti per la trace.
Una semplice chiave basata sul timestamp della richiesta non garantisce la consistenza del risultato.
In assenza di un meccanismo affidabile di invalidazione, è preferibile evitare il caching delle trace utilizzate per decisioni operative critiche.
19. Test di regressione delle trace
Una Utility Network dovrebbe essere trattata come un sistema soggetto a regression testing.
Una modifica alle network rules, ai terminali o alle configurazioni può cambiare i risultati senza introdurre errori visibili nell'interfaccia.
Per questo motivo, ogni rete dovrebbe disporre di un insieme di scenari di riferimento.
Per esempio:
Scenario: Electric Feeder A
Starting Point:
Device GlobalID
Expected:
Controller Count = 1
Downstream Loads = 125
Open Switches Traversed = 0
Unexpected Cross-Tier Paths = 0
Questi numeri sono puramente illustrativi.
Il test deve utilizzare un dataset di riferimento controllato e verificare che il risultato corrisponda alle aspettative definite dagli esperti di dominio.
19.1 Un confronto deterministico
Per evitare problemi dovuti all'ordine degli elementi nei risultati, il confronto può utilizzare identificativi ordinati.
Expected GlobalIDs
|
v
Canonical Sorting
|
v
Expected Hash
|
+-----------------+
|
Actual GlobalIDs |
| |
v |
Canonical Sorting |
| |
v |
Actual Hash |
| |
+--------+--------+
|
v
Comparison
Il confronto dell'hash può essere utile per identificare rapidamente variazioni, ma per la diagnostica è necessario conservare anche gli identificativi originali o una rappresentazione confrontabile dei risultati.
Per i trace con geometrie aggregate, il confronto richiede ulteriori precauzioni: precisione, tolleranze, sistema di riferimento e rappresentazione geometrica possono influenzare il risultato.
20. Un caso reale: isolamento di una condotta idrica
Consideriamo una condotta principale che deve essere isolata per manutenzione.
Un'applicazione basata soltanto su geometrie potrebbe individuare le valvole più vicine alla condotta.
Ma questo non dimostra che quelle valvole siano sufficienti a isolare la sezione interessata.
Il problema è topologico.
Source
|
v
[Valve A]
|
+-------+-------+
| |
Pipe 1 Pipe 2
| |
[Valve B] [Valve C]
| |
+-------+-------+
|
Faulted Pipe
|
[Valve D]
|
Users
Una isolation trace deve considerare i percorsi realmente disponibili verso le sorgenti e i dispositivi in grado di interrompere l'attraversamento.
Se esiste un percorso alternativo che bypassa una valvola, l'isolamento potrebbe richiedere la chiusura di ulteriori dispositivi.
Una corretta analisi deve inoltre distinguere gli asset isolati dalle utenze effettivamente interessate dall'interruzione.
Queste due informazioni non sono necessariamente equivalenti.
20.1 Workflow operativo
Faulted Pipe
|
v
Validate Network State
|
v
Isolation Trace
|
v
Identify Isolation Devices
|
v
Determine Isolated Assets
|
v
Identify Affected Customers
|
v
Operational Review
|
v
Maintenance Plan
La trace fornisce una base analitica, ma non sostituisce il processo di autorizzazione operativa della rete.
La chiusura reale delle valvole deve essere verificata dagli operatori secondo le procedure di sicurezza e di esercizio.
21. Gli errori architetturali più comuni
Nel progettare applicazioni Utility Network enterprise è opportuno evitare alcune semplificazioni.
Errore 1 — Considerare la geometria come unica fonte di connettività
Le connectivity associations e i terminali possono determinare relazioni che non risultano evidenti dalle geometrie.
Errore 2 — Eseguire trace su topologie non validate
Le modifiche non ancora incorporate nella topologia possono compromettere l'accuratezza delle analisi.
Errore 3 — Confondere Validate Network Topology con Update Subnetwork
Le due operazioni hanno responsabilità differenti nel ciclo di aggiornamento della rete.
Errore 4 — Utilizzare configurazioni divergenti fra applicazioni
Le named trace configurations aiutano a mantenere comportamenti coerenti e riproducibili.
Errore 5 — Richiedere output eccessivi
Geometrie, attributi e informazioni di connettività non necessarie possono aumentare il costo delle analisi.
Errore 6 — Confondere tracing e simulazione fisica
La connettività non equivale alla soluzione delle equazioni fisiche che descrivono flussi, pressioni o carichi.
Errore 7 — Ignorare la versione del dataset
La disponibilità di una nuova funzionalità in ArcGIS Pro non garantisce che sia utilizzabile con ogni configurazione Enterprise e ogni Utility Network Version.
22. Conclusioni: la Utility Network come motore topologico enterprise
Il tracing trasforma una Utility Network da modello di rappresentazione delle infrastrutture a sistema di analisi operativa.
Ma la correttezza del risultato dipende da numerosi componenti:
Il modello dati, che descrive gli asset.
Le network rules, che definiscono le connessioni ammesse.
Le associations, che rappresentano relazioni non necessariamente geometriche.
La network topology, che rende possibile l'attraversamento del grafo.
Le trace configurations, che determinano le regole dell'analisi.
Le subnetworks, che organizzano la rete in unità operative.
La gestione della consistenza, che assicura che le analisi utilizzino uno stato coerente della rete.
L'architettura Enterprise, che deve garantire autenticazione, prestazioni, concorrenza e osservabilità.
Per questo motivo, il successo di un progetto Utility Network non può essere misurato soltanto verificando che una trace produca una selezione di elementi.
Occorre dimostrare che il risultato è corretto, riproducibile, coerente con lo stato della rete e ottenibile con prestazioni adeguate anche nelle condizioni operative reali.
Commenti