Konfigurowanie podstawowej wtyczki OpenTelemetry w gRPC Python

1. Wprowadzenie

W tym laboratorium nauczysz się tworzyć za pomocą gRPC klienta i serwera, które stanowią podstawę aplikacji do mapowania tras napisanej w Pythonie.

Po ukończeniu tego samouczka będziesz mieć prostą aplikację gRPC HelloWorld z instrumentacją za pomocą wtyczki gRPC OpenTelemetry i będziesz w stanie wyświetlać wyeksportowane wskaźniki obserwacji w usłudze Prometheus.

Czego się nauczysz

• Jak skonfigurować wtyczkę OpenTelemetry w istniejącej aplikacji gRPC w Pythonie
• Uruchamianie lokalnej instancji Prometheus
• Eksportowanie wskaźników do usługi Prometheus
• Wyświetlanie danych z panelu Prometheus

2. Zanim zaczniesz

Czego potrzebujesz

• git
• curl
• build-essential
• Python w wersji 3.9 lub nowszej. Instrukcje instalacji Pythona na poszczególnych platformach znajdziesz w artykule Python Setup and Usage (Konfiguracja i używanie Pythona). Możesz też zainstalować Pythona, który nie jest częścią systemu, za pomocą narzędzi takich jak uv lub pyenv.
• pip w wersji 9.0.1 lub nowszej do instalowania pakietów Pythona.
• venv do tworzenia wirtualnych środowisk Pythona.

Zainstaluj wymagania wstępne:

sudo apt-get update -y
sudo apt-get upgrade -y
sudo apt-get install -y git curl build-essential clang
sudo apt install python3
sudo apt install python3-pip python3-venv

Pobierz kod

Aby ułatwić Ci naukę, w tym ćwiczeniu z programowania znajdziesz gotowy szkielet kodu źródłowego, który pomoże Ci zacząć. Z podanych niżej instrukcji dowiesz się, jak zintegrować wtyczkę gRPC OpenTelemetry z aplikacją.

grpc-codelabs

Kod źródłowy szkieletu tego ćwiczenia z programowania jest dostępny w tym katalogu na GitHubie. Jeśli nie chcesz samodzielnie implementować kodu, gotowy kod źródłowy znajdziesz w katalogu completed.

Najpierw sklonuj repozytorium z ćwiczeniami z grpc i przejdź do folderu grpc-python-opentelemetry:

git clone https://github.com/grpc-ecosystem/grpc-codelabs.git
cd grpc-codelabs/codelabs/grpc-python-opentelemetry/

Możesz też pobrać plik ZIP zawierający tylko katalog z codelabem i rozpakować go ręcznie.

Pobierz plik ZIP

Najpierw utwórz nowe wirtualne środowisko Pythona (venv), aby odizolować zależności projektu od pakietów systemowych:

python3 -m venv --upgrade-deps .venv

Aby aktywować środowisko wirtualne w powłoce bash/zsh:

source .venv/bin/activate

W przypadku systemu Windows i niestandardowych powłok zobacz tabelę na stronie https://docs.python.org/3/library/venv.html#how-venvs-work.

Uwaga: środowisko wirtualne musisz aktywować za każdym razem, gdy otworzysz nową powłokę. Skrypt activate konfiguruje zmienną $PATH tak, aby używała Pythona i narzędzia pip z Twojego środowiska wirtualnego. Aby zdezaktywować środowisko wirtualne, po prostu uruchom deactivate.

Następnie zainstaluj zależności w środowisku, używając tego polecenia:

python -m pip install -r requirements.txt

3. Rejestrowanie wtyczki OpenTelemetry

Aby dodać wtyczkę gRPC OpenTelemetry, potrzebujemy aplikacji gRPC. W tych ćwiczeniach z programowania użyjemy prostego klienta i serwera gRPC HelloWorld, które wyposażymy w wtyczkę gRPC OpenTelemetry.

Najpierw zarejestruj w kliencie wtyczkę OpenTelemetry skonfigurowaną z eksporterem Prometheus. Otwórz plik start_here/observability_greeter_client.py w ulubionym edytorze. Najpierw dodaj powiązane zależności i makra, aby wyglądały tak:

import logging
import time

import grpc
import grpc_observability
import helloworld_pb2
import helloworld_pb2_grpc
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from opentelemetry.sdk.metrics import MeterProvider
from prometheus_client import start_http_server

_SERVER_PORT = "50051"
_PROMETHEUS_PORT = 9465

Następnie przekształć run() w taki sposób:

