Documentazione dei prodotti
Citrix DaaS™
Visualizza PDF

Strumento di visibilità della cache host locale

August 20, 2026
Grazie al contributo di: 
C

Questo articolo descrive lo strumento di visibilità in tempo reale della cache host locale (LHC), una soluzione basata su PowerShell che fornisce visibilità negli ambienti Citrix Local Host Cache. Utilizzando questo strumento, è possibile monitorare l’integrità del Cloud Connector, identificare il leader eletto durante la modalità LHC, controllare la modalità di interruzione forzata e interrogare i registri eventi per risolvere i problemi di comportamento di LHC.

Panoramica

Lo strumento di visibilità in tempo reale della cache host locale (LHC) è una soluzione completa basata su PowerShell per fornire visibilità negli ambienti Citrix Local Host Cache. Fornisce sia un’interfaccia a riga di comando che semplici GUI accessibili dal Cloud Connector per consentire di:

  • Individuare i Cloud Connector in una zona o posizione delle risorse.
  • Identificare il leader eletto durante la modalità LHC.
  • Abilitare o disabilitare la modalità di interruzione forzata su tutti i Cloud Connector nella zona o posizione delle risorse.
  • Interrogare i registri eventi da provider specifici e ID evento.
  • Eseguire comandi Broker PowerShell sul leader eletto.

Prerequisiti

Prima di distribuire ed eseguire lo strumento di visibilità della cache host locale, assicurarsi che l’ambiente soddisfi i seguenti requisiti di sistema, autorizzazioni e requisiti di file.

Requisiti di sistema

  • Windows Server 2016 o versioni successive
  • PowerShell 5.1 o versioni successive
  • Deve essere eseguito su un Citrix Cloud Connector™
  • Servizi richiesti:
    • Servizio Citrix High Availability
    • Servizio Citrix ConfigSync

Autorizzazioni

  • Privilegi di amministratore sulla macchina locale
  • Autorizzazioni di esecuzione remota di PowerShell per tutti i Cloud Connector nella zona
  • Connettività di rete a tutti i Cloud Connector

File richiesti

  • LHCVisibilityTool.ps1 - Modulo PowerShell principale
  • LHCVisibilityToolGUI.ps1 - Applicazione GUI
  • HighAvailabilityServiceControl.psm1 - Modulo di controllo del servizio HA Citrix

Lo script PowerShell della GUI si trova in:

C:\Program Files\Citrix\Broker\Service\LHCVisibilityToolScripts
<!--NeedCopy-->

Per iniziare

Prima di eseguire lo strumento, impostare i criteri di esecuzione di PowerShell utilizzando una delle seguenti opzioni:

  • Opzione 1: RemoteSigned (più restrittiva):

     Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 <!--NeedCopy-->

  • Opzione 2: Solo sessione corrente (temporaneo):

     Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
 <!--NeedCopy-->

Nota:

Potrebbe essere necessario eseguire PowerShell come amministratore per modificare i criteri di esecuzione. Se si dispone solo di autorizzazioni a livello utente, utilizzare -Scope CurrentUser.

Utilizzare lo strumento tramite l’applicazione GUI

La GUI fornisce un’interfaccia a schede per rilevare i Cloud Connector, controllare la modalità di interruzione, interrogare i registri eventi ed eseguire i comandi del broker. Dopo aver avviato lo strumento, selezionare un’attività per visualizzarne le istruzioni:

Avviare la GUI 

cd "C:\Program Files\Citrix\Broker\Service\LHCVisibilityToolScripts"
.\LHCVisibilityToolGUI.ps1
<!--NeedCopy-->

Avvio della GUI dello strumento di visibilità LHC

Lo strumento utilizza un layout a tre schede con una barra di stato persistente nella parte inferiore.

Il layout a tre schede e la barra di stato persistente nella parte inferiore della finestra

La barra di stato si estende nella parte inferiore della finestra e contiene:

