gRPC

#Ne işe yarar

gRPC adımı bir gRPC servisinin metodunu çağırır: unary (tek istek, tek yanıt), server streaming, client streaming ve bidirectional (bidi) streaming. İstek mesajını JSON olarak yazarsınız; Spitfire şemayı kullanarak onu protobuf'a çevirir. Şema iki yerden gelir: sunucunun server reflection servisi ya da bağlantıya yüklediğiniz .proto dosyaları.

#Ne zaman kullanılır

• Mikroservisleriniz birbirleriyle gRPC üzerinden konuşuyorsa ve bir servisin yük altındaki gecikmesini ölçmek istiyorsanız.
• Streaming metotlarda ilk mesaja kadar geçen süreyi, mesaj başına gecikmeyi ve mesajlar arası süreyi görmek istiyorsanız.

#Bağlantı oluşturma

1. Bağlantılar → Bağlantı ekle'ye tıklayın, Tür olarak gRPC seçin.
2. Ad verin (ör. orders-grpc).
3. Adres (host:port) alanına servisin adresini yazın, örneğin orders.internal:50051. Zorunludur.
4. Gerekirse:
   • Authority: :authority header'ı adresten farklı olmalıysa (ör. bir proxy arkasında sanal host).
   • Bearer token: her çağrıda authorization: Bearer <token> metadata'sı olarak gönderilir. Secret'tır.
   • Her VU ayrı bağlantı: her VU kendi HTTP/2 bağlantısını açar.
   • Paylaşılan bağlantı sayısı (runner başına): Her VU ayrı bağlantı kapalıyken bir runner'daki VU'lar bu kadar bağlantıyı paylaşır (varsayılan 8). Tek bir bağlantı, sunucunun eşzamanlı stream sınırına (çoğu zaman 100–128) takılıp beklemeyi gecikme olarak sayar ve L4 yük dengeleyicinin arkasında bütün çağrıları tek backend'e gönderir; bu yüzden birden çok bağlantı kullanılır.
5. Şema kaynağı:
   • Sunucuda reflection açıksa hiçbir şey yüklemeyin; listede Şema server reflection ile alınır. görünür.
   • Reflection kapalıysa .proto dosyaları alanından servisin .proto dosyalarını, import ettikleriyle birlikte seçin (birden çok dosya seçebilirsiniz). Controller bunları kaydederken derler; derleme hatası varsa kayıt reddedilir ve hata gösterilir.
6. TLS gerekiyorsa TLS bölümünü açıp TLS kullan'ı işaretleyin (bkz. TLS ayarları).
7. Kaydet, ardından Test et.

#Adım ekleme

1. Test editöründe Adım ekle → Protokol olarak gRPC seçin.
2. Bağlantı listesinden gRPC bağlantınızı seçin.
3. Metot listesi şemadan doldurulur (Metot seçin…). Streaming metotların yanında türü yazar: server stream, client stream ya da bidi stream. Şema okunamazsa Şema okunamadı; metodu elle yazın çıkar; metodu paket.Servis/Metot biçiminde yazın (ör. shop.v1.Orders/GetOrder).
4. İstek mesajı (JSON) alanına mesajı yazın. Şablonu doldur düğmesi seçili metodun alanlarıyla boş bir JSON iskeleti yerleştirir. Alanlarda {{değişken}} kullanabilirsiniz.
5. Gerekirse Metadata ekleyin (ör. x-tenant: demo).
6. Streaming metotta stream ayarlarını yapın (aşağıda).
7. Check sekmesinde durumu doğrulayın: Durum check'i gRPC status adını (OK, NOT_FOUND, büyük/küçük harf fark etmez) ya da sayısal kodunu kabul eder.
8. Dene ile tek iterasyon gönderin, Kaydet.

{"id": "get-order", "name": "Sipariş getir", "protocol": "grpc", "connection": "orders-grpc",
 "grpc": {"method": "shop.v1.Orders/GetOrder", "message": "{\"id\": \"{{$uuid}}\"}",
   "metadata": [{"key": "x-tenant", "value": "demo"}]},
 "checks": [{"type": "status", "value": "OK"}]}

