Aggiungere report sull'integrità di Service Fabric personalizzatiAdd custom Service Fabric health reports

In Azure Service Fabric è disponibile un modello di integrità progettato per contrassegnare condizioni di non integrità di cluster e applicazioni in entità specifiche.Azure Service Fabric introduces a health model designed to flag unhealthy cluster and application conditions on specific entities. Il modello di integrità usa i , costituiti da watchdog e componenti di sistema.The health model uses health reporters (system components and watchdogs). Lo scopo è semplificare e velocizzare la diagnosi e la risoluzione dei problemi.The goal is easy and fast diagnosis and repair. Gli sviluppatori del servizio devono tenere conto dell'integrità fin dall'inizio.Service writers need to think upfront about health. È necessario segnalare tutte le condizioni che possono influire sull'integrità, soprattutto se aiutano a risalire alla causa dei problemi.Any condition that can impact health should be reported on, especially if it can help flag problems close to the root. Le informazioni sull'integrità consentono di risparmiare tempo ed energie per il debug e l'analisi.The health information can save time and effort on debugging and investigation. L'utilità è particolarmente evidente quando il servizio è in esecuzione su larga scala nel cloud (privato o Azure).The usefulness is especially clear once the service is up and running at scale in the cloud (private or Azure).

I generatori di report di Service Fabric eseguono il monitoraggio di condizioni di particolare interesse.The Service Fabric reporters monitor identified conditions of interest. Generano report su tali condizioni in base alla visualizzazione locale.They report on those conditions based on their local view. L'archivio integrità aggrega i dati sull'integrità inviati da tutti i reporter per determinare se le entità sono complessivamente integre.The health store aggregates health data sent by all reporters to determine whether entities are globally healthy. Il modello è concepito per essere completo, flessibile e facile da usare.The model is intended to be rich, flexible, and easy to use. La qualità dei report sull'integrità determina il livello di accuratezza della visualizzazione dell'integrità del cluster.The quality of the health reports determines the accuracy of the health view of the cluster. I falsi positivi che visualizzano erroneamente problemi di non integrità possono influire negativamente sugli aggiornamenti o su altri servizi che usano i dati di integrità,False positives that wrongly show unhealthy issues can negatively impact upgrades or other services that use health data. come ad esempio i servizi di ripristino e i meccanismi di avviso.Examples of such services are repair services and alerting mechanisms. Pertanto, è necessario creare report che segnalino le condizioni a cui si è interessati nel miglior modo possibile.Therefore, some thought is needed to provide reports that capture conditions of interest in the best possible way.

Per progettare e implementare i report sull'integrità, i watchdog e i componenti di sistema devono:To design and implement health reporting, watchdogs and system components must:

  • Definire la condizione di cui devono occuparsi, il modo in cui viene monitorata e l'impatto sulla funzionalità del cluster o dell'applicazione.Define the condition they are interested in, the way it is monitored, and the impact on the cluster or application functionality. Tali informazioni determinano la proprietà del report sull'integrità e lo stato di integrità.Based on this information, decide on the health report property and health state.
  • Determinare l' entità a cui si applica il report.Determine the entity that the report applies to.
  • Determinare dove viene eseguito il report, ovvero dall'interno del servizio o da un watchdog interno o esterno.Determine where the reporting is done, from within the service or from an internal or external watchdog.
  • Definire un'origine usata per identificare il generatore di report.Define a source used to identify the reporter.
  • Scegliere una strategia di creazione di report (periodicamente o in caso di transizioni).Choose a reporting strategy, either periodically or on transitions. La creazione periodica di report è la scelta consigliata, perché richiede codice più semplice ed è meno soggetta a errori.The recommended way is periodically, as it requires simpler code and is less prone to errors.
  • Determinare per quanto tempo il report sulle condizioni di non integrità deve rimanere nell'archivio integrità e come deve essere eliminato.Determine how long the report for unhealthy conditions should stay in the health store and how it should be cleared. Queste informazioni determinano la durata (TTL) del report e il comportamento alla scadenza.Using this information, decide the report's time to live and remove-on-expiration behavior.

Come indicato, i report possono essere creati da:As mentioned, reporting can be done from:

  • La replica del servizio di Service Fabric monitorato.The monitored Service Fabric service replica.
  • Watchdog interni distribuiti come servizio di Service Fabric, ad esempio un servizio senza stato di Service Fabric che monitora le condizioni e genera i report.Internal watchdogs deployed as a Service Fabric service (for example, a Service Fabric stateless service that monitors conditions and issues reports). Il watchdog può essere distribuito su tutti i nodi o è possibile creare un'affinità con il servizio monitorato.The watchdogs can be deployed an all nodes or can be affinitized to the monitored service.
  • Watchdog interni eseguiti sui nodi di Service Fabric ma non implementati come servizi di Service Fabric.Internal watchdogs that run on the Service Fabric nodes but are not implemented as Service Fabric services.
  • Watchdog esterni che interrogano la risorsa dall' esterno del cluster di Service Fabric, ad esempio un servizio di monitoraggio come Gomez.External watchdogs that probe the resource from outside the Service Fabric cluster (for example, monitoring service like Gomez).

Nota

Per impostazione predefinita, il cluster viene popolato con report sull'integrità inviati dai componenti di sistema.Out of the box, the cluster is populated with health reports sent by the system components. Per altre informazioni, vedere Uso dei report sull'integrità del sistema per la risoluzione dei problemi.Read more at Using system health reports for troubleshooting. I report dell'utente devono essere inviati alle entità di integrità già create dal sistema.The user reports must be sent on health entities that have already been created by the system.

