Monitorare i messaggi

Questa guida descrive come monitorare i messaggi inviati a Manufacturing Data Engine (MDE), come scorrono nella pipeline di elaborazione e come diagnosticare eventuali problemi che potrebbero verificarsi a causa di problemi di configurazione o di sistema potenziali.

Per monitorare i messaggi che passano attraverso MDE, devi utilizzare la tabella BigQuery operations-log. Ogni volta che un passaggio della pipeline MDE non riesce a elaborare un messaggio, lo invia alla tabella operations-log indicando il passaggio e il motivo dell'errore.

Tutti i messaggi non riusciti vengono scritti in questa tabella, ma puoi configurare MDE in modo che scriva anche i messaggi riusciti nella tabella operations-log. Questa opzione è utile per il debug dei problemi, ma non deve essere lasciata attiva perché può generare molto traffico aggiuntivo nel sistema e potrebbe ridurre le prestazioni in produzione.

REST

Esegui la seguente richiesta API REST per configurare la tabella operations-log:

POST /configuration/v1/environment

{
  "operationsLogLevel": "ALL"
}

Dove:

  • ALL: tutti i messaggi verranno inviati alla tabella operations-log per ogni passaggio della pipeline di elaborazione.
  • ERROR: solo i messaggi per cui uno dei passaggi di elaborazione non è andato a buon fine verranno inviati alla tabella operations-log.

Passaggi di elaborazione

Per diagnosticare il motivo per cui un messaggio viene rifiutato durante l'elaborazione della pipeline, è utile conoscere i diversi passaggi di elaborazione e capire cosa fanno. Per saperne di più, consulta Architettura di MDE.

  1. message-mapper: legge il file JSON originale, lo associa alla message-class corrispondente e lo elabora utilizzando Whistle per generare uno o più record.
  2. configuration-manager: crea un nuovo tag nel sistema se non esiste già e aggiunge al record tutte le proprietà definite nel tipo appropriato (bucket di metadati, sink e trasformazioni).
  3. metadata-manager: risolve tutti i riferimenti ai metadati di questo record, aggiorna le istanze dei metadati di sistema se ne viene ricevuta una nuova, aggiunge i metadati materializzati al record se è configurato per farlo.
  4. bigquery-sink: mappa il record alla struttura di tipo appropriata e lo invia all'argomento Pub/Sub corrispondente da scrivere in BigQuery.
  5. pubsub-sink: esegue il mapping del record alla struttura Proto o JSON di Pub/Sub e lo invia all'argomento corrispondente.
  6. GCSWriter: scrive sia i dati non elaborati ricevuti dall'argomento input-messages sia i dati elaborati dopo essere passati attraverso metadata-manager.
  7. BigtableWriter: scrive i dati in Bigtable.
  8. GCSReader: legge i file da Cloud Storage e invia i messaggi a input-messages.

Eseguire la diagnostica dei messaggi che non vengono visualizzati nel sink configurato

Se invii un messaggio a MDE e non si trova nel sink configurato, verifica innanzitutto che il tipo abbia configurato correttamente il sink (come spiegato nella sezione Tipo) e che tu stia eseguendo query sulla tabella corretta in BigQuery. Ricorda che la tabella prende il nome dal tipo.

Se la configurazione è corretta, devi utilizzare la tabella operations-log per diagnosticare il problema. Puoi iniziare con una query generale, ordinando per event_timestamp o filtrandola in base alla data di invio del messaggio, come mostrato nell'esempio seguente:

SELECT
  *
FROM
  `mde_system.operations-log`
WHERE
  DATE(event_timestamp) = CURRENT_DATE()
ORDER BY
  event_timestamp desc
LIMIT 100;

Puoi anche utilizzare source_message_id per filtrare un messaggio specifico. Questo ID viene assegnato da Pub/Sub durante la pubblicazione di un messaggio. Se utilizzi gcloud CLI per pubblicare un messaggio dalla riga di comando, verrà restituito l'messageId del messaggio pubblicato.

SELECT
  *
FROM
  `mde_system.operations-log`
WHERE
  DATE(event_timestamp) <= CURRENT_DATE()
  AND source_message_id = 'PubSubMessageId';

Se non riesci a trovare il messaggio o ce ne sono troppi, puoi filtrare in base a un attributo del messaggio originale. Il messaggio viene sempre registrato nel campo payload con lo stato in cui si trovava l'ultimo passaggio e viene salvato in un campo JSON, in modo che sia più facile utilizzare TO_JSON_STRING e % per cercare i messaggi che contengono il testo che ti interessa.

SELECT
  *
FROM
  `mde_system.operations-log`
WHERE
  DATE(event_timestamp) = CURRENT_DATE()
  AND TO_JSON_STRING(payload) LIKE "%TEXT-TO-FIND%"
ORDER BY
  event_timestamp DESC;

Una volta trovato il messaggio nella tabella operations-log, controlla la colonna error-message per trovare il motivo del rifiuto. Gli errori più comuni sono i seguenti:

  • Impossibile trovare una corrispondenza tra il messaggio in arrivo e una delle classi di messaggi registrate in Configuration Manager.
  • Nessun parser trovato per la classe di messaggi <MESSAGE_CLASS_NAME>.
  • Elaborazione del messaggio ignorata perché non è stato possibile deserializzarlo (il messaggio non è un JSON valido).
  • Impossibile creare un messaggio valido con il parser <PARSER_NAME>. Il messaggio non contiene il campo timestamp.
  • Impossibile creare un messaggio valido con il parser <PARSER_NAME>. Il messaggio non contiene il campo tagName o è vuoto.
  • Impossibile creare un messaggio valido con il parser <PARSER_NAME>. Il timestamp del messaggio non rientra nei limiti supportati.

Dopo aver trovato e corretto l'errore che causa il mancato invio del messaggio, i messaggi inizieranno ad arrivare nelle rispettive destinazioni.