#Streaming ayarları

Streaming bir metot seçtiğinizde Streaming metot bölümü açılır. Bir adım bir stream'dir.

On mesaj gönderen, on yanıt bekleyen ve onuncu yanıtı doğrulayan bir bidi stream:

{"id": "chat", "name": "Chat", "protocol": "grpc", "connection": "orders-grpc",
 "grpc": {"method": "shop.v1.Chat/Talk", "message": "{\"text\": \"selam {{__MSG}}\"}",
   "stream": {"count": 10, "interval": "100ms", "receive": 10, "body": "all"}},
 "checks": [{"type": "jsonPath", "path": "$[9].text", "value": "selam 9"}]}

Gönderilen ve alınan mesaj sayıları grpc-messages-sent / grpc-messages-received header'larında da bulunur; check'lerde kullanabilirsiniz.

#Ürettiği metrikler

Koşu sayfasında streaming adımlar gRPC stream'leri tablosunda (Gönderilen mesaj, Alınan mesaj, İlk mesaj p95, Mesaj gecikmesi p95, Mesajlar arası p95) görünür. Eşik örneği: {"metric": "grpc_time_to_first_message", "expr": "p(95)<300"}.

#Sık karşılaşılan sorunlar

Belirti: Metot listesi boş, Şema okunamadı; metodu elle yazın ya da gRPC şeması alınamadı. Neden: Sunucuda server reflection kapalı ve bağlantıya .proto yüklenmemiş; ya da adres/TLS ayarı yanlış olduğu için controller sunucuya ulaşamıyor. Çözüm: Önce Test et ile bağlantıyı doğrulayın. Bağlantı yeşilse .proto dosyaları'nı import ettikleriyle birlikte yükleyin.

Belirti: .proto yüklerken kayıt reddediliyor, mesajda not found / could not resolve import. Neden: Bir import edilen dosya eksik. Çözüm: Import zincirindeki tüm dosyaları (ör. ortak common.proto) birlikte seçin.

Belirti: Unavailable, connection refused ya da transport: authentication handshake failed. Neden: Port yanlış, servis kapalı ya da TLS ayarı sunucuyla uyuşmuyor (TLS'li sunucuya düz bağlantı veya tersi). Çözüm: Adres (host:port)'u ve TLS kullan kutusunu kontrol edin; özel CA için CA sertifikası ekleyin.

Belirti: UNAUTHENTICATED ya da PERMISSION_DENIED. Neden: Token eksik ya da yanlış. Çözüm: Bearer token'ı yeniden yazıp kaydedin veya adımın Metadata alanında doğru header'ı gönderin.

Belirti: Streaming adımda DEADLINE_EXCEEDED. Neden: Stream, timeout dolmadan bitmedi (sunucu stream'i kapatmıyor ya da yanıtlar yavaş). Çözüm: Beklenecek yanıt sayısı ya da Stream süresi verin; gerekirse Timeout (deadline)'ı artırın.

Belirti: Adım incomplete hatasıyla başarısız. Neden: Sunucu, Beklenecek yanıt sayısına ulaşmadan stream'i bitirdi. Çözüm: Sayıyı sunucunun gerçekten gönderdiği yanıt sayısına göre düzeltin ya da alanı boş bırakın.

Belirti: Yük arttıkça p95 basamak basamak yükseliyor, sunucu CPU'su düşük. Neden: Çok sayıda VU az sayıda HTTP/2 bağlantısını paylaşıyor ve sunucunun stream sınırında bekliyor. Çözüm: Paylaşılan bağlantı sayısı (runner başına)'nı artırın ya da Her VU ayrı bağlantı'yı işaretleyin.

#İlgili sayfalar

• Protokoller ve bağlantılar
• HTTP, WebSocket ve SSE
• Kafka