Skip to content

Commit

Permalink
fixed readme, migliorata struttura
Browse files Browse the repository at this point in the history
  • Loading branch information
@Andrea-Cavallo
Andrea-Cavallo committed Aug 17, 2024
1 parent df5d746 commit 5df3db3
Show file tree
Hide file tree
Showing 10 changed files with 675 additions and 336 deletions.
288 changes: 218 additions & 70 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,91 +1,155 @@
# Super cool Go con GRPC

<img src="./extra/img/GRPC.png" height="800" width="600">

# Real-Time Temperature Monitoring with Go and gRPC

## Introduzione

Questo progetto dimostra l'integrazione di servizi gRPC con il linguaggio Go,
fornendo un esempio completo di un server gRPC che serve dati di temperatura e un client gRPC che li consuma,
il tutto con una gestione avanzata delle metriche, connessione a MongoDB per persistere i dati, funzionalità di allerta tramite Twilio.
Il progetto utilizza Docker per facilitare l'impostazione dell'ambiente, inclusi la configurazione di MongoDB e altre dipendenze tipo jaeger.

<img src="./extra/img/GRPC.png" height="800" width="600">

[Click here for the English version](#english-version)

# Struttura del progetto


```text
├── api --> qua dentro il file .proto
│ ├── protos
│ │ ├── temperature.proto
│ ├── api.md
├── docker ---> tutto cio' relativo a docker
│ ├── docker-compose.yml
│ ├── init-mongo.js
│ ├── loki-config.yml
│ ├── otel-collector-config.yaml
│ ├── prometheus.yml
├── extra --> immagini del progetto
├── pkg --> pkg tutto quello che deve essere visibile e condiviso
│ ├── telemetry
│ ├── temperature
├── temperature_grpc_client -> il Client GRPC
│ ├── cmd
│ ├── plot
│ ├── service
│ ├── client.md
├── temperature_grpc_server --> il Server GRPC
│ ├── alert_twilio
│ │ ├── alert.go
│ ├── cmd
│ │ ├── server
│ │ │ ├── main.go
│ ├── mongodb --> connessione a MONGODB
│ │ ├── config
│ │ ├── temperature_repo
│ ├── service
│ │ ├── server.go
│ ├── server.md
├── .editorconfig
├── .gitignore
├── changelog.md
├── go.mod
├── go.sum
```

## Esecuzione del Progetto
# Esecuzione del Progetto

### 1. Prerequisiti
## 1. Prerequisiti

Prima di eseguire il progetto, è necessario ottenere una chiave API per utilizzare il servizio WeatherAPI. Questo servizio è completamente gratuito, e puoi ottenere la tua chiave API seguendo questi passi:
Prima di eseguire il progetto, è necessario ottenere una chiave API per utilizzare il servizio WeatherAPI. Questo servizio è completamente gratuito e puoi ottenere la tua chiave API seguendo questi passi:

1. Visita il sito [WeatherAPI](https://www.weatherapi.com/).
2. Registrati e segui le istruzioni per ottenere la tua chiave API.
3. Una volta ottenuta, salva la chiave API in un luogo sicuro.

### 2. Configurare l'API Key come Variabile d'Ambiente
## 2. Configurare l'API Key come Variabile d'Ambiente

Per mantenere la tua chiave API sicura e fuori dal codice sorgente, configurala come una variabile d'ambiente. Segui questi passi:

#### Su Linux/MacOS:
### Su Linux/MacOS:

```bash
export WEATHER_API_KEY=la-tua-api-key
```

#### Su Windows (nel terminale PowerShell):
### Su Windows (nel terminale PowerShell):

```powershell
$env:WEATHER_API_KEY="la-tua-api-key"
```

Assicurati che la variabile d'ambiente `WEATHER_API_KEY` sia impostata correttamente prima di procedere.

### 3. Build del docker-compose.yml
## 3. Build del Docker Compose

Assicurati di avere Docker installato e di avere accesso al file `docker-compose.yml`:

- Assicurarsi di ditar su docker
- docker/docker-compose.yml
- Posizionati nella directory che contiene `docker-compose.yml`

## 4. Opzionale - Configurazione di Twilio

### 4. Opzionale
Se desideri inviare avvisi tramite Twilio, segui i seguenti passi per creare un account su Twilio e configurare le variabili d'ambiente:

Consulta: [Twilio WhatsApp Quickstart (Go)](https://www.twilio.com/docs/whatsapp/quickstart/go)

Configurare le seguenti variabili d'ambiente:

```bash
export TWILIO_ACCOUNT_SID=il-tuo-account-sid
export TWILIO_AUTH_TOKEN=il-tuo-auth-token
export TWILIO_PHONE_NUMBER=il-tuo-numero-di-telefono
export ALERT_PHONE_NUMBER=il-numero-di-telefono-per-gli-avvisi
```

### 3. Eseguire il Server
## 5. Eseguire il Server

Una volta configurata la chiave API, puoi avviare il server:

1. Naviga alla directory `temperature_grpc_server`:

```bash
cd temperature_grpc_server/cmd/server
```
```bash
cd temperature_grpc_server/cmd/server
```

2. Esegui il server:

```bash
go run main.go
```
```bash
go run main.go
```

Il server inizierà ad ascoltare le richieste gRPC.
Il server inizierà ad ascoltare le richieste gRPC.

### 4. Eseguire il Client
## 6. Eseguire il Client

Con il server in esecuzione, ora puoi avviare il client per inviare richieste al server:

1. Apri un nuovo terminale e naviga alla directory `temperature_grpc_client`:

```bash
cd temperature_grpc_client/cmd/client
```
```bash
cd temperature_grpc_client/cmd/client
```

2. Esegui il client:

```bash
go run main.go
```
```bash
go run main.go
```

Il client invierà una richiesta gRPC al server e riceverà una risposta con i dati di temperatura.
Il client invierà una richiesta gRPC al server e riceverà una risposta con i dati di temperatura.

## Grafico della Temperatura

Ogni volta che arresti l'applicazione, in particolare il client, vedrai disegnato un grafico che mostrerà la variazione della temperatura.
![Grafico della Temperatura](./temp_graph.png)
## Per il dettaglio del client e del server
- temperature_grpc_client/client.md
- temperature_grpc_server/server.md

## Approfondimenti sulla tecnologia scelta:


## Approfondimenti sulla tecnologia scelta
gRPC può essere considerato un successore di RPC, ed è leggero in termini di peso. Google lo ha sviluppato per la comunicazione tra microservizi e altri sistemi che necessitano di interagire. Ci sono diversi vantaggi nell'usare gRPC.

Expand All @@ -104,55 +168,139 @@ Oltre ai vantaggi chiave menzionati sopra, gRPC promuove un design migliore per
gRPC è circa sette volte più veloce di REST nel ricevere dati e circa dieci volte più veloce di REST nel trasmettere dati per un payload specifico. Questo è principalmente dovuto al pacchettamento compatto dei Protocol Buffers e all'uso di HTTP/2 da parte di gRPC.
## Tipi di RPC
gRPC supporta quattro tipi di metodi di servizio:
## Autore
1. **RPC Unario**: il client invia una singola richiesta e ottiene una singola risposta, come una chiamata a funzione normale.
```protobuf
rpc SayHello(HelloRequest) returns (HelloResponse);
```
Progetto sviluppato da [Andrea Cavallo].
2. **RPC con Streaming Server**: il client invia una richiesta e riceve un flusso di risposte.
```protobuf
rpc LotsOfReplies(HelloRequest) returns (stream HelloResponse);
```
## Licenza
Questo progetto è distribuito sotto la licenza Apache 2.0. Vedi il file LICENSE per ulteriori dettagli.
3. **RPC con Streaming Client**: il client invia un flusso di richieste e riceve una singola risposta.
```protobuf
rpc LotsOfGreetings(stream HelloRequest) returns (HelloResponse);
# English Version
# Super cool Go with GRPC
<img src="./extra/img/GRPC.png" height="800" width="600">
# Project Execution
## 1. Prerequisites
Before running the project, you need to obtain an API key to use the WeatherAPI service. This service is completely free, and you can get your API key by following these steps:
1. Visit the [WeatherAPI](https://www.weatherapi.com/) website.
2. Sign up and follow the instructions to get your API key.
3. Once obtained, save the API key in a safe place.
## 2. Configure the API Key as an Environment Variable
To keep your API key secure and out of the source code, configure it as an environment variable. Follow these steps:
### On Linux/MacOS:
```bash
export WEATHER_API_KEY=your-api-key
```
4. **RPC con Streaming Bidirezionale**: entrambe le parti inviano flussi di messaggi.
```protobuf
rpc BidiHello(stream HelloRequest) returns (stream HelloResponse);
### On Windows (in PowerShell):
```powershell
$env:WEATHER_API_KEY="your-api-key"
```
## Utilizzo dell'API
### Lato Server
Il server implementa i metodi dichiarati dal servizio e gestisce le chiamate client utilizzando un server gRPC. La struttura gRPC decodifica le richieste in arrivo, esegue i metodi di servizio e codifica le risposte.
Ensure the `WEATHER_API_KEY` environment variable is set correctly before proceeding.
## 3. Docker Compose Build
### Lato Client
Il client utilizza un oggetto locale noto come "stub" che implementa gli stessi metodi del servizio. Chiamando questi metodi, i parametri vengono invocati nel tipo di messaggio specificato dal protocol buffer e inviati al server, che a sua volta risponde con i messaggi corrispondenti.
Ensure you have Docker installed and access to the `docker-compose.yml` file:
## Sincrono vs Asincrono
Le chiamate RPC sincrone bloccano fino all'arrivo della risposta. Tuttavia, molte situazioni richiedono l'avvio di RPC senza bloccare il thread corrente. gRPC fornisce API sia sincrone che asincrone.
- Navigate to the directory that contains `docker-compose.yml`.
## Deadline/Timeout
gRPC consente ai client di specificare quanto tempo sono disposti ad attendere una risposta, dopo di che l'RPC viene terminato con un errore DEADLINE_EXCEEDED. Il server può verificare se l'RPC è scaduto.
## 4. Optional - Twilio Configuration
## Terminazione e Cancellazione di un RPC
Client e server determinano localmente il successo di una chiamata, che potrebbe non corrispondere. Entrambe le parti possono annullare una chiamata RPC in qualsiasi momento.
If you wish to send alerts via Twilio, follow these steps to create a Twilio account and set up the environment variables:
## Metadata
La metadata sono informazioni su una chiamata RPC sotto forma di coppie chiave-valore. gRPC consente la gestione di metadata definiti dall'utente senza influenzare il funzionamento di base.
Consult: [Twilio WhatsApp Quickstart (Go)](https://www.twilio.com/docs/whatsapp/quickstart/go)
## Canali
Un canale gRPC fornisce una connessione a un server gRPC su un host e una porta specificati. Viene utilizzato per creare un client stub. I client possono specificare argomenti del canale per modificare il comportamento predefinito.
Set the following environment variables:
Ad esempio:
```go
conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
```bash
export TWILIO_ACCOUNT_SID=your-account-sid
export TWILIO_AUTH_TOKEN=your-auth-token
export TWILIO_PHONE_NUMBER=your-phone-number
export ALERT_PHONE_NUMBER=alert-phone-number
```
https://signoz.io/blog/opentelemetry-grpc-golang/
## 5. Running the Server
Once the API key is configured, you can start the server:
1. Navigate to the `temperature_grpc_server` directory:
```bash
cd temperature_grpc_server/cmd/server
```
2. Start the server:
```bash
go run main.go
```
The server will start listening for gRPC requests.
## 6. Running the Client
With the server running, you can now start the client to send requests to the server:
1. Open a new terminal and navigate to the `temperature_grpc_client` directory:
```bash
cd temperature_grpc_client/cmd/client
```
2. Start the client:
```bash
go run main.go
```
The client will send a gRPC request to the server and receive a response with the temperature data.
## Temperature Graph
Whenever you shut down the application, especially the client, you will see a graph showing the temperature variation.
![Temperature Graph](./temp_graph.png)
## Detailed Client and Server Documentation
- temperature_grpc_client/client.md
- temperature_grpc_server/server.md
## Insights into the Chosen Technology
gRPC can be considered a successor to RPC and is lightweight. Google developed it for communication between microservices and other systems that need to interact. There are several advantages to using gRPC.
## Advantages of gRPC
- **Uses Protocol Buffers (Protobuf)** instead of JSON.
- **Built on HTTP/2** instead of HTTP 1.1.
- **Built-in Code Generation**.
- **High Performance**.
- **SSL Security**.
In addition to the key advantages mentioned above, gRPC promotes better design for your application. gRPC is API-oriented, unlike REST, which is resource-oriented. It is also asynchronous by default, meaning it does not block the thread on request and can serve millions of requests in parallel, ensuring high scalability.
## Advantages of gRPC over REST
gRPC is about seven times faster than REST in receiving data and about ten times faster than REST in transmitting data for a specific payload. This is primarily due to the compact packing of Protocol Buffers and the use of HTTP/2 by gRPC.
## Author
Andrea Cavallo
Project developed by [Andrea Cavallo].
## License
This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.
27 changes: 27 additions & 0 deletions changelog.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Changelog

Tutte le modifiche rilevanti apportate a questo progetto saranno documentate in questo file.

## [1.0.0] - 2024-08-17

### Aggiunto
- Integrazione di gRPC per la comunicazione tra client e server con supporto per i quattro tipi di RPC: Unario, Streaming Server, Streaming Client, e Streaming Bidirezionale.
- Implementazione del servizio `TemperatureService` per ottenere i dati della temperatura attuale di una località specificata.
- Configurazione del server gRPC e del client gRPC per inviare e ricevere richieste gRPC.
- Supporto per la creazione di grafici della temperatura alla chiusura del client.
- Documentazione dettagliata per l'installazione e l'uso del progetto, inclusa la configurazione di chiavi API e variabili d'ambiente.
- Supporto per l'invio di avvisi tramite Twilio con configurazione opzionale.
- Docker Compose configurato con servizi per MongoDB, Jaeger, OpenTelemetry Collector, Prometheus, Grafana, Loki, Node Exporter, cAdvisor, e K6 per il test delle prestazioni.
- Integrazione con Prometheus per la raccolta delle metriche e Grafana per la visualizzazione delle stesse.
- Supporto per tracing distribuito con Jaeger tramite OpenTelemetry.

### Modificato
- Aggiornamento della documentazione per includere dettagli sull'uso di Grafana con credenziali predefinite (`admin/admin`).
- Miglioramento della configurazione Docker Compose per una maggiore stabilità e facilità di utilizzo.

### Risolto
- Problemi di connessione tra client e server gRPC ora risolti, garantendo un flusso di dati stabile e continuo.
- Risolto un problema con la mancata individuazione del file `.proto` da parte di K6 durante l'esecuzione dei test delle prestazioni.

### Rilascio Iniziale
- Rilascio iniziale del progetto con tutte le funzionalità di base per il monitoraggio delle temperature utilizzando gRPC e l'integrazione di strumenti di osservabilità.
Loading

0 comments on commit 5df3db3

Please sign in to comment.