def run():
    # Start Prometheus client
    start_http_server(port=_PROMETHEUS_PORT, addr="0.0.0.0")
    meter_provider = MeterProvider(metric_readers=[PrometheusMetricReader()])

    otel_plugin = grpc_observability.OpenTelemetryPlugin(
        meter_provider=meter_provider
    )
    otel_plugin.register_global()

    with grpc.insecure_channel(target=f"localhost:{_SERVER_PORT}") as channel:
        stub = helloworld_pb2_grpc.GreeterStub(channel)
        # Continuously send RPCs every second.
        while True:
            try:
                response = stub.SayHello(helloworld_pb2.HelloRequest(name="You"))
                print(f"Greeter client received: {response.message}")
                time.sleep(1)
            except grpc.RpcError as rpc_error:
                print("Call failed with code: ", rpc_error.code())

    # Deregister is not called in this example, but this is required to clean up.
    otel_plugin.deregister_global()

Uwaga: w usłudze OpenTelemetry Meter Provider jest konfigurowany eksporter Prometheus. (Dane możesz też wyeksportować w inny sposób. W tym laboratorium wybieramy eksportera Prometheus). Ten obiekt MeterProvider jest przekazywany do wtyczki OpenTelemetry gRPC jako konfiguracja. Gdy wtyczka OpenTelemetry zostanie zarejestrowana globalnie, wszyscy klienci i serwery gRPC będą instrumentowani za pomocą OpenTelemetry.

Następnym krokiem jest dodanie wtyczki OpenTelemetry do serwera. Otwórz start_here/observability_greeter_server.py i dodaj powiązane zależności i makra, aby wyglądały tak:

from concurrent import futures
import logging
import time

import grpc
import grpc_observability
import helloworld_pb2
import helloworld_pb2_grpc
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from prometheus_client import start_http_server

_SERVER_PORT = "50051"
_PROMETHEUS_PORT = 9464

Następnie przekształć run() w taki sposób:

def serve():
    # Start Prometheus client
    start_http_server(port=_PROMETHEUS_PORT, addr="0.0.0.0")

    meter_provider = MeterProvider(metric_readers=[PrometheusMetricReader()])

    otel_plugin = grpc_observability.OpenTelemetryPlugin(
        meter_provider=meter_provider
    )
    otel_plugin.register_global()

    server = grpc.server(
        thread_pool=futures.ThreadPoolExecutor(max_workers=10),
    )
    helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
    server.add_insecure_port("[::]:" + _SERVER_PORT)
    server.start()
    print("Server started, listening on " + _SERVER_PORT)

    server.wait_for_termination()

    # Deregister is not called in this example, but this is required to clean up.
    otel_plugin.deregister_global()

4. Uruchamianie przykładu i wyświetlanie danych

Aby uruchomić serwer, wpisz:

cd start_here
python -m observability_greeter_server

Po pomyślnej konfiguracji na serwerze zobaczysz te dane wyjściowe:

Server started, listening on 50051

Gdy serwer działa, w innym terminalu uruchom klienta:

# Run the below commands to cd to the working directory and activate virtual environment in the new terminal
cd grpc-codelabs/codelabs/grpc-python-opentelemetry/
source .venv/bin/activate

cd start_here
python -m observability_greeter_client

Prawidłowe uruchomienie będzie wyglądać tak:

Greeter client received: Hello You
Greeter client received: Hello You
Greeter client received: Hello You

Skonfigurowaliśmy wtyczkę gRPC OpenTelemetry do eksportowania wskaźników za pomocą Prometheus. Te dane będą dostępne na serwerze localhost:9464 i na kliencie localhost:9465.

Aby wyświetlić dane klienta:

curl localhost:9465/metrics

Wynik będzie miał postać:

