Skip to content
This repository has been archived by the owner on Jul 21, 2023. It is now read-only.

Struttura Messaggi Interni

Jump to bottom
Alberto Schiabel edited this page May 16, 2019 · 2 revisions

Struttura messaggi interni

Descrizione

Il formato utilizzato per lo scambio di messaggi interni tra i microservizi di Butterfly collegati al broker Kafka è Apache Avro. Gli schemi Avro permettono di definire, usando la sintassi JSON, le strutture dati tipizzate inviate dai servizi di produzione e ricevute dai servizi di consumo. Per ogni schema Avro, a tempo di compilazione è generata una classe Java equivalente, che offre sia un modo pratico di creare una nuova istanza di tale classe (tramite Builder Pattern), sia metodi getter e setter per leggere e modificare ogni campo dato definito nello schema. Per un esempio pratico su come creare un oggetto Avro in Java, si rimanda alla relativa sezione Esempio reazione oggetto Avro in Java.

Avro supporta i più comuni tipi primitivi di dato, di cui quelli più utilizzati in Butterfly sono:

  • long: numero intero a 64 bit con segno;
  • string: sequenza di caratteri Unicode;
  • null: nessun valore

La definizione delle strutture dei messaggi scambiati si basa sul tipo complesso Record, che è analogo alla definizione di un oggetto JSON. Avro supporta inoltre le enumerazioni di tipi e alcune semplici collezioni di dati, come gli array, anch'essi utilizzati da Butterfly.

Per una documentazione più esaustiva sui tipi primitivi e complessi supportati da Avro, si rimanda al documento ufficiale della specifica di Apache Avro 1.8.1.

Esempio creazione oggetto Avro in Java

Lo schema Avro di riferimento di questo esempio è it.unipd.dstack.butterfly.producer.avro.Event.

import java.util.list;
import it.unipd.dstack.butterfly.producer.avro.Event;
import it.unipd.dstack.butterfly.producer.avro.Services;
import it.unipd.dstack.butterfly.producer.avro.ServiceEventTypes;

// ...
Event.Builder eventBuilder = Event.newBuilder();
eventBuilder.setTimestamp(1557325419);
eventBuilder.setService(Services.GITLAB);
eventBuilder.setProjectName(mergeRequestEvent.getProject().getName());
eventBuilder.setProjectURL(mergeRequestEvent.getProject().getWebUrl());
eventBuilder.setEventId("123");
eventBuilder.setEventType(ServiceEventTypes.GITLAB_ISSUE_CREATED);
eventBuilder.setUserEmail("[email protected]");
eventBuilder.setTitle("title");
eventBuilder.setDescription("description");
eventBuilder.setTags(List.of("Bug", "Fix"));
Event event = eventBuilder.build();

Schemi Avro più importanti

Di seguito è presentata la lista degli schemi Avro utilizzati da Butterfly per la propagazione dei messaggi relativi agli eventi di produzione dai producer ai consumer.

Services

Services è un tipo enumerabile Avro che definisce la lista dei servizi di produzione supportati da Butterfly. Il namespace completo di questo schema è it.unipd.dstack.butterfly.producer.avro.Services. I servizi supportati sono:

  • REDMINE;
  • GITLAB;
  • SONARQUBE.

ServiceEventTypes

ServiceEventTypes è un tipo enumerabile Avro che definisce la lista degli eventi supportati da Butterfly. Il namespace completo di questo schema è it.unipd.dstack.butterfly.producer.avro.ServiceEventTypes. Le tipologie di eventi supportati sono:

  • GITLAB_COMMIT_CREATED;
  • GITLAB_ISSUE_CREATED;
  • GITLAB_ISSUE_EDITED;
  • GITLAB_MERGE_REQUEST_CREATED;
  • GITLAB_MERGE_REQUEST_EDITED;
  • GITLAB_MERGE_REQUEST_MERGED;
  • GITLAB_MERGE_REQUEST_CLOSED;
  • REDMINE_TICKET_CREATED;
  • REDMINE_TICKET_EDITED;
  • SONARQUBE_PROJECT_ANALYSIS_COMPLETED.

Event

