1. Giriş
Bu codelab'de, Java ile yazılmış bir rota eşleme uygulamasının temelini oluşturan bir istemci ve sunucu oluşturmak için gRPC'yi kullanacaksınız.
Eğitimin sonunda, gRPC OpenTelemetry eklentisiyle donatılmış basit bir gRPC HelloWorld uygulamanız olacak ve dışa aktarılan gözlemlenebilirlik metriklerini Prometheus'ta görebileceksiniz.
Neler öğreneceksiniz?
- Mevcut gRPC Java uygulaması için OpenTelemetry eklentisi nasıl kurulur?
- Yerel bir Prometheus örneği çalıştırma
- Metrikleri Prometheus'a aktarma
- Prometheus kontrol panelinden metrikleri görüntüleme
2. Başlamadan önce
İhtiyacınız olanlar
gitcurlJDKv8 veya sonraki sürümleri
Ön koşulları yükleyin:
sudo apt-get update -y
sudo apt-get upgrade -y
sudo apt-get install -y git curl
Kodu alın
Bu codelab, öğrenme sürecinizi kolaylaştırmak için başlamanıza yardımcı olacak önceden oluşturulmuş bir kaynak kodu iskeleti sunar. Aşağıdaki adımlar, bir uygulamada gRPC OpenTelemetry eklentisini kullanma konusunda size yol gösterecektir.
Bu codelab'in iskele kaynak kodunu bu GitHub dizininde bulabilirsiniz. Kodu kendiniz uygulamayı tercih etmezseniz tamamlanmış kaynak kodu completed dizininde bulabilirsiniz.
Öncelikle grpc codelab deposunu klonlayın ve grpc-java-opentelemetry klasörüne gidin:
git clone https://github.com/grpc-ecosystem/grpc-codelabs.git
cd grpc-codelabs/codelabs/grpc-java-opentelemetry/
Alternatif olarak, yalnızca codelab dizinini içeren .zip dosyasını indirebilir ve manuel olarak sıkıştırmasını açabilirsiniz.
3. OpenTelemetry eklentisini kaydetme
gRPC OpenTelemetry eklentisini eklemek için bir gRPC uygulamasına ihtiyacımız var. Bu codelab'de, gRPC OpenTelemetry eklentisiyle donatacağımız basit bir gRPC HelloWorld istemcisi ve sunucusu kullanacağız.
İlk adımınız, istemcide Prometheus dışa aktarıcısıyla yapılandırılmış OpenTelemetry eklentisini kaydetmektir. codelabs/grpc-java-opentelemetry/start_here/src/main/java/io/grpc/codelabs/opentelemetry/OpenTelemetryClient.java dosyasını en sevdiğiniz düzenleyiciyle açın. Ardından, gRPC Java OpenTelemetry API'yi kurmak için kod eklemek üzere main dosyasını değiştirin.
İstemcide enstrüman oluşturma kurulumu
Prometheus dışa aktarıcısı oluşturma
OpenTelemetry metriklerini Prometheus biçimine dönüştürmek ve bunları bir HttpServer aracılığıyla kullanıma sunmak için PrometheusHttpServer oluşturun. Aşağıdaki kod snippet'i yeni bir Prometheus Exporter oluşturur.
// Default prometheus port i.e `prometheusPort` has been initialized to 9465
PrometheusHttpServer prometheusExporter = PrometheusHttpServer.builder()
.setPort(prometheusPort)
.build();
OpenTelemetry SDK örneği oluşturma
Yukarıdaki prometheusExporter öğesini, SdkMeterProvider öğesinden metrik okumak için MetricReader olarak kaydedin. SdkMeterProvider, metrik ayarlarını yapılandırmak için kullanılır.
SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
.registerMetricReader(prometheusExporter)
.build();
OpenTelemetry'nin SDK uygulaması için yukarıda oluşturulan sdkMeterProvider ile OpenTelemetrySdk örneği oluşturun.
OpenTelemetrySdk openTelemetrySdk =OpenTelemetrySdk.builder()
.setMeterProvider(sdkMeterProvider)
.build();
GrpcOpenTelemetry örneği oluşturma
GrpcOpenTelemetry API'sini kullanarak Prometheus Metric dışa aktarıcısını kullanan OpenTelemetry SDK'sını ayarlayın.
GrpcOpenTelemetry grpcOpenTelmetry = GrpcOpenTelemetry.newBuilder()
.sdk(openTelemetrySdk)
.build();
// Registers gRPC OpenTelemetry globally.
grpcOpenTelmetry.registerGlobal();
Bir GrpcOpenTelemetry örneği registerGlobal kullanılarak genel olarak kaydedildikten sonra, daha sonra oluşturulan tüm gRPC istemcileri ve sunucuları OpenTelemetry ile donatılır.
OpenTelemetry SDK'sını kapatma
Kapatma işlemi, ShutDownHook içinde yapılmalıdır. openTelemetrySdk.close(), SDK'yı kapatır ve SdkMeterProvider'da da kapatma işlemini çağırır.
Sunucuda enstrüman kurulumu
Benzer şekilde, GrpcOpenTelemetry'yi de sunucuya ekleyelim. codelabs/grpc-java-opentelemetry/start_here/src/main/java/io/grpc/codelabs/opentelemetry/OpenTelemetryServer.java uygulamasını açın ve GrpcOpenTelemetry'yi başlatmak için kod ekleyin.
Prometheus dışa aktarıcısı oluşturma
Bu codelab aynı makinede çalıştırılabileceğinden, PrometheusHttpServer oluşturulurken bağlantı noktası çakışmalarını önlemek için gRPC sunucu tarafı metriklerini barındırmak üzere farklı bir bağlantı noktası kullanıyoruz.
// Default prometheus port i.e `prometheusPort` has been set to 9464
PrometheusHttpServer prometheusExporter = PrometheusHttpServer.builder()
.setPort(prometheusPort)
.build();
OpenTelemetry SDK örneği oluşturma
SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
.registerMetricReader(prometheusExporter)
.build();
GrpcOpenTelemetry'yi OpenTelemetry SDK ile başlatma
OpenTelemetrySdk openTelemetrySdk =OpenTelemetrySdk.builder()
.setMeterProvider(sdkMeterProvider)
.build();
GrpcOpenTelemetry örneği oluşturma
GrpcOpenTelemetry grpcOpenTelmetry = GrpcOpenTelemetry.newBuilder()
.sdk(openTelemetrySdk)
.build();
// Registers gRPC OpenTelemetry globally.
grpcOpenTelmetry.registerGlobal();
OpenTelemetry SDK'sını kapatma
gRPC kanalı kapatıldıktan sonra. openTelemetrySdk.close() çağrısı, SDK'yı kapatır ve SdkMeterProvider'da da kapatma çağrısı yapar.
4. Örneği çalıştırma ve metrikleri görüntüleme
Sunucuyu çalıştırmak için şunu çalıştırın:
cd start_here
../gradlew installDist
./build/install/start_here/bin/opentelemetry-server
Kurulum başarılı olduğunda sunucu için aşağıdaki çıkışı görürsünüz:
[date and time] io.grpc.codelabs.opentelemetry.OpenTelemetryServer start
INFO: Server started, listening on 50051
Sunucu çalışırken başka bir terminalde istemciyi çalıştırın:
./build/install/start_here/bin/opentelemetry-client world
Başarılı bir çalıştırma şöyle görünür:
[date and time]io.grpc.codelabs.opentelemetry.OpenTelemetryClient greet
INFO: Greeting: Hello world
[date and time] io.grpc.codelabs.opentelemetry.OpenTelemetryClient greet
INFO: Will try to greet world ...
[date and time]io.grpc.codelabs.opentelemetry.OpenTelemetryClient greet
INFO: Greeting: Hello world
Prometheus kullanarak metrikleri dışa aktarmak için gRPC OpenTelemetry eklentisini kurduğumuzdan. Bu metrikler, sunucu için localhost:9464, istemci için ise localhost:9465 adresinde kullanılabilir.
Müşteri metriklerini görmek için:
curl localhost:9465/metrics
Sonuç şu biçimde olur:
# HELP grpc_client_attempt_duration_seconds Time taken to complete a client call attempt
# TYPE grpc_client_attempt_duration_seconds histogram
grpc_client_attempt_duration_seconds_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="0.002"} 0
grpc_client_attempt_duration_seconds_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="0.003"} 2
grpc_client_attempt_duration_seconds_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="0.004"} 14
grpc_client_attempt_duration_seconds_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="0.005"} 29
grpc_client_attempt_duration_seconds_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="0.1"} 33
grpc_client_attempt_duration_seconds_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="+Inf"} 34
grpc_client_attempt_duration_seconds_count{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0"} 34
grpc_client_attempt_duration_seconds_sum{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0"} 0.46512665300000006
# HELP grpc_client_attempt_rcvd_total_compressed_message_size_bytes Compressed message bytes received per call attempt
# TYPE grpc_client_attempt_rcvd_total_compressed_message_size_bytes histogram
grpc_client_attempt_rcvd_total_compressed_message_size_bytes_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="0.0"} 0
grpc_client_attempt_rcvd_total_compressed_message_size_bytes_sum{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0"} 442.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="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="0.0"} 0
grpc_client_attempt_sent_total_compressed_message_size_bytes_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="1024.0"} 34
grpc_client_attempt_sent_total_compressed_message_size_bytes_sum{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0"} 238.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="helloworld.Greeter/SayHello",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0"} 34.0
# HELP grpc_client_call_duration_seconds Time taken by gRPC to complete an RPC from application's perspective
# TYPE grpc_client_call_duration_seconds histogram
grpc_client_call_duration_seconds_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="0.0"} 0
grpc_client_call_duration_seconds_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="0.003"} 2
grpc_client_call_duration_seconds_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0",le="+Inf"} 34
grpc_client_call_duration_seconds_count{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0"} 34
grpc_client_call_duration_seconds_sum{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-java",otel_scope_version="1.66.0"} 0.512708707
# TYPE target_info gauge
target_info{service_name="unknown_service:java",telemetry_sdk_language="java",telemetry_sdk_name="opentelemetry",telemetry_sdk_version="1.40.0"} 1
Aynı şekilde, sunucu tarafı metrikleri için:
curl localhost:9464/metrics
5. Prometheus'taki metrikleri görüntüleme
Burada, prometheus kullanarak metrikleri dışa aktaran gRPC örnek istemcimizi ve sunucumuzu kazıyacak bir prometheus örneği kuracağız.
Platformunuz için Prometheus'un en son sürümünü indirin, ardından çıkarıp çalıştırın:
tar xvfz prometheus-*.tar.gz
cd prometheus-*
Aşağıdaki bilgileri içeren bir Prometheus yapılandırma dosyası oluşturun:
cat > grpc_otel_java_prometheus.yml <<EOF
scrape_configs:
- job_name: "prometheus"
scrape_interval: 5s
static_configs:
- targets: ["localhost:9090"]
- job_name: "grpc-otel-java"
scrape_interval: 5s
static_configs:
- targets: ["localhost:9464", "localhost:9465"]
EOF
Prometheus'u yeni yapılandırmayla başlatın:
./prometheus --config.file=grpc_otel_java_prometheus.yml
Bu işlem, istemci ve sunucu codelab işlemlerindeki metriklerin 5 saniyede bir kazınacak şekilde yapılandırılmasını sağlar.
Metrikleri görüntülemek için http://localhost:9090/graph adresine gidin. Örneğin, şu sorgu:
histogram_quantile(0.5, rate(grpc_client_attempt_duration_seconds_bucket[1m]))
, nicelik hesaplaması için zaman aralığı olarak 1 dakikanın kullanıldığı, deneme gecikmesinin ortanca değerini gösteren bir grafik gösterir.
Sorgu oranı:
increase(grpc_client_attempt_duration_seconds_bucket[1m])
6. (İsteğe bağlı) Kullanıcı için egzersiz
Prometheus kontrol panellerinde QPS'nin düşük olduğunu görürsünüz. Örnekte, sorgu/saniye sayısını sınırlayan şüpheli bir kod olup olmadığını kontrol edin.
İstekli kullanıcılar için istemci kodu, belirli bir anda yalnızca tek bir bekleyen RPC'ye sahip olacak şekilde sınırlandırılmıştır. Bu, istemcinin önceki RPC'lerin tamamlanmasını beklemeden daha fazla RPC gönderecek şekilde değiştirilebilir. (Bunun çözümü sağlanmadı.)