Elemento Descrizione
Stato operazione (sinistra) Operazione corrente o “Pronto”
Stato modalità HA Indicatori a punti per connettore (massimo 5 visualizzati; “+N altro” se troncato); il tooltip al passaggio del mouse mostra l’elenco completo
Ultimo aggiornamento Timestamp dell’ultimo aggiornamento riuscito dello stato HA
Visualizza registro Apre il file di registro della sessione in Blocco note

La barra di stato utilizza i seguenti colori per indicare lo stato HA:

Stato Colore
Funzionamento normale Verde
In attesa di HA Giallo oro
In attesa di ripristino Arancione
HA iniziale Rosso
HA esteso Rosso
Sconosciuto / Irraggiungibile Grigio

Individuare i Cloud Connector e identificare il leader

Nella scheda Stato e controllo del sistema, fare clic su Individua e identifica leader. Lo strumento rileva e mostra automaticamente il leader eletto tra tutti i Cloud Connector nella zona utilizzando:

  • Analisi del registro eventi (ID evento 3504)
  • Informazioni PeerStatus e IsElected del Registro di sistema
  • Verifica del servizio locale

Scheda Stato e controllo del sistema

Controllo della modalità di interruzione forzata

Nella scheda Stato e controllo del sistema, utilizzare i controlli della modalità di interruzione per gestire la modalità HA in tutta la zona:

  • Abilita modalità di interruzione forzata:
    • Forza tutti i Cloud Connector nella zona a entrare in modalità HA
    • Utilizza la cache host locale per il brokering
    • Richiede la sincronizzazione del database LHC
  • Disabilita modalità di interruzione forzata:
    • Consente al sistema di tornare alle normali operazioni
    • Si riconnette al sito primario quando disponibile

Avviso:

Queste azioni influiscono su tutti i Cloud Connector nella zona.

Interrogare e tenere traccia dei registri eventi

Nella scheda Query registro eventi, configurare i seguenti parametri di query:

  • Destinazione: Scegli tra:
    • Tutti i Cloud Connector
    • Solo leader eletto
    • Computer specifico (immettere FQDN)
  • Nome provider: Selezionare o immettere un provider personalizzato:
    • Servizio Citrix High Availability
    • Servizio Citrix ConfigSync
    • Servizio Citrix Broker
  • ID evento: Elenco separato da virgole (ad esempio, 3502,3503,3506)
  • Intervallo di tempo: Filtra facoltativamente per ora di inizio e fine
  • Eventi massimi: Numero massimo di eventi da recuperare per computer (predefinito: 100)

Utilizzare i seguenti pulsanti per lavorare con gli eventi:

  • Interroga eventi: Interroga i registri eventi utilizzando i parametri di query configurati.
  • Eventi HA passati: Trova i limiti di inizio e fine LHC (eventi 3502, 3503, 3508) dai parametri di query configurati e visualizza l’evento di riepilogo finale per fornire una panoramica.
  • Cancella eventi: Cancella l’elenco eventi, il pannello dei dettagli e lo stato di tracciamento.
  • Esporta report: Crea statistiche dagli eventi interrogati nell’interfaccia grafica e li salva come file di testo. (Utilizza l’output dal pulsante Mostra statistiche eventi.)

Scheda Query registro eventi

Il monitoraggio in tempo reale si comporta come segue:

  • Il monitoraggio in tempo reale monitora i nuovi eventi di riepilogo ogni 120 secondi mentre LHC è attivo.
  • Quando inizia il monitoraggio in tempo reale, determina l’ora di inizio per la modalità LHC facendo riferimento all’evento 3502 ed elenca tutti gli eventi apparsi dall’inizio.
  • Il monitoraggio in tempo reale può essere interrotto manualmente o automaticamente quando la modalità LHC si conclude.