Event è una struttura Avro che contiene tutte le informazioni relative ad un evento prodotto da un sistema di produzione supportato da Butterfly. Il namespace completo di questo schema è it.unipd.dstack.butterfly.producer.avro.Event. Poiché gli eventi prodotti da GitLab hanno una struttura diversa rispetto a quelli prodotti da Redmine e da SonarQube, è necessario fattorizzarli, unificandone la struttura ed estraendone solo le informazioni di effettivo interesse e il cui significato sia comune a prescindere dal sistema di produzione originale. Event, infatti, funge da massimo comune denominatore tra le strutture degli eventi supportati. Solo una minima parte dei campi di Event è nullable. I campi dello schema Event sono i seguenti:

Nome Tipo Esempio Commento
timestamp long 1557325419 Timestamp relativo all'evento espresso in formato UNIX
service Services 'GITLAB' Nome del servizio di terze parti da cui proviene l'evento originale
projectName string 'Butterfly' Nome del progetto associato con l'evento corrente
projectURL `string null` 'http://dstack.gitlab.io/butterfly'
eventId string '123' ID dell'evento corrente
eventType ServiceEventTypes 'GITLAB_ISSUE_CREATED' Tipologia di evento associata all'evento corrente
userEmail `string null` '[email protected]'
title string 'New issue' Titolo riassuntivo dell'evento
description string 'Some new bugs to fix' Descrizione estesa dell'evento
tags string[] ['Bug'] Lista di etichette associate all'evento, per esempio estratte dalle issue di GitLab o dai tracker di Redmine

Contacts

Contacts è un tipo enumerabile Avro che definisce la lista delle piattaforme di contatto supportate da Butterfly. Il namespace completo di questo schema è it.unipd.dstack.butterfly.consumer.avro.Contacts. Le piattaforme di contatto supportate sono:

  • TELEGRAM;
  • EMAIL;
  • SLACK.

UserSingleContact

UserSingleContact è una struttura Avro che contiene una breve anagrafica dell'utente a cui inviare l'evento, la piattaforma di contatto scelta dall'utente per l'inoltro di un evento, e il riferimento di contatto per identificare univocamente il destinatario all'interno del sistema di contatto scelto. Nel caso in cui la piattaforma di contatto scelta dall'utente sia EMAIL, il riferimento di contatto è l'indirizzo email specificato dall'utente, che non è necessariamente lo stesso usato per registrarsi. Nel caso in cui la piattaforma di contatto scelta sia TELEGRAM, il riferimento di contatto è l'id della conversazione tra il Bot di Telegram di Butterfly e l'utente, impostato al momento della configurazione dell'account di contatto di Telegram. Infine, se la piattaforme di contatto scelta è SLACK, il riferimento di contatto è l'id dell'utente Slack che ha configurato l'account di contatto Butterfly per questa piattaforma. Il namespace completo di questo schema è it.unipd.dstack.butterfly.consumer.avro.UserSingleContact. I campi dello schema UserSingleContact sono i seguenti:

Nome Tipo Esempio Commento
firstname string 'Davide' Nome dell'utente che deve ricevere una notifica dell'evento corrente
lastname string 'Zanetti' Cognome dell'utente che deve ricevere una notifica dell'evento corrente
contact Contacts 'SLACK' Piattaforma di contatto scelta dall'utente destinatario per ricevere una notifica dell'evento corrente
contactRef string 'DUHV896A' Riferimento di contatto dell'utente destinatario per la piattaforma di contatto scelta

EventWithUserContact

EventWithUserContact è una struttura Avro che aggiunge le informazioni relative al destinatario del messaggio all'evento originale da inviare. Il namespace completo di questo schema è it.unipd.dstack.butterfly.consumer.avro.EventWithUserContact. EventWithUserContact è una composizione di altri due record Avro, event e userContact. I campi dello schema EventWithUserContact sono i seguenti:

Nome Tipo Esempio Commento
event Event {"timestamp": 1557325419, "service": "GITLAB", "projectName": "Butterfly", "projectURL": "http://dstack.gitlab.io/butterfly", "eventId": "123", "eventType": "GITLAB_ISSUE_CREATED", "userEmail": "[email protected]", "title": "New issue", "description": "Some new bugs to fix", "tags": ["Bug"]} Record che definisce una struttura uniformata per tutti gli eventi di produzione possibili, estraendo le informazioni più rilevanti dall'evento originale
userContact UserSingleContact {"firstname": "Davide", "lastname": "Zanetti", "contact": "SLACK", "contactRef": "DUHV896A" } Record che contiene le informazioni base dell'utente destinatario, la piattaforma di contatto scelta e un identificativo univoco di contatto
Clone this wiki locally