Observability seminar on MFF UK
This repository contains a template and an assignment for the practical part of the Observability seminar on MFF UK.
Following text is intended just for the purpose of the seminar and is written in the Czech language.
Předpoklady
Nutné
Pro splnění tohoto úkolu je potřeba mít nainstalované následující nástroje:
- Git
- Golang
v1.18
ssh
&scp
(nebo ekvivalent)curl
(nebo ekvivalent)
Volitelné
Pokud si budete chtít rozchodit projekt lokálně na svém počítači (doporučeno), je potřeba mít nainstalované následující backendy:
- Grafana 8.5.2
- Loki 2.4.2
- Prometheus 2.35.0
- Jaeger 1.33.0
Všechny pomocné skripty (startování backendů atd.) jsou napsány a odladěny pro UNIXové prostředí. V případě použití jiného operačního systému (Windows) je potřeba tyto skripty adaptovat (např. pro PowerShell).
Zadání
Předpoklad: vytvořené VM podle zadání v prezentaci od Ládi Dobiáše.
- Fork a
git clone
této repozitory. - Úprava zdrojových kódů.
- Build aplikace
- (Volitelně) Lokální spuštění aplikace se správnými konfiguračními parametry.
scp
aplikace na studentské VM- Spuštění aplikace se správnými konfiguračními parametry na VM.
- Provolání aplikace pomocí
curl
(nebo ekvivalentního nástroje). - Kontrola observability dat Grafaně.
git commit
&git push
vašich změn do vámi forknuté repozitory.
Odevzdání zadání
Splněné zadání se odevzdá formou: zpráva v aplikaci PARG, v kanále #nswi150-clouddev
.
Zpráva by měla mít formát:
@vit-kotacka @ldobias Odevzdání zadaní.
X-Request-Id: <vaše request ID>
compartment: <váš studentský compartment>
Troubleshooting
Pokud budete mít během vypracování zadání nějaký problém, udělejte následující věci:
- Pošlete notifikaci @vit-kotacka na PARG kanále
#nswi150-clouddev
- Pošlete odkaz na svou forknutou repozitory, která obsahuje vaše nejaktuálnější změny.
- Pošlete konfigurační parametry, se kterými spouštíte aplikaci.
- Definujte prostředí, ve kterém pracujete.
Podrobné zadání
git clone
této repozitory.
1. Fork a - Na GitHubu kliknout na tlačítko Fork
- V pracovním adresáři spustit příkaz:
git clone https://github.com/<vaše-repo>/observability-mff-uk.git
2. Úprava zdrojových kódů.
Projít zdrojové kódy (soubory *.go
) a vyřešit všechny TODO
. (Po vyřešení můžete TODO
řádek smazat.)
Pro porozumnění aplikaci a fungování instrumentace je doporučeno spustiti aplikaci
před úravou TODO
a postupně během úprav a sledovat výsledné chování.
Také je doporučeno řešit vždy jen jeden z pilířů observability, tedy postupně: logging
metriky a tracing. Jednotlivé oblasti poznáte podle suffixu TODO
, tj. TODO Logging:
,
TODO Metrics:
a TODO Tracing
.
TODO
:
Příklad úpravy Počáteční stav:
// TODO Logging: Enable json formatting for logging. Uncomment following line.
// logrus.SetFormatter(&logrus.JSONFormatter{})
Cílový stav:
logrus.SetFormatter(&logrus.JSONFormatter{})
3. Build aplikace
Aplikace se zbuilduje jednoduchým:
cd <naklonovaná repo>
go build
Výsledkem je binárka observability
.
4. (Volitelně) Lokální spuštění aplikace se správnými konfiguračními parametry.
Lokální spuštění bez backendů a downstream servis
Spustit aplikaci bez externích závislostí lze jednoduchým příkazem:
./observability
Lokální spuštění s backendy a downstream servisami
Pokud máte lokálně nainstalované všechny backendy (viz Předpoklady -> Volitelné), lze spustit všechny backendy pomocí příkazu:
./run-backends.sh
Aplikace se pak následně spustí příkazem:
./run-app.sh
!!! DŮLEŽITÉ !!! Před spuštěním skriptu run-backends.sh
si zkontrolujte, že následující
proměnné na začátku souboru odpovídají vašemu prostředí a případně je upravte na korektní
hodnotu:
LOKI_HOME="${HOME}/dev/loki"
PROMETHEUS_HOME="${HOME}/dev/prometheus"
JAEGER_HOME="${HOME}/dev/jaeger"
GRAFANA_HOME="${HOME}/dev/grafana"
Stejně tak si zkontrolujte dále ve skriptu, že názvy jednotlivých binárek odpovídají vašemu prostředí, či platformě. Např.:
"${LOKI_HOME}/loki-linux-amd64"
Obdobně potom zkontrolujte ve skriptu kill-backends.sh
, že názvy běžících procesů
jednotlivých backendů odpovídají hodnotám v proměnné APP
.
Provolání aplikace
Aplikace běží lokálně na adresse localhost:4040
. Lze ji provolat pomocí skriptu
curl-load.sh
, nebo jednoduchým curl
příkazem (či alternativou):
curl -v -H "X-Request-ID: test-42" localhost:4040/
Očekávaný výstup logů
Provolaná aplikace před změnami by měla vrátit na konzoli následující výstup:
INFO[2022-05-18T15:45:39+02:00] starting observability app on: 0.0.0.0:4040 app=my-app func=main
INFO[2022-05-18T15:45:43+02:00] writing response with status: 200 app=my-app func=homeHandler
Po vyřešení všech TODO
by se výstup aplikace měl objevit v souboru _logs/observability.log
:
{"app":"my-app","func":"main","level":"info","msg":"starting observability app on: 0.0.0.0:4040","time":"2022-05-18T16:23:22+02:00"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"getCorrelationId","level":"warning","msg":"header X-Correlation-ID is empty, no correlation id has been provided","requestId":"load-1-1652883805","time":"2022-05-18T16:23:25+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"tracingMiddleware","level":"debug","msg":"starting tracing...","requestId":"load-1-1652883805","time":"2022-05-18T16:23:25+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"metricsMiddleware","level":"debug","msg":"starting metrics...","requestId":"load-1-1652883805","time":"2022-05-18T16:23:25+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"loggingMiddleware","level":"info","msg":"serving request: GET localhost:4040/","requestId":"load-1-1652883805","time":"2022-05-18T16:23:25+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"loggingMiddleware","level":"debug","msg":"user agent: curl/7.74.0","requestId":"load-1-1652883805","time":"2022-05-18T16:23:25+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"callDownstream","level":"info","msg":"calling downstream service: http://localhost:5050","requestId":"load-1-1652883805","time":"2022-05-18T16:23:25+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"callDownstream","level":"info","msg":"downstream service returned http code: 200","requestId":"load-1-1652883805","time":"2022-05-18T16:23:26+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"callDownstream","level":"info","msg":"downstream service returned request id: e52a834d-ad13-469a-81e1-ecce61a22286","requestId":"load-1-1652883805","time":"2022-05-18T16:23:26+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"callDownstream","level":"debug","msg":"downstream service returned correlation id: a00219e6-11cf-4a94-8190-655dff17ad9f","requestId":"load-1-1652883805","time":"2022-05-18T16:23:26+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"homeHandler","level":"info","msg":"writing response with status: 200","requestId":"load-1-1652883805","time":"2022-05-18T16:23:27+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"metricsMiddleware","level":"debug","msg":"closing metrics...","requestId":"load-1-1652883805","time":"2022-05-18T16:23:27+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
{"app":"my-app","correlationId":"a00219e6-11cf-4a94-8190-655dff17ad9f","func":"tracingMiddleware","level":"debug","msg":"closing tracing...","requestId":"load-1-1652883805","time":"2022-05-18T16:23:27+02:00","traceId":"21beda5b8997fe529daae0f776877d62"}
scp
aplikace na studentské VM
5. Vámi vytvořené VM by mělo mít public IP adresu. Zkompilovanou binárku aplikace tam nahrajete příkazem:
scp observability opc@<vaše IP adresa>:~
O pushování logů do logging backendu (Loki) se stará aplikace promtail
- tu je potřeba
také nahrát na vaše VM. Aplikaci si stáhnete zde:
promtail-linux-amd64.zip.
Spolu s ní je také potřeba na VM nahrát její konfigurační soubor:
scp <cesta k rozbalenému promtail>/promtail-linux-amd64 opc@<vaše IP adresa>:~
scp _config/promtail-config.yaml opc@<vaše IP adresa>:~
Přihlašte se pomocí ssh
na vaše VM a vytvořte v domácím adresáři (kde by měly být všechny
soubory nahrané přes scp
) vytvořte adresář _logs
:
mkdir _logs
Vámi vytvořené prostředí by mělo vypadat takto:
.
├── _logs
├── observability
├── promtail-config.yaml
└── promtail-linux-amd64
6. Spuštění aplikace se správnými konfiguračními parametry na VM.
Prvně je potřeba spustit aplikaci promtail
:
./promtail-linux-amd64 -config.file promtail-config.yaml &
Aplikace poběží na pozadí (i když stdout
a stderr
jsou přesměrovány na konzoli).
Následně pustíte vaši aplikaci:
./observability -d "http://service1.edu.dobias.info:5050" -t "http://grafana.edu.dobias.info:14268/api/traces"
Význam jednotlivých parametrů si můžete vypsat příkazem:
[opc@sw-samuraj ~]$ ./observability -h
Options:
-d string
Downstream URL. Empty string triggers no call to downstream service.
-h Print help.
-n string
Application name. (default "my-app")
-p string
Application port. (default "4040")
-t string
Tracing URL. (default "http://localhost:14268/api/traces")
curl
(nebo ekvivalentního nástroje).
7. Provolání aplikace pomocí Protože vaše VM má veřejnou IP adresu, můžete aplikaci provolat z vašeho lokálního počítače:
curl -v <vaše IP adresa>:4040/
Případně pro poslání většího počtu requestů můžete použít skript curl-load.sh
,
kde upravíte parametry MAX_REQ
a URL
.
8. Kontrola observability dat v Grafaně.
Vizualizaci vašich observability dat si můžete prohlédnout v Grafaně, která běží na adrese http://grafana.edu.dobias.info:3000/
V levém menu vyberte položku Explore a následně vyberte v rozbalovacím menu jeden z backendů (Loki, Prometheus, Jaeger). Zobrazete si data z vaší aplikace pomocí následujících dotazů.
Názvy vašich labelů se můžou drobně měnit, proto si upravte dotazy podle vašich hodnot.
Loki
{job=~"downstream-1-logs|downstream-2-logs|student-app-logs"} | json | requestId="<vaše X-Request-ID"
Prometheus
rate(http_requests_total{job=~"service1|service2|student",path="/"}[1m])
Jaeger
Hledejte podle vašeho X-Tracing-Id
(zadáte ho do pole formuláře Trace ID).
git commit
& git push
vašich změn do vámi forknuté repozitory.
9. Všechny změny, které jste provedli ve zdrojovém kódu vložte do Gitu a publikujte do své forknuté GitHub repozitory:
git add .
git commit -m "commit message"
git push