Una volta definita la progettazione dei report sull'integrità, è possibile inviarli facilmente.Once the health reporting design is clear, health reports can be sent easily. È possibile usare FabricClient per segnalare lo stato di integrità se il cluster non è sicuro o se il client Fabric ha privilegi di amministratore.You can use FabricClient to report health if the cluster is not secure or if the fabric client has admin privileges. Per la creazione di report è possibile usare l'API con FabricClient.HealthManager.ReportHealth, PowerShell oppure REST.Reporting can be done through the API by using FabricClient.HealthManager.ReportHealth, through PowerShell, or through REST. Sono disponibili controlli di configurazione che riuniscono i report in batch per migliorare le prestazioni.Configuration knobs batch reports for improved performance.

Nota

L'esecuzione di report sull'integrità è un'operazione sincrona e rappresenta solo l'attività di convalida sul lato client.Report health is synchronous, and it represents only the validation work on the client side. Il fatto che il report venga accettato dal client di integrità o dagli oggetti Partition o CodePackageActivationContext non significa che venga applicato nell'archivio.The fact that the report is accepted by the health client or the Partition or CodePackageActivationContext objects doesn't mean that it is applied in the store. Viene inviato in modo asincrono e possibilmente in batch con altri report.It is sent asynchronously and possibly batched with other reports. L'elaborazione sul server può comunque non riuscire. È possibile che un numero di sequenza non sia aggiornato, che l'entità a cui deve essere applicato il report sia stata eliminata e così via.The processing on the server may still fail: the sequence number could be stale, the entity on which the report must be applied has been deleted, etc.

Client di integritàHealth client

I report sull'integrità vengono inviati all'archivio integrità tramite un client di integrità, che risiede nel client Fabric.The health reports are sent to the health store through a health client, which lives inside the fabric client. Il client di integrità può essere configurato con le impostazioni seguenti:The health client can be configured with the following settings:

  • HealthReportSendInterval: ritardo tra il momento in cui il report viene aggiunto al client e il momento in cui viene inviato all'archivio integrità.HealthReportSendInterval: The delay between the time the report is added to the client and the time it is sent to the health store. Questo valore viene usato per inviare i report in batch un singolo messaggio, anziché inviare un messaggio per ogni report,Used to batch reports into a single message, rather than sending one message for each report. e migliorare così le prestazioni.The batching improves performance. Impostazione predefinita: 30 secondi.Default: 30 seconds.
  • HealthReportRetrySendInterval: intervallo dopo il quale il client di integrità invia nuovamente i report sull'integrità accumulati all'archivio integrità.HealthReportRetrySendInterval: The interval at which the health client resends accumulated health reports to the health store. Impostazione predefinita: 30 secondi.Default: 30 seconds.
  • HealthOperationTimeout: periodo di timeout per un messaggio di report inviato all'archivio integrità.HealthOperationTimeout: The timeout period for a report message sent to the health store. In caso di timeout di un messaggio scade, il client di integrità riprova a inviarlo finché l'archivio integrità non conferma che i report sono stati elaborati.If a message times out, the health client retries it until the health store confirms that the report has been processed. Valore predefinito: due minuti.Default: two minutes.

Nota

Quando i report vengono riuniti in batch, il client Fabric deve restare attivo almeno per il tempo previsto da HealthReportSendInterval per garantire l'invio dei report.When the reports are batched, the fabric client must be kept alive for at least the HealthReportSendInterval to ensure that they are sent. Se il messaggio viene perso o l'archivio integrità non può applicare i report a causa di errori temporanei, il client Fabric deve restare attivo più a lungo per dare la possibilità di riprovare.If the message is lost or the health store cannot apply them due to transient errors, the fabric client must be kept alive longer to give it a chance to retry.

La memorizzazione nel buffer sul client tiene conto dell'unicità dei report.The buffering on the client takes the uniqueness of the reports into consideration. Se un particolare generatore di report non corretto crea 100 report al secondo per la stessa proprietà della stessa entità, ad esempio, i report vengono sostituiti con l'ultima versione.For example, if a particular bad reporter is reporting 100 reports per second on the same property of the same entity, the reports are replaced with the last version. Nella coda del client sarà presente al massimo uno di questi report.At most one such report exists in the client queue. Se è configurato l'invio in batch, il numero di report inviati all'archivio integrità è solo uno per ogni intervallo di trasmissione.If batching is configured, the number of reports sent to the health store is just one per send interval. Questo è l'ultimo report aggiunto, che riflette lo stato più recente dell'entità.This report is the last added report, which reflects the most current state of the entity. Specificare i parametri di configurazione quando viene creato FabricClient passando FabricClientSettings con i valori desiderati per le voci correlate all'integrità.Specify configuration parameters when FabricClient is created by passing FabricClientSettings with the desired values for health-related entries.

L'esempio seguente crea un client Fabric e specifica che i report devono essere inviati quando vengono aggiunti.The following example creates a fabric client and specifies that the reports should be sent when they are added. In caso di timeout ed errori che supportano nuovi tentativi, questi vengono eseguiti ogni 40 secondi.On timeouts and errors that can be retried, retries happen every 40 seconds.

var clientSettings = new FabricClientSettings()
{
    HealthOperationTimeout = TimeSpan.FromSeconds(120),
    HealthReportSendInterval = TimeSpan.FromSeconds(0),
    HealthReportRetrySendInterval = TimeSpan.FromSeconds(40),
};
var fabricClient = new FabricClient(clientSettings);

Si consiglia di mantenere le impostazioni predefinite del client Fabric, con HealthReportSendInterval pari a 30 secondi.We recommend keeping the default fabric client settings, which set HealthReportSendInterval to 30 seconds. Questa impostazione garantisce prestazioni ottimali con l'invio in batch.This setting ensures optimal performance due to batching. Per i report critici che devono essere inviati il prima possibile, usare HealthReportSendOptions con il flag Immediate true nell'API FabricClient.HealthClient.ReportHealth.For critical reports that must be sent as soon as possible, use HealthReportSendOptions with Immediate true in FabricClient.HealthClient.ReportHealth API. I report con flag Immediate ignorano l'intervallo di invio in batch.Immediate reports bypass the batching interval. Usare questo flag con cautela. Quando possibile, è preferibile usare l'invio in batch del client di integrità.Use this flag with care; we want to take advantage of the health client batching whenever possible. L'invio immediato è utile anche quando il client Fabric è in fase di chiusura (ad esempio, il processo ha determinato uno stato non valido e deve essere arrestato per evitare effetti collaterali).Immediate send is also useful when the fabric client is closing (for example, the process has determined invalid state and needs to shut down to prevent side effects). Ciò assicura un invio ottimale dei report accumulati.It ensures a best-effort send of the accumulated reports. Quando viene aggiunto un report con il flag Immediate, il client di integrità invia in batch tutti i report accumulati dall'ultimo invio.When one report is added with Immediate flag, the health client batches all the accumulated reports since last send.