# HELP python_gc_objects_collected_total Objects collected during gc
# TYPE python_gc_objects_collected_total counter
python_gc_objects_collected_total{generation="0"} 241.0
python_gc_objects_collected_total{generation="1"} 163.0
python_gc_objects_collected_total{generation="2"} 0.0
# HELP python_gc_objects_uncollectable_total Uncollectable objects found during GC
# TYPE python_gc_objects_uncollectable_total counter
python_gc_objects_uncollectable_total{generation="0"} 0.0
python_gc_objects_uncollectable_total{generation="1"} 0.0
python_gc_objects_uncollectable_total{generation="2"} 0.0
# HELP python_gc_collections_total Number of times this generation was collected
# TYPE python_gc_collections_total counter
python_gc_collections_total{generation="0"} 78.0
python_gc_collections_total{generation="1"} 7.0
python_gc_collections_total{generation="2"} 0.0
# HELP python_info Python platform information
# TYPE python_info gauge
python_info{implementation="CPython",major="3",minor="10",patchlevel="9",version="3.10.9"} 1.0
# HELP process_virtual_memory_bytes Virtual memory size in bytes.
# TYPE process_virtual_memory_bytes gauge
process_virtual_memory_bytes 1.868988416e+09
# HELP process_resident_memory_bytes Resident memory size in bytes.
# TYPE process_resident_memory_bytes gauge
process_resident_memory_bytes 4.1680896e+07
# TYPE process_resident_memory_bytes gauge                                                                                                                                                                                                                                                                21:20:16 [154/966]
process_resident_memory_bytes 4.1680896e+07
# HELP process_start_time_seconds Start time of the process since unix epoch in seconds.
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1.72375679833e+09
# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
# TYPE process_cpu_seconds_total counter
process_cpu_seconds_total 0.38
# HELP process_open_fds Number of open file descriptors.
# TYPE process_open_fds gauge
process_open_fds 9.0
# HELP process_max_fds Maximum number of open file descriptors.
# TYPE process_max_fds gauge
process_max_fds 4096.0
# HELP target_info Target metadata
# TYPE target_info gauge
target_info{service_name="unknown_service",telemetry_sdk_language="python",telemetry_sdk_name="opentelemetry",telemetry_sdk_version="1.26.0"} 1.0
# HELP grpc_client_attempt_started_total Number of client call attempts started
# TYPE grpc_client_attempt_started_total counter
grpc_client_attempt_started_total{grpc_method="other",grpc_target="localhost:50051"} 18.0
# HELP grpc_client_attempt_sent_total_compressed_message_size_bytes Compressed message bytes sent per client call attempt
# TYPE grpc_client_attempt_sent_total_compressed_message_size_bytes histogram
grpc_client_attempt_sent_total_compressed_message_size_bytes_bucket{grpc_method="other",grpc_status="OK",grpc_target="localhost:50051",le="0.0"} 0.0
grpc_client_attempt_sent_total_compressed_message_size_bytes_bucket{grpc_method="other",grpc_status="OK",grpc_target="localhost:50051",le="5.0"} 18.0
grpc_client_attempt_sent_total_compressed_message_size_bytes_bucket{grpc_method="other",grpc_status="OK",grpc_target="localhost:50051",le="10.0"} 18.0
grpc_client_attempt_sent_total_compressed_message_size_bytes_bucket{grpc_method="other",grpc_status="OK",grpc_target="localhost:50051",le="25.0"} 18.0
grpc_client_attempt_sent_total_compressed_message_size_bytes_bucket{grpc_method="other",grpc_status="OK",grpc_target="localhost:50051",le="50.0"} 18.0
grpc_client_attempt_sent_total_compressed_message_size_bytes_bucket{grpc_method="other",grpc_status="OK",grpc_target="localhost:50051",le="75.0"} 18.0
grpc_client_attempt_sent_total_compressed_message_size_bytes_bucket{grpc_method="other",grpc_status="OK",grpc_target="localhost:50051",le="100.0"} 18.0
grpc_client_attempt_sent_total_compressed_message_size_bytes_bucket{grpc_method="other",grpc_status="OK",grpc_target="localhost:50051",le="250.0"} 18.0

Podobnie w przypadku danych po stronie serwera:

curl localhost:9464/metrics

5. Wyświetlanie danych w Prometheusie

Skonfigurujemy tu instancję usługi Prometheus, która będzie pobierać dane z przykładowego klienta i serwera gRPC eksportujących dane za pomocą usługi Prometheus.

Pobierz najnowszą wersję Prometheusa na swoją platformę, korzystając z podanego linku, lub użyj tego polecenia:

curl -sLO https://github.com/prometheus/prometheus/releases/download/v3.7.3/prometheus-3.7.3.linux-amd64.tar.gz

Następnie wyodrębnij i uruchom go za pomocą tego polecenia:

tar xvfz prometheus-*.tar.gz
cd prometheus-*

Utwórz plik konfiguracji usługi Prometheus o tej treści:

cat > grpc_otel_python_prometheus.yml <<EOF
scrape_configs:
  - job_name: "prometheus"
    scrape_interval: 5s
    static_configs:
      - targets: ["localhost:9090"]
  - job_name: "grpc-otel-python"
    scrape_interval: 5s
    static_configs:
      - targets: ["localhost:9464", "localhost:9465"]
EOF

Uruchom Prometheusa z nową konfiguracją:

./prometheus --config.file=grpc_otel_python_prometheus.yml

Spowoduje to skonfigurowanie wskaźników z procesów po stronie klienta i serwera w samouczku, aby były pobierane co 5 sekund.

Aby wyświetlić dane, otwórz adres http://localhost:9090/graph. Na przykład zapytanie:

histogram_quantile(0.5, rate(grpc_client_attempt_duration_seconds_bucket[1m]))

wyświetli wykres z medianą opóźnienia próby z 1-minutowym oknem czasowym do obliczania kwantyla.

Częstotliwość zapytań –

increase(grpc_client_attempt_duration_seconds_bucket[1m])

6. (Opcjonalnie) Ćwiczenie dla użytkownika

Na panelach Prometheusa zauważysz, że liczba zapytań na sekundę jest niska. Sprawdź, czy w przykładzie kodu możesz znaleźć podejrzany kod, który ogranicza liczbę zapytań na sekundę.

W przypadku entuzjastów kod klienta ogranicza się do posiadania tylko jednego oczekującego wywołania RPC w danym momencie. Można to zmodyfikować tak, aby klient wysyłał więcej wywołań RPC bez czekania na zakończenie poprzednich. (Rozwiązanie tego problemu nie zostało podane).