La sezione inferiore fornisce due visualizzazioni principali:

  • Pannello sinistro:
    • Gli eventi sono elencati cronologicamente con dettagli chiave (numero evento, ora, ID, tipo).
    • Ogni evento è visivamente distinto per colore in base al suo tipo, seguendo il riferimento dell’ID evento.
    • La selezione di un evento visualizza ulteriori informazioni su di esso.
  • Pannello destro: Due opzioni di visualizzazione consentono di passare da riepiloghi statistici a informazioni dettagliate per l’evento selezionato:
    • Mostra dettagli evento: Dettagli completi per l’evento scelto.
    • Mostra statistiche eventi: Statistiche che riepilogano gli eventi in modalità HA, incluse metriche tabulari e grafici a barre ASCII dagli eventi di riepilogo (3507).

L’immagine seguente mostra la visualizzazione dei dettagli dell’evento:

Vista dettagli evento

L’immagine seguente mostra la vista delle statistiche degli eventi:

Vista statistiche eventi

Riferimento: ID evento HA e ConfigSync

Le sezioni seguenti elencano gli ID evento comuni per provider.

Servizio Citrix High Availability:

ID evento Descrizione
3502 Modalità HA avviata (broker eletto)
3503 Uscita dalla modalità HA (operazioni normali ripristinate)
3506 Modalità HA avviata (broker non eletto)
3507 Riepilogo periodico della modalità HA (broker eletto)
3508 Fine del riepilogo della modalità HA (broker eletto)

Servizio Citrix ConfigSync:

ID evento Descrizione
503 Processo di sincronizzazione avviato
504 Sincronizzazione completata correttamente
505 Sincronizzazione non riuscita
507 Sincronizzazione abbandonata a causa della modalità HA
510 Nessun dato di configurazione ricevuto
517 Problema di comunicazione con il broker primario
518 ConfigSync interrotto (servizio HA non in esecuzione)

Eseguire i comandi del broker

Nella scheda Comandi broker, i comandi predefiniti sono:

  • Get-BrokerMachine: Recupera le informazioni VDA/macchina
  • Get-BrokerSession: Recupera le sessioni attive
  • Get-BrokerDesktopGroup: Recupera i gruppi di consegna
  • Get-BrokerCatalog: Recupera i cataloghi di macchine
  • Get-BrokerApplication: Recupera le applicazioni pubblicate

Scheda Comandi broker

Suggerimento:

Utilizzare la casella di testo del filtro per cercare contemporaneamente in tutte le colonne di stringa un elemento specifico nei risultati.

Per eseguire un comando personalizzato:

  1. Immettere un comando, ad esempio Get-BrokerMachine -MaxRecordCount 2.
  2. Specificare facoltativamente le proprietà da restituire (separate da virgole).
  3. Fare clic su Esegui.

Comando personalizzato

Nota:

I comandi del broker forniscono informazioni recenti dal database LHC quando:

  • Il sistema è in modalità LHC.
  • È stato identificato un leader eletto.
  • Il database LHC è disponibile.

Visualizzare i log delle sessioni

Per aprire il log della sessione corrente, fare clic su Visualizza log nella barra di stato. Il log si apre in Blocco note.

Ogni sessione crea un file di log in %TEMP%\LHCVisibilityTool_<yyyyMMdd_HHmmss>.log. I messaggi vengono anche scritti nella console host con codifica a colori.

Utilizzare lo strumento tramite la riga di comando

Oltre all’interfaccia grafica, è possibile eseguire lo strumento direttamente da PowerShell. Dopo aver importato il modulo, utilizzare i seguenti comandi per eseguire ogni attività. Selezionare un’attività per accedere al relativo comando:

Avviare lo strumento da riga di comando 

cd "C:\Program Files\Citrix\Broker\Service\LHCVisibilityToolScripts"
. .\LHCVisibilityTool.ps1
<!--NeedCopy-->

Individuare i Cloud Connector 

$connectors = Get-CloudConnectorsInZone
$connectors | ForEach-Object { Write-Host $_ }
<!--NeedCopy-->

Identificare il leader eletto 