È possibile specificare gli stessi parametri quando si crea una connessione a un cluster tramite PowerShell.Same parameters can be specified when a connection to a cluster is created through PowerShell. L'esempio seguente avvia una connessione a un cluster locale:The following example starts a connection to a local cluster:

PS C:\> Connect-ServiceFabricCluster -HealthOperationTimeoutInSec 120 -HealthReportSendIntervalInSec 0 -HealthReportRetrySendIntervalInSec 40
True

ConnectionEndpoint   :
FabricClientSettings : {
                       ClientFriendlyName                   : PowerShell-1944858a-4c6d-465f-89c7-9021c12ac0bb
                       PartitionLocationCacheLimit          : 100000
                       PartitionLocationCacheBucketCount    : 1024
                       ServiceChangePollInterval            : 00:02:00
                       ConnectionInitializationTimeout      : 00:00:02
                       KeepAliveInterval                    : 00:00:20
                       HealthOperationTimeout               : 00:02:00
                       HealthReportSendInterval             : 00:00:00
                       HealthReportRetrySendInterval        : 00:00:40
                       NotificationGatewayConnectionTimeout : 00:00:00
                       NotificationCacheUpdateTimeout       : 00:00:00
                       }
GatewayInformation   : {
                       NodeAddress                          : localhost:19000
                       NodeId                               : 1880ec88a3187766a6da323399721f53
                       NodeInstanceId                       : 130729063464981219
                       NodeName                             : Node.1
                       }

Analogamente all'API, i report possono essere inviati usando l'opzione -Immediate per l'invio immediato, indipendentemente dal valore di HealthReportSendInterval.Similarly to API, reports can be sent using -Immediate switch to be sent immediately, regardless of the HealthReportSendInterval value.

Per REST, i report vengono inviati al gateway di Service Fabric, che ha un client Fabric interno.For REST, the reports are sent to the Service Fabric gateway, which has an internal fabric client. Per impostazione predefinita, questo client è configurato per inviare i report in batch ogni 30 secondi.By default, this client is configured to send reports batched every 30 seconds. È possibile modificare l'intervallo di invio in batch impostando l'opzione di configurazione del cluster HttpGatewayHealthReportSendInterval su HttpGateway.You can change the batch interval with the cluster configuration setting HttpGatewayHealthReportSendInterval on HttpGateway. Come indicato, è preferibile inviare i report con Immediate true.As mentioned, a better option is to send the reports with Immediate true.

Nota

Per fare in modo che i servizi non autorizzati non creino report sull'integrità per le entità del cluster, configurare il server in modo che accetti solo le richieste dei client protetti.To ensure that unauthorized services can't report health against the entities in the cluster, configure the server to accept requests only from secured clients. Per la classe FabricClient usata per la creazione di report è necessario abilitare la sicurezza per consentire la comunicazione con il cluster, ad esempio con Kerberos o l'autenticazione del certificato.The FabricClient used for reporting must have security enabled to be able to communicate with the cluster (for example, with Kerberos or certificate authentication). Per altre informazioni, vedere la pagina relativa alla sicurezza del cluster.Read more about cluster security.

Report dai servizi con privilegi limitatiReport from within low privilege services

Se i servizi di Service Fabric non hanno accesso amministrativo al cluster, è possibile creare report sull'integrità per le entità dal contesto corrente tramite Partition o CodePackageActivationContext.If Service Fabric services do not have admin access to the cluster, you can report health on entities from the current context through Partition or CodePackageActivationContext.

Nota

Internamente gli oggetti Partition e CodePackageActivationContext hanno un client di integrità configurato con le impostazioni predefinite.Internally, the Partition and the CodePackageActivationContext hold a health client configured with default settings. Come illustrato per il client di integrità, i report vengono raggruppati in batch e inviati in base a un timer.As explained for the health client, reports are batched and sent on a timer. Gli oggetti devono essere mantenuti attivi per poter inviare il report.The objects should be kept alive to have a chance to send the report.

È possibile specificare HealthReportSendOptions quando si inviano i report tramite le API di integrità Partition e CodePackageActivationContext.You can specify HealthReportSendOptions when sending reports through Partition and CodePackageActivationContext health APIs. Per i report critici che devono essere inviati il prima possibile, usare HealthReportSendOptions con il flag Immediate true.If you have critical reports that must be sent as soon as possible, use HealthReportSendOptions with Immediate true. I report con flag Immediate ignorano l'intervallo di invio in batch del client di integrità interno.Immediate reports bypass the batching interval of the internal health client. Come indicato in precedenza, usare questo flag con cautela. Quando possibile, è preferibile usare l'invio in batch del client di integrità.As mentioned before, use this flag with care; we want to take advantage of the health client batching whenever possible.

Creare report sull'integritàDesign health reporting

Il primo passaggio per la creazione di report di alta qualità consiste nell'identificare le condizioni che possono influire sull'integrità del servizio.The first step in generating high-quality reports is identifying the conditions that can impact the health of the service. Tutte le condizioni che facilitano l'identificazione dei problemi nel servizio o nel cluster non appena insorgono, o meglio ancora prima che si verifichino, possono consentire un notevole risparmio,Any condition that can help flag problems in the service or cluster when it starts--or even better, before a problem happens--can potentially save billions of dollars. grazie alla riduzione dei tempi di inattività e del numero di ore impiegate per l'analisi e la risoluzione dei problemi, oltre all'aumento della soddisfazione dei clienti.The benefits include less down time, fewer night hours spent investigating and repairing issues, and higher customer satisfaction.