$leader = Get-ElectedLeader
Write-Host "Elected Leader: $leader"
<!--NeedCopy-->

Ottenere lo stato di interruzione 

$states = Get-OutageState
foreach ($connector in $states.Keys) {
    Write-Host "$connector : $($states[$connector].State)"
}
<!--NeedCopy-->

Interrogare i registri eventi

Interrogare tutti i Cloud Connector per gli eventi HA:

$results = Get-LHCEventLogs -EventID @(3502, 3503, 3506) `
    -ProviderName "Citrix High Availability Service" `
    -StartTime (Get-Date).AddDays(-7) `
    -EndTime (Get-Date) `
    -MaxEvents 100

# Display results
foreach ($computer in $results.Keys) {
    Write-Host "`n=== $computer ==="
    if ($results[$computer].Success) {
        $results[$computer].Events | Format-Table TimeCreated, Id, Message -AutoSize
    } else {
        Write-Host "ERROR: $($results[$computer].Error)" -ForegroundColor Red
    }
}
<!--NeedCopy-->

Interrogare solo il leader eletto:

$results = Get-LHCEventLogs -ComputerName "ElectedLeader" `
    -EventID @(3507) `
    -ProviderName "Citrix High Availability Service" `
    -MaxEvents 50
<!--NeedCopy-->

Interrogare un computer specifico:

$results = Get-LHCEventLogs -ComputerName "CC-01.domain.com" `
    -EventID @(503, 504, 505) `
    -ProviderName "Citrix ConfigSync Service"
<!--NeedCopy-->

Eseguire comandi broker

Recupera tutte le macchine:

$machines = Invoke-BrokerCommand -Command "Get-BrokerMachine" `
    -Properties @("MachineName", "RegistrationState", "SessionCount")
$machines | Format-Table -AutoSize
<!--NeedCopy-->

Recupera sessioni attive:

$sessions = Invoke-BrokerCommand -Command "Get-BrokerSession" `
    -Properties @("UserName", "MachineName", "SessionState")
$sessions | Format-Table -AutoSize
<!--NeedCopy-->

Eseguire un comando personalizzato con parametri:

$params = @{
    MaxRecordCount = 10
}
$results = Invoke-BrokerCommand -Command "Get-BrokerMachine" `
    -Parameters $params `
    -Properties @("MachineName", "DesktopGroupName")
<!--NeedCopy-->

Controllare la modalità di interruzione

Abilitare la modalità di interruzione forzata su tutti i Cloud Connector:

$results = Set-LHCOutageMode -Enable

# Check results
foreach ($connector in $results.Keys) {
    $status = if ($results[$connector].Success) { "SUCCESS" } else { "FAILED" }
    Write-Host "$connector : $status"
    if (-not $results[$connector].Success) {
        Write-Host "  Error: $($results[$connector].Error)" -ForegroundColor Red
    }
}
<!--NeedCopy-->

Disabilitare la modalità di interruzione forzata:

$results = Set-LHCOutageMode

# Check results
foreach ($connector in $results.Keys) {
    $status = if ($results[$connector].Success) { "SUCCESS" } else { "FAILED" }
    Write-Host "$connector : $status"
}
<!--NeedCopy-->

Risoluzione dei problemi

Per risolvere i problemi con lo strumento, seguire questo processo generale:

  1. Controllare il registro eventi dell’applicazione per messaggi di errore dettagliati.
  2. Verificare che tutti i prerequisiti siano soddisfatti.
  3. Esaminare i problemi comuni nella tabella seguente e le procedure consigliate descritte più avanti in questo articolo.
  4. Fare riferimento a Local Host Cache e al documento tecnico Evitare configurazioni errate comuni che possono influire negativamente sulla resilienza di DaaS.

La tabella seguente elenca i problemi comuni che si potrebbero riscontrare durante l’utilizzo dello strumento e le relative soluzioni consigliate.

Problema Soluzione
Nessun Cloud Connector trovato

  1. Verificare di essere in esecuzione su un Cloud Connector.
  2. Verificare che i servizi richiesti siano in esecuzione utilizzando Get-Service CitrixHighAvailabilityService, CitrixConfigSyncService.
  3. Controllare la chiave di registro HKLM:\SOFTWARE\Citrix\Broker\Service\State\LHC.
Impossibile identificare il leader eletto
  1. Controllare l’ID evento 3502 nel registro applicazioni.
  2. Verificare la connettività a tutti i Cloud Connector.
Comando broker non riuscito


  1. Assicurarsi che il sistema sia in modalità HA.
  2. Verificare che il leader eletto sia identificato.
  3. Verificare che il database LHC sia sincronizzato.
  4. Verificare che HighAvailabilityServiceControl.psm1 sia presente.
Errori di esecuzione remota

  1. Verificare che WinRM sia abilitato su tutti i Cloud Connector utilizzando Test-WSMan -ComputerName <CloudConnectorFQDN>.
  2. Verificare che le regole del firewall consentano il remoting di PowerShell.
  3. Verificare di disporre dei privilegi di amministratore.
La query del registro eventi non restituisce risultati

  1. Verificare che gli ID evento siano corretti per il provider selezionato.
  2. Verificare che l’intervallo di tempo includa gli eventi previsti.
  3. Assicurarsi che i limiti di dimensione del registro eventi non abbiano causato la sovrascrittura di eventi precedenti.

Procedure consigliate

Seguire queste procedure consigliate per ottenere il massimo dallo strumento e per gestire l’ambiente della cache host locale in modo sicuro.

Monitoraggio regolare

  • Eseguire Discover Cloud Connectors e Identify Elected Leader periodicamente.
  • Monitorare gli eventi ConfigSync (503, 504, 505) per problemi di sincronizzazione.

Analisi del registro eventi

  • Interrogare gli eventi HA degli ultimi 7 giorni per comprendere i modelli di interruzione.
  • Cercare l’ID evento 3507 durante la modalità HA per statistiche dettagliate.

Comandi del broker

  • Eseguire solo sul leader eletto.
  • Limitare la selezione delle proprietà per migliorare le prestazioni.
  • Utilizzare il parametro MaxRecordCount per ambienti di grandi dimensioni.

Modalità di interruzione

  • Utilizzare la modalità di interruzione forzata solo per test o manutenzione pianificata.
  • Verificare sempre che il database LHC sia sincronizzato prima di abilitare.
  • Disabilitare la modalità di interruzione forzata una volta ripristinata la connettività primaria.

Sicurezza

  • Eseguire con account con privilegi minimi, ove possibile.
  • Utilizzare canali sicuri per l’esecuzione remota.
  • Controllare le modifiche alla modalità di interruzione.

Esempi

I seguenti esempi presuppongono che sia stata creata una cartella in C:\Reports per contenere l’output.

Esempio 1: Report giornaliero della modalità HA 

# Import module
. "C:\Program Files\Citrix\Broker\Service\LHCVisibilityToolScripts\LHCVisibilityTool.ps1"

# Discover environment
$connectors = Get-CloudConnectorsInZone
Write-Host "Found $($connectors.Count) Cloud Connectors"

# Check HA status
$leader = Get-ElectedLeader
if ($leader) {
    Write-Host "System is in HA mode. Elected leader: $leader"

    # Get HA summary events from elected leader
    $events = Get-LHCEventLogs -ComputerName "ElectedLeader" `
        -EventID @(3507, 3508) `
        -ProviderName "Citrix High Availability Service" `
        -StartTime (Get-Date).AddHours(-24) `
        -MaxEvents 100

    # Export to file
    $events[$leader].Events | Select-Object TimeCreated, Id, LevelDisplayName, Message | Export-Csv -Path "C:\Reports\HA-Status-$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation
} else {
    Write-Host "System is in normal operations mode"
}
<!--NeedCopy-->

Esempio 2: Controllare lo stato di ConfigSync su tutti i connettori 

. "C:\Program Files\Citrix\Broker\Service\LHCVisibilityToolScripts\LHCVisibilityTool.ps1"

$results = Get-LHCEventLogs -ComputerName "All" `
    -EventID @(503, 504, 505) `
    -ProviderName "Citrix ConfigSync Service" `
    -StartTime (Get-Date).AddHours(-6) `
    -MaxEvents 10

foreach ($computer in $results.Keys) {
    $lastEvent = $results[$computer].Events | Sort-Object TimeCreated -Descending | Select-Object -First 1
    $status = switch ($lastEvent.Id) {
        503 { "In Progress" }
        504 { "Success" }
        505 { "Failed" }
    }
    Write-Host "$computer - Last Sync: $($lastEvent.TimeCreated) - Status: $status"
}
<!--NeedCopy-->

Esempio 3: Ottenere il conteggio delle sessioni durante la modalità HA 

. "C:\Program Files\Citrix\Broker\Service\LHCVisibilityToolScripts\LHCVisibilityTool.ps1"

# Ensure we have an elected leader
$leader = Get-ElectedLeader
if ($leader) {
    # Get all sessions
    $sessions = Invoke-BrokerCommand -Command "Get-BrokerSession"
    Write-Host "Total Sessions: $($sessions.Count)"

    # Group by state
    $sessionsByState = $sessions | Group-Object SessionState
    foreach ($group in $sessionsByState) {
        Write-Host "  $($group.Name): $($group.Count)"
    }
} else {
    Write-Host "Not in HA mode - cannot query sessions from LHC"
}
<!--NeedCopy-->

Scenari avanzati

I seguenti scenari combinano più funzioni dello strumento in script per operazioni più complesse, come l’automazione dei test di interruzione e l’esportazione dei dati storici della modalità HA.

Automatizzare i test di interruzione 

# Enable outage mode
Write-Host "Enabling forced outage mode..."
$enableResults = Set-LHCOutageMode -Enable
$allEnabled = $enableResults.Values | Where-Object { -not $_.Success }
if ($allEnabled) {
    Write-Host "WARNING: Some connectors failed to enable outage mode - aborting test" -ForegroundColor Yellow
    return
}
Start-Sleep -Seconds 30

# Verify elected leader
$leader = Get-ElectedLeader
Write-Host "Elected leader: $leader"

# Test brokering
$machines = Invoke-BrokerCommand -Command "Get-BrokerMachine" -Properties @("MachineName", "RegistrationState")
Write-Host "Retrieved $($machines.Count) machines"

# Disable outage mode
Write-Host "Disabling forced outage mode..."
$disableResults = Set-LHCOutageMode
<!--NeedCopy-->

Esportare la cronologia della modalità HA 

$haEvents = Get-LHCEventLogs -ComputerName "All" `
    -EventID @(3502, 3503) `
    -ProviderName "Citrix High Availability Service" `
    -StartTime (Get-Date).AddDays(-30) `
    -MaxEvents 1000

$report = foreach ($computer in $haEvents.Keys) {
    if (-not $haEvents[$computer].Success) { continue }
    foreach ($event in $haEvents[$computer].Events) {
        [PSCustomObject]@{
            Computer  = $computer
            EventID   = $event.Id
            EventType = if ($event.Id -eq 3502) { "Entered HA Mode" } else { "Exited HA Mode" }
            Time      = $event.TimeCreated
        }
    }
}
$report | Sort-Object Time | Export-Csv -Path "C:\Reports\HA-History.csv" -NoTypeInformation
<!--NeedCopy-->
Strumento di visibilità della cache host locale
August 20, 2026
Grazie al contributo di: 
C
August 20, 2026
Grazie al contributo di: 
C

In questo articolo

Feedback sito | Your privacy choices footer linkScelte di privacy | Privacy e condizioni legali | Preferenze cookie | Impostazioni di consenso | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.