Dopo aver identificato le condizioni, gli sviluppatori dei watchdog devono stabilire il modo migliore per monitorarle, trovando il giusto equilibrio tra sovraccarico e utilità.Once the conditions are identified, watchdog writers need to figure out the best way to monitor them for balance between overhead and usefulness. Si consideri, ad esempio, un servizio che esegue calcoli complessi usando alcuni file temporanei in una condivisione.For example, consider a service that does complex calculations that use some temporary files on a share. Un watchdog può monitorare la condivisione per verificare che sia disponibile spazio sufficiente.A watchdog could monitor the share to ensure that enough space is available. Può restare in attesa di notifiche relative a modifiche di file o directory.It could listen for notifications of file or directory changes. Può segnalare un avviso se si raggiunge una soglia prestabilita e un errore se la condivisione è piena.It could report a warning if an upfront threshold is reached, and report an error if the share is full. In caso di avviso, un sistema di ripristino può avviare la pulizia dei file meno recenti nella condivisione.On a warning, a repair system could start cleaning up older files on the share. In caso di errore, un sistema di ripristino può spostare la replica del servizio su un altro nodo.On an error, a repair system could move the service replica to another node. Si noti come vengono descritti gli stati della condizione in termini di integrità: lo stato della condizione può essere considerato integro (ok) o non integro (avviso o errore).Note how the condition states are described in terms of health: the state of the condition that can be considered healthy (ok) or unhealthy (warning or error).

Dopo aver impostato i dettagli di monitoraggio, gli sviluppatori del watchdog devono decidere come implementarlo.Once the monitoring details are set, a watchdog writer needs to figure out how to implement the watchdog. Se è possibile determinare le condizioni dall'interno del servizio, il watchdog può far parte del servizio stesso che viene monitorato.If the conditions can be determined from within the service, the watchdog can be part of the monitored service itself. Ad esempio, il codice del servizio può controllare l'utilizzo della condivisione e quindi creare un report ogni volta che prova a scrivere un file.For example, the service code can check the share usage, and then report every time it tries to write a file. Il vantaggio di questo approccio è dato dalla semplicità della creazione di report.The advantage of this approach is that reporting is simple. È necessario fare attenzione per evitare che gli errori del watchdog influiscano negativamente sulla funzionalità del servizio.Care must be taken to prevent watchdog bugs from impacting the service functionality.

Non è sempre possibile creare report dall'interno del servizio monitorato.Reporting from within the monitored service is not always an option. Un watchdog all'interno del servizio potrebbe non riuscire a rilevare le condizioni.A watchdog within the service may not be able to detect the conditions. Potrebbe non avere la logica o i dati per prendere una decisione.It may not have the logic or data to make the determination. Il monitoraggio delle condizioni potrebbe comportare un sovraccarico eccessivo.The overhead of monitoring the conditions may be high. Le condizioni potrebbero anche non essere specifiche di un servizio, ma avere invece ripercussioni sulle interazioni tra i servizi.The conditions also may not be specific to a service, but instead affect interactions between services. Un'altra opzione consiste nel creare i watchdog nel cluster come processi separati.Another option is to have watchdogs in the cluster as separate processes. I watchdog eseguono il monitoraggio delle condizioni e generano report, senza influire in alcun modo sui servizi principali.The watchdogs monitor the conditions and report, without affecting the main services in any way. Ad esempio, questi watchdog possono essere implementati come servizi senza stato nella stessa applicazione, distribuiti in tutti i nodi o negli stessi nodi del servizio.For example, these watchdogs could be implemented as stateless services in the same application, deployed on all nodes or on the same nodes as the service.

A volte anche un watchdog in esecuzione nel cluster può non essere una soluzione efficace.Sometimes, a watchdog running in the cluster is not an option either. Se la condizione monitorate è la disponibilità o la funzionalità del servizio dal punto di vista degli utenti, è preferibile inserire i watchdog nella stessa posizione dei client degli utenti,If the monitored condition is the availability or functionality of the service as users see it, it's best to have the watchdogs in the same place as the user clients. dove possono testare le operazioni allo stesso modo in cui vengono eseguite dagli utenti.There, they can test the operations in the same way users call them. Ad esempio, è possibile configurare un watchdog esterno al cluster che invia le richieste al servizio e controlla la latenza e la correttezza del risultato.For example, you can have a watchdog that lives outside the cluster, issues requests to the service, and checks the latency and correctness of the result. Ad esempio, per un servizio calcolatrice, verificare se l'operazione 2+2 restituisce 4 in tempi ragionevoli.(For a calculator service, for example, does 2+2 return 4 in a reasonable amount of time?)

Una volta finalizzati i dettagli del watchdog, stabilire un ID di origine che lo identifichi in modo univoco.Once the watchdog details have been finalized, you should decide on a source ID that uniquely identifies it. Se nel cluster sono presenti più watchdog dello stesso tipo, devono generare report per entità diverse oppure, se generano report per la stessa entità, usare proprietà o ID di origine diversi.If multiple watchdogs of the same type are living in the cluster, they must report on different entities, or, if they report on the same entity, use different source ID or property. In questo modo, i report possono coesistere.This way, their reports can coexist. La proprietà del report sull'integrità deve contenere la condizione monitorata.The property of the health report should capture the monitored condition. Ad esempio, nel caso sopra riportato la proprietà può essere ShareSize. Se più report si applicano alla stessa condizione, la proprietà deve contenere alcune informazioni dinamiche per consentire la coesistenza dei report.(For the example above, the property could be ShareSize.) If multiple reports apply to the same condition, the property should contain some dynamic information that allows reports to coexist. Ad esempio, se è necessario monitorare più condivisioni, il nome della proprietà può essere ShareSize-sharename.For example, if multiple shares need to be monitored, the property name can be ShareSize-sharename.

Nota

Non usare l'archivio integrità per conservare informazioni sullo stato.Do not use the health store to keep status information. Nei report solo le informazioni correlate all'integrità devono essere segnalate come informazioni sull'integrità, perché influiscono sulla valutazione dell'integrità di un'entità.Only health-related information should be reported as health, as this information impacts the health evaluation of an entity. L'archivio integrità non è stato progettato come archivio per utilizzo generico.The health store was not designed as a general-purpose store. Usa la logica di valutazione dell'integrità per aggregare tutti i dati nello stato di integrità.It uses health evaluation logic to aggregate all data into the health state. L'invio di informazioni non correlate all'integrità, come la creazione di report sullo stato con stato di integrità OK, non ha ripercussioni sullo stato di integrità aggregato, ma può influire negativamente sulle prestazioni dell'archivio integrità.Sending information unrelated to health (like reporting status with a health state of OK) doesn't impact the aggregated health state, but it can negatively affect the performance of the health store.

Il passaggio successivo consiste nel decidere per quale entità creare report.The next decision point is which entity to report on. Nella maggior parte dei casi, la condizione identifica chiaramente l'entità.Most of the time, the condition clearly idetifies the entity. Scegliere l'entità con la migliore granularità possibile.Choose the entity with best possible granularity. Se una condizione influisce su tutte le repliche in una partizione, creare report sulla partizione, non sul servizio.If a condition impacts all replicas in a partition, report on the partition, not on the service. Esistono tuttavia casi particolari che richiedono maggiore attenzione.There are corner cases where more thought is needed, though. Se la condizione influisce su un'entità, ad esempio una replica, ma si vuole segnalare la condizione per un tempo superiore alla durata della replica, è necessario creare report sulla partizione.If the condition impacts an entity, such as a replica, but the desire is to have the condition flagged for more than the duration of replica life, then it should be reported on the partition. In caso contrario, quando la replica viene eliminata, l'archivio integrità pulisce tutti i relativi report.Otherwise, when the replica is deleted, the health store cleans up all its reports. Gli sviluppatori dei watchdog devono considerare la durata dell'entità e del report.Watchdog writers must think about the lifetimes of the entity and the report. È necessario specificare chiaramente quando rimuovere un report da un archivio, ad esempio quando un errore segnalato per un'entità non si verifica più.It must be clear when a report should be cleaned up from a store (for example, when an error reported on an entity no longer applies).

L'esempio seguente illustra i punti descritti.Let's look at an example that puts together the points I described. Si consideri un'applicazione di Service Fabric composta da un servizio master con stato persistente e servizi secondari senza stato distribuiti in tutti i nodi, ovvero un tipo di servizio secondario per ogni tipo di attività.Consider a Service Fabric application composed of a master stateful persistent service and secondary stateless services deployed on all nodes (one secondary service type for each type of task). Il servizio master ha una coda di elaborazione con i comandi che devono essere eseguiti dai servizi secondari.The master has a processing queue that contains commands to be executed by secondaries. I servizi secondari eseguono le richieste in ingresso e restituiscono segnali di conferma.The secondaries execute the incoming requests and send back acknowledgement signals. Una condizione che è possibile monitorare è la lunghezza della coda di elaborazione del servizio master.One condition that could be monitored is the length of the master processing queue. Se la lunghezza della coda master raggiunge una soglia, viene generato un avviso.If the master queue length reaches a threshold, a warning is reported. L'avviso indica che i servizi secondari non possono gestire il carico.The warning indicates that the secondaries can't handle the load. Se la coda raggiunge la lunghezza massima e i comandi vengono eliminati, viene generato un errore perché il servizio non può essere ripristinato.If the queue reaches the maximum length and commands are dropped, an error is reported, as the service can't recover. I report possono riguardare la proprietà QueueStatus.The reports can be on the property QueueStatus. Il watchdog si trova all'interno del servizio e viene inviato periodicamente alla replica primaria del servizio master.The watchdog lives inside the service, and it's sent periodically on the master primary replica. La durata (TTL) è di 2 minuti e l'invio avviene periodicamente ogni 30 secondi.The time to live is two minutes, and it's sent periodically every 30 seconds. Se il servizio primario diventa inattivo, il report viene eliminato automaticamente dall'archivio.If the primary goes down, the report is cleaned up automatically from store. Se la replica del servizio è attiva ma presenta un deadlock o altri problemi, il report scade nell'archivio integrità.If the service replica is up, but it is deadlocked or having other issues, the report expires in the health store. In questo caso, l'entità viene considerata in stato di errore.In this case, the entity is evaluated at error.

Un'altra condizione che può essere monitorata è il tempo di esecuzione delle attività.Another condition that can be monitored is task execution time. Il servizio master distribuisce le attività ai server secondari in base al tipo di attività.The master distributes tasks to the secondaries based on the task type. A seconda della progettazione, il servizio master può eseguire il polling dei servizi secondari per quanto riguarda lo stato delle attività.Depending on the design, the master could poll the secondaries for task status. Può anche attendere che i servizi secondari inviino segnali di conferma al termine dell'operazione.It could also wait for secondaries to send back acknowledgement signals when they are done. Nel secondo caso, è necessario prestare attenzione a individuare le situazioni in cui i servizi secondari vengono interrotti o i messaggi vengono persi.In the second case, care must be taken to detect situations where secondaries die or messages are lost. Un'opzione consiste nell'invio di una richiesta ping da parte del master allo stesso servizio secondario, che restituisce lo stato.One option is for the master to send a ping request to the same secondary, which sends back its status. Se non riceve alcuno stato, il master lo considera un errore e ripianifica l'attività.If no status is received, the master considers it a failure and reschedules the task. Questo comportamento presuppone che le attività siano idempotenti.This behavior assumes that the tasks are idempotent.

La condizione monitorata può essere riportata come avviso se l'attività non viene eseguita entro un certo periodo di tempo t1, ad esempio, 10 minuti.The monitored condition can be translated as a warning if the task is not done in a certain time (t1, for example 10 minutes). La condizione monitorata può essere riportata come errore se l'attività non viene completata entro il periodo di tempo t2, ad esempio, 20 minuti.If the task is not completed in time (t2, for example 20 minutes), the monitored condition can be translated as Error. Questo tipo di report può essere creato in diversi modi:This reporting can be done in multiple ways:

  • La replica primaria del servizio master genera periodicamente report su se stessa.The master primary replica reports on itself periodically. È possibile configurare una proprietà per tutte le attività in sospeso nella coda.You can have one property for all pending tasks in the queue. Se almeno una delle attività richiede più tempo, lo stato del report sulla proprietà PendingTasks è un avviso o errore, secondo il caso.If at least one task takes longer, the report status on the property PendingTasks is a warning or error, as appropriate. Se non sono presenti attività in sospeso o è stata avviata l'esecuzione di tutte le attività, viene segnalato uno stato integro.If there are no pending tasks or all tasks started execution, the report status is OK. Le attività sono persistenti.The tasks are persistent. Se il servizio primario si arresta, il nuovo servizio alzato di livello al ruolo di primario può continuare a generare report correttamente.If the primary goes down, the newly promoted primary can continue to report properly.
  • Un altro processo di watchdog, nel cloud o esterno, verifica le attività dall'esterno, in base al risultato desiderato per l'attività, per controllare se sono state completate.Another watchdog process (in the cloud or external) checks the tasks (from outside, based on the desired task result) to see if they are completed. Se non rispettano le soglie, viene inviato un report sul servizio master.If they do not respect the thresholds, a report is sent on the master service. Viene inviato anche un report per ogni attività che include l'identificatore dell'attività, ad esempio PendingTask+taskId.A report is also sent on each task that includes the task identifier, like PendingTask+taskId. I report dovranno essere inviati solo sugli stati non integri.Reports should be sent only on unhealthy states. Impostare la durata (TTL) su alcuni minuti e contrassegnare i report da rimuovere alla scadenza, per garantire la pulizia.Set time to live to a few minutes, and mark the reports to be removed when they expire to ensure cleanup.
  • Il servizio secondario che esegue un'attività segnala quando l'esecuzione richiede più tempo del previsto.The secondary that is executing a task reports when it takes longer than expected to run it. La segnalazione riguarda l'istanza del servizio della proprietà PendingTasks.It reports on the service instance on the property PendingTasks. Il report individua l'istanza del servizio che presenta problemi, ma allo scadere dell'istanza non consente di valutare la situazione,The report pinpoints the service instance that has issues, but it doesn't capture the situation where the instance dies. perché i report vengono eliminati.The reports are cleaned up then. È possibile creare report sul servizio secondario.It could report on the secondary service. Se l'attività viene completata, l'istanza del servizio secondario elimina il report dall'archivio.If the secondary completes the task, the secondary instance clears the report from the store. Il report non permette di valutare la situazione se il messaggio di acknowledgement viene perso e l'attività non viene completata dal punto di vista del master.The report doesn't capture the situation where the acknowledgement message is lost and the task is not finished from the master's point of view.

Se però la creazione di report viene eseguita nei casi descritti sopra, i report vengono acquisiti nell'integrità dell'applicazione quando questa viene valutata.However the reporting is done in the cases described above, the reports are captured in application health when health is evaluated.

Report periodici e report in caso di transizione a confrontoReport periodically vs. on transition

Usando il modello di report sull'integrità, i watchdog possono inviare report periodicamente o in caso di transizioni.By using the health reporting model, watchdogs can send reports periodically or on transitions. Nel caso dei report watchdog, è consigliabile inviarli periodicamente, perché il codice è molto più semplice e meno soggetto a errori.The recommended way for watchdog reporting is periodically, because the code is much simpler and less prone to errors. I watchdog devono essere più semplici possibile per evitare bug che generano report non corretti.The watchdogs must strive to be as simple as possible to avoid bugs that trigger incorrect reports. Eventuali report che segnalano erroneamente la mancata integrità influiscono sulla valutazione dell'integrità e sugli scenari basati sull'integrità, inclusi gli aggiornamenti.Incorrect unhealthy reports impact health evaluations and scenarios based on health, including upgrades. I report che segnalano erroneamente la mancata integrità hanno l'effetto di nascondere problemi del cluster ed è quindi opportuno evitare che vengano generati.Incorrect healthy reports hide issues in the cluster, which is not desired.

Per i report periodici, il watchdog può essere implementato con un timer.For periodic reporting, the watchdog can be implemented with a timer. In caso di callback del timer, il watchdog può controllare lo stato e inviare un report in base allo stato corrente.On a timer callback, the watchdog can check the state and send a report based on the current state. Non è necessario visualizzare il report inviato in precedenza o eseguire ottimizzazioni in termini di messaggistica.There is no need to see which report was sent previously or make any optimizations in terms of messaging. Ai fini delle prestazioni, il client di integrità è dotato di logica per l'invio in batch.The health client has batching logic to help with performance. Finché il client di integrità viene mantenuto attivo, esegue nuovi tentativi internamente finché il report non riceve un acknowledgement dall'archivio integrità o il watchdog genera un report più recente con entità, proprietà e origine identiche.While the health client is kept alive, it retries internally until the report is acknowledged by the health store or the watchdog generates a newer report with the same entity, property, and source.

La creazione di report in caso di transizioni richiede una gestione attenta dello stato.Reporting on transitions requires careful handling of state. Il watchdog esegue il monitoraggio di alcune condizioni e segnala soltanto eventuali modifiche di tali condizioni.The watchdog monitors some conditions and reports only when the conditions change. Il lato positivo di questo approccio è che sono necessari meno report.The upside of this approach is that fewer reports are needed. Il lato negativo è che la logica del watchdog è complessa.The downside is that the logic of the watchdog is complex. È necessario che il watchdog mantenga le condizioni o i report per poterli esaminare e determinare i cambiamenti di stato.The watchdog must maintain the conditions or the reports, so that they can be inspected to determine state changes. In caso di failover, fare attenzione ai report aggiunti, ma non ancora inviati all'archivio integrità.On failover, care must be taken with reports added, but not yet sent to the health store. Il numero di sequenza deve essere crescente.The sequence number must be ever-increasing. In caso contrario, i report verranno rifiutati come non aggiornati.If not, the reports are rejected as stale. Nei rari casi in cui si verifica una perdita di dati, potrebbe essere necessaria la sincronizzazione tra lo stato del reporter e quello dell'archivio integrità.In the rare cases where data loss is incurred, synchronization may be needed between the state of the reporter and the state of the health store.

La creazione di report relativi alle transizioni risulta utile per i servizi che inviano report relativi a se stessi, tramite Partition o CodePackageActivationContext.Reporting on transitions makes sense for services reporting on themselves, through Partition or CodePackageActivationContext. Quando viene rimosso l'oggetto locale, ovvero una replica o un pacchetto del servizio distribuito oppure un'applicazione distribuita, vengono rimossi anche tutti i rispettivi report.When the local object (replica or deployed service package / deployed application) is removed, all its reports are also removed. Grazie a questa pulizia automatica, non è strettamente necessario eseguire la sincronizzazione tra il generatore di report e l'archivio integrità.This automatic cleanup relaxes the need for synchronization between reporter and health store. Se il report è relativo a una partizione o un'applicazione padre, è necessario prestare attenzione in caso di failover, in modo da evitare report obsoleti nell'archivio integrità.If the report is for parent partition or parent application, care must be taken on failover to avoid stale reports in the health store. Occorre aggiungere la logica per mantenere lo stato corretto e cancellare il report dall'archivio quando non è più necessario.Logic must be added to maintain the correct state and clear the report from store when not needed anymore.

Implementare report sull'integritàImplement health reporting

Dopo aver definito l'entità e i dettagli del report, l'invio dei report sull'integrità può essere eseguito tramite API, PowerShell o REST.Once the entity and report details are clear, sending health reports can be done through the API, PowerShell, or REST.

APIAPI

Per usare un'API, è necessario creare un report sull'integrità specifico per il tipo di entità desiderato.To report through the API, you need to create a health report specific to the entity type they want to report on. Assegnare il report a un client di integrità.Give the report to a health client. In alternativa, creare informazioni sull'integrità e passarle ai metodi di creazione report corretti in Partition o CodePackageActivationContext per generare report sulle entità correnti.Alternatively, create a health information and pass it to correct reporting methods on Partition or CodePackageActivationContext to report on current entities.

L'esempio seguente illustra la generazione periodica di report da un watchdog all'interno del cluster.The following example shows periodic reporting from a watchdog within the cluster. I controlli del watchdog determinano se è possibile accedere a una risorsa esterna dall'interno di un nodo.The watchdog checks whether an external resource can be accessed from within a node. La risorsa è richiesta da un manifesto del servizio all'interno dell'applicazione.The resource is needed by a service manifest within the application. Se la risorsa non è disponibile, gli altri servizi all'interno dell'applicazione possono comunque funzionare correttamente.If the resource is unavailable, the other services within the application can still function properly. Il report viene quindi inviato per l'entità del pacchetto del servizio distribuito ogni 30 secondi.Therefore, the report is sent on the deployed service package entity every 30 seconds.

private static Uri ApplicationName = new Uri("fabric:/WordCount");
private static string ServiceManifestName = "WordCount.Service";
private static string NodeName = FabricRuntime.GetNodeContext().NodeName;
private static Timer ReportTimer = new Timer(new TimerCallback(SendReport), null, 30 * 1000, 30 * 1000);
private static FabricClient Client = new FabricClient(new FabricClientSettings() { HealthReportSendInterval = TimeSpan.FromSeconds(0) });

public static void SendReport(object obj)
{
    // Test whether the resource can be accessed from the node
    HealthState healthState = this.TestConnectivityToExternalResource();

    // Send report on deployed service package, as the connectivity is needed by the specific service manifest
    // and can be different on different nodes
    var deployedServicePackageHealthReport = new DeployedServicePackageHealthReport(
        ApplicationName,
        ServiceManifestName,
        NodeName,
        new HealthInformation("ExternalSourceWatcher", "Connectivity", healthState));

    // TODO: handle exception. Code omitted for snippet brevity.
    // Possible exceptions: FabricException with error codes
    // FabricHealthStaleReport (non-retryable, the report is already queued on the health client),
    // FabricHealthMaxReportsReached (retryable; user should retry with exponential delay until the report is accepted).
    Client.HealthManager.ReportHealth(deployedServicePackageHealthReport);
}

PowerShellPowerShell

Inviare report sull'integrità con Send-ServiceFabricTipoEntitàHealthReport.Send health reports with Send-ServiceFabricEntityTypeHealthReport.

L'esempio seguente illustra la generazione di report periodica sui valori della CPU in un nodo.The following example shows periodic reporting on CPU values on a node. I report devono essere inviati ogni 30 secondi e hanno una durata (TTL) di 2 minuti.The reports should be sent every 30 seconds, and they have a time to live of two minutes. Se scadono, nel reporter sono presenti problemi e quindi il nodo viene considerato in stato di errore.If they expire, the reporter has issues, so the node is evaluated at error. Quando la CPU è oltre la soglia specificata, il report presenta uno stato di integrità di tipo avviso.When the CPU is above a threshold, the report has a health state of warning. Quando la CPU rimane oltre la soglia specificata per più di tempo di quello configurato, verrà segnalato come errore.When the CPU remains above a threshold for more than the configured time, it's reported as an error. In caso contrario, il reporter invia uno stato di integrità corretto.Otherwise, the reporter sends a health state of OK.

PS C:\> Send-ServiceFabricNodeHealthReport -NodeName Node.1 -HealthState Warning -SourceId PowershellWatcher -HealthProperty CPU -Description "CPU is above 80% threshold" -TimeToLiveSec 120

PS C:\> Get-ServiceFabricNodeHealth -NodeName Node.1
NodeName              : Node.1
AggregatedHealthState : Warning
UnhealthyEvaluations  :
                        Unhealthy event: SourceId='PowershellWatcher', Property='CPU', HealthState='Warning', ConsiderWarningAsError=false.

HealthEvents          :
                        SourceId              : System.FM
                        Property              : State
                        HealthState           : Ok
                        SequenceNumber        : 5
                        SentAt                : 4/21/2015 8:01:17 AM
                        ReceivedAt            : 4/21/2015 8:02:12 AM
                        TTL                   : Infinite
                        Description           : Fabric node is up.
                        RemoveWhenExpired     : False
                        IsExpired             : False
                        Transitions           : ->Ok = 4/21/2015 8:02:12 AM

                        SourceId              : PowershellWatcher
                        Property              : CPU
                        HealthState           : Warning
                        SequenceNumber        : 130741236814913394
                        SentAt                : 4/21/2015 9:01:21 PM
                        ReceivedAt            : 4/21/2015 9:01:21 PM
                        TTL                   : 00:02:00
                        Description           : CPU is above 80% threshold
                        RemoveWhenExpired     : False
                        IsExpired             : False
                        Transitions           : ->Warning = 4/21/2015 9:01:21 PM

L'esempio seguente segnala un avviso temporaneo in una replica.The following example reports a transient warning on a replica. Ottiene prima di tutto l'ID della partizione e quindi all'ID della replica per il servizio interessato.It first gets the partition ID and then the replica ID for the service it is interested in. Invia quindi un report da PowershellWatcher sulla proprietà ResourceDependency.It then sends a report from PowershellWatcher on the property ResourceDependency. Il report è valido solo per due minuti e viene rimosso automaticamente dall'archivio.The report is of interest for only two minutes, and it is removed from the store automatically.

PS C:\> $partitionId = (Get-ServiceFabricPartition -ServiceName fabric:/WordCount/WordCount.Service).PartitionId

PS C:\> $replicaId = (Get-ServiceFabricReplica -PartitionId $partitionId | where {$_.ReplicaRole -eq "Primary"}).ReplicaId

PS C:\> Send-ServiceFabricReplicaHealthReport -PartitionId $partitionId -ReplicaId $replicaId -HealthState Warning -SourceId PowershellWatcher -HealthProperty ResourceDependency -Description "The external resource that the primary is using has been rebooted at 4/21/2015 9:01:21 PM. Expect processing delays for a few minutes." -TimeToLiveSec 120 -RemoveWhenExpired

PS C:\> Get-ServiceFabricReplicaHealth  -PartitionId $partitionId -ReplicaOrInstanceId $replicaId


PartitionId           : 8f82daff-eb68-4fd9-b631-7a37629e08c0
ReplicaId             : 130740415594605869
AggregatedHealthState : Warning
UnhealthyEvaluations  :
                        Unhealthy event: SourceId='PowershellWatcher', Property='ResourceDependency', HealthState='Warning', ConsiderWarningAsError=false.

HealthEvents          :
                        SourceId              : System.RA
                        Property              : State
                        HealthState           : Ok
                        SequenceNumber        : 130740768777734943
                        SentAt                : 4/21/2015 8:01:17 AM
                        ReceivedAt            : 4/21/2015 8:02:12 AM
                        TTL                   : Infinite
                        Description           : Replica has been created.
                        RemoveWhenExpired     : False
                        IsExpired             : False
                        Transitions           : ->Ok = 4/21/2015 8:02:12 AM

                        SourceId              : PowershellWatcher
                        Property              : ResourceDependency
                        HealthState           : Warning
                        SequenceNumber        : 130741243777723555
                        SentAt                : 4/21/2015 9:12:57 PM
                        ReceivedAt            : 4/21/2015 9:12:57 PM
                        TTL                   : 00:02:00
                        Description           : The external resource that the primary is using has been rebooted at 4/21/2015 9:01:21 PM. Expect processing delays for a few minutes.
                        RemoveWhenExpired     : True
                        IsExpired             : False
                        Transitions           : ->Warning = 4/21/2015 9:12:32 PM

RESTREST

Inviare report sull'integrità usando REST con richieste POST indirizzate all'entità desiderata e contenenti nel corpo la descrizione del report sull'integrità.Send health reports using REST with POST requests that go to the desired entity and have in the body the health report description. Vedere ad esempio come inviare report sull'integrità di un cluster o report sull'integrità di un servizio con REST.For example, see how to send REST cluster health reports or service health reports. Sono supportate tutte le entità.All entities are supported.

Passaggi successiviNext steps

In base ai dati sull'integrità, gli sviluppatori del servizio e gli amministratori di cluster e applicazioni possono valutare come usare le informazioni.Based on the health data, service writers and cluster/application administrators can think of ways to consume the information. Ad esempio, è possibile impostare avvisi in base allo stato integrità per rilevare problemi gravi prima che provochino interruzioni.For example, they can set up alerts based on health status to catch severe issues before they provoke outages. Gli amministratori possono anche configurare sistemi di ripristino per risolvere i problemi automaticamente.Administrators can also set up repair systems to fix issues automatically.

Introduzione al monitoraggio dell'integrità di Service FabricIntroduction to Service Fabric health Monitoring

Come visualizzare i report sull'integrità di Service FabricView Service Fabric health reports

Creare report e verificare l'integrità dei serviziHow to report and check service health

Uso dei report sull'integrità del sistema per la risoluzione dei problemiUse system health reports for troubleshooting

Monitorare e diagnosticare servizi in localeMonitor and diagnose services locally

Aggiornamento di un'applicazione di infrastruttura di serviziService Fabric application upgrade