Performance Testing gRPC: Step-by-Step Guide with Real Code Samples

 

gRPC is a high-performance, language-agnostic remote procedure call (RPC) framework developed by Google. It’s designed for efficient communication between microservices and is based on the HTTP/2 protocol. While gRPC offers impressive performance out of the box, it’s essential to conduct performance testing to ensure your services can handle real-world loads effectively. In this comprehensive guide, we’ll explore the importance of performance testing for gRPC services and provide code examples and best practices to help you get started.

Setting Up a gRPC Service for Performance Testing

Before we dive into performance testing, let’s set up a simple gRPC service and client for demonstration purposes. We’ll use Python and the gRPC library for this example.

Installing gRPC for Python

You can install the gRPC Python library using pip:pip install grpcio

pip install grpcio

pip install grpcio-toolip install grpcio-tool

Creating a Simple gRPC Service

Let’s start by defining the service interface in a Protocol Buffers (protobuf) file:

syntax = "proto3";

package calculator;

service Calculator {

rpc Add (AddRequest) returns (AddResponse);

}

message AddRequest {

int32 num1 = 1;

int32 num2 = 2;

}

message AddResponse {

int32 result = 1;

}

Now, generate the Python code from the protobuf file:

python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. calculator.proto

Implementing the gRPC Service

Let’s implement the gRPC server:

import grpc

import calculator_pb2

import calculator_pb2_grpc

class Calculator(calculator_pb2_grpc.CalculatorServicer):

def Add(self, request, context):

result = request.num1 + request.num2

return calculator_pb2.AddResponse(result=result)

def serve():

server = grpc.server(grpc.ThreadPoolExecutor(max_workers=10))

calculator_pb2_grpc.add_CalculatorServicer_to_server(Calculator(), server)

server.add_insecure_port("[::]:50051")

server.start()

server.wait_for_termination()

if __name__ == "__main__":

serve()

Creating a gRPC Client

Now, let’s create a simple gRPC client to interact with the service:

import grpc

import calculator_pb2

import calculator_pb2_grpc

def run():

channel = grpc.insecure_channel("localhost:50051")

stub = calculator_pb2_grpc.CalculatorStub(channel)

request = calculator_pb2.AddRequest(num1=5, num2=3)

response = stub.Add(request)

print("Response:", response.result)

if __name__ == "__main__":

run()

Conducting Performance Testing

Now that we have our gRPC service and client set up, let’s conduct performance testing using two popular tools: Locust and Gatling.

Performance Testing with Locust

Installing Locust

You can install Locust via pip:

pip install locust

Writing a Locust Test Script

Here’s a Locust test script that simulates multiple users making gRPC requests:

from locust import HttpUser, TaskSet, task, between

class GrpcUser(HttpUser):

wait_time = between(1, 5)

@task(1)

def add_operation(self):

payload = {"num1": 5, "num2": 3}

self.client.post("/calculator.Calculator/Add", json=payload)

Running the Locust Performance Test

You can run the Locust test with the following command:

locust -f locustfile.py --host=http://localhost:50051

Locust will start a web-based UI on `http://localhost:8089`, allowing you to configure and run your performance test.

Performance Testing with Gatling

You can download Gatling from the official website (https://gatling.io/download/) and follow the installation instructions.

Writing a Gatling Simulation

Here’s a Gatling simulation script for testing gRPC services:

import io.gatling.core.Predef._

import io.gatling.http.Predef._

class CalculatorSimulation extends Simulation {

val grpcConf = http

.baseUrl("http://localhost:50051")

.header("Content-Type", "application/grpc")

val scn = scenario("gRPC Performance Test")

.exec(

http("gRPC Add")

.post("/calculator.Calculator/Add")

.header("grpc-encoding", "identity")

.header("TE", "trailers")

.body(StringBody("Your gRPC Request Payload Here"))

.check(status.is(200))

)

setUp(scn.inject(atOnceUsers(10)).protocols(grpcConf))

}

Running the Gatling Performance Test

You can run the Gatling test using the following command:

./gatling.sh -s CalculatorSimulation

Gatling will generate detailed reports and metrics to help you analyze the performance of your gRPC service.

Conclusion

Performance testing is essential to ensure your gRPC services can meet the demands of real-world traffic. In this comprehensive guide, we set up a simple gRPC service and client and performed performance tests using Locust and Gatling.

Happy Load Testing 🔖

Performance Metrics Measure

Performance testing is only as effective as the metrics you measure and act on. In distributed systems, it’s not just about response time — it’s about end-to-end system behavior under load, resource utilization, and failure thresholds.

Here’s how I typically categorize and collect key performance testing metrics, based on my real-world experience with high-scale platforms.

---

✅ 1. Core Performance Metrics

Metric	Why It Matters
Throughput (TPS/QPS)	Measures system capacity — are we handling the expected load?
Latency (P50, P95, P99)	Helps detect tail latencies and slow paths. P99 is critical for user experience.
Error Rate (%)	Any spike under load suggests bottlenecks or instability.
Concurrency	Helps test thread safety and async processing under pressure.
Time to First Byte / Full Response	Important for APIs and UI performance perception.

✅ 2. Resource Utilization Metrics

Resource	Metric	Purpose
CPU	% Usage, context switches	Detect CPU-bound operations
Memory	Heap/Non-heap usage, GC pause time	Tune for memory leaks, OOM risk
Disk I/O	Read/write IOPS, latency	Ensure storage doesn’t become a bottleneck
Network	Throughput, packet loss, RTT	Catch bandwidth saturation, dropped packets
Thread Pools	Active threads, queue size	Avoid thread starvation under load

Tools used: Prometheus, Grafana, New Relic, top, vmstat, iostat, jstat, jmap, async-profiler

✅ 3. Application-Specific Metrics

Component	Metrics to Monitor
Kafka	Consumer lag, messages/sec, ISR count
DB/Cache (e.g., Redis, Postgres)	Query latency, cache hit/miss, slow query logs
Elasticsearch	Query throughput, indexing rate, segment merges, node GC
Spark Jobs	Task duration, shuffle read/write, executor memory spill
API Layer	Response codes breakdown (2xx, 4xx, 5xx), rate-limited requests

✅ 4. Infrastructure & Cluster Health

Service	Key Indicators
Kubernetes	Pod restarts, node CPU/mem pressure, eviction count
Disk Space	Free space per node, inode usage
GC Behavior	GC frequency, full GC %, pause durations
Auto-scaling Logs	Scale-up/down events, throttle rates

✅ 5. Stability & Reliability Metrics

Category	Why It Matters
Test Flakiness Rate	Detects inconsistent behavior under load
Success % under chaos	How gracefully does the system degrade?
Retry Count / Circuit Breaker Trips	Signals downstream failures under load
Service Uptime %	Validates HA/resilience against failures

🔧 How I Collect & Analyze Metrics

• Test Harness Integration: I integrate metrics collection directly into test frameworks (e.g., expose custom Prometheus counters in Java test harness).

• Dashboards: Build tailored Grafana dashboards for real-time observability of test runs.

• Thresholds & SLOs: Define thresholds for acceptable P95 latency, error rate, and resource usage — any breach flags a performance regression.

• Baseline Comparison: Run nightly jobs to compare metrics vs. last known good release and flag deltas.

Performance testing with Vegeta

Load testing is an important part of releasing a reliable API or application. Vegeta load testing will give you the confidence that the application will work well under a defined load. In this post, we will discuss how to use Vegeta for your load testing needs with some GET request examples. As it is just a go binary it is much easier to set up and use than you think, let's get started.

What is Load testing?

Load testing in plain terms means testing an application by simulating some concurrent requests to determine the behavior of the application in the real world like scenario. Basically, it tests how the application will respond when multiple simultaneous users try to use the application.

There are many ways to load test applications/APIs and Vegeta is one of the easiest tools to perform load testing on your APIs or applications.

Prerequisites for this tutorial

Before jumping on the main topic let’s look at some prerequisites:

• You are good with using the command line (installing and executing CLI apps)
• Your application/API is deployed on a server (staging/production) to test it. Local tests are fine too still they might not give an accurate picture of how the server will behave on load.
• You have some experience with load testing (may be used locust or Jmeter in the past)

Alternatives and why Vegeta

Load testing can be done in multiple ways, there are many different SAAS for load testing too. Still, locally installed tools are a great way to load test your application or API. I have used Locust in the past. The setup and execution are not as easy and straightforward as Vegeta.

Another option is to go with JMeter. Apache JMeter is a fully-featured load testing tool which also translates to knowing its concepts and having a steep learning curve.

Vegeta is a go-lang binary (and library) so installing and using it is a breeze. There are not many concepts to understand and learn.

To start with, simply provide a URL and give it how many requests per second you want the URL to be hit with. Vegeta will hit the URL with the frequency provided and can give the HTTP response codes and response time in an easy to comprehend graph.

The best thing about Vegeta is there is no need to install python or Java to get started. Next, let’s install Vegeta to begin Vegeta load testing.

Install Vegeta

Let us look at the official way Vegeta define itself:

Vegeta is a versatile HTTP load testing tool built out of a need to drill HTTP services with a constant request rate. It can be used both as a command-line utility and a library.

The easiest way to begin load testing with Vegeta is to download the right executable from its GitHub releases page. At the time of writing, the current version is v12.8.3.

Install on Linux

If you are on a 64-bit Linux you can make Vegeta work with the following set of commands:

cd ~/downloads

wget https://github.com/tsenart/vegeta/releases/download/v12.8.3/vegeta-12.8.3-linux-amd64.tar.gz

tar -zxvf vegeta-12.8.3-linux-amd64.tar.gz

chmod +x vegeta

./vegeta --version

If you want to execute Vegeta from any path, you can add a symlink to your path executing a command like ln -s ~/downloads/vegeta ~/bin/vegeta , then it will work on a new CLI tab.

Install on Mac

You can also install Vegeta on a Mac with the following command:

brew update && brew install vegeta

If you already have go-lang installed on your machine and GOBIN in your PATH, you can try to start your Vegeta load testing journey:

go get -u github.com/tsenart/vegeta

Check if it installed properly with:

vegeta --version

You should see a version number displayed.

Your first Vegeta load testing command

There are multiple ways to use the Vegeta load testing tool, one of the simplest ways to get the output on the command line for faster analysis. To your first Vegeta load testing command execute the following:

echo "GET http://httpbin.org/get" | vegeta attack -duration=5s -rate=5 | vegeta report --type=text

So what just happened here?

1. We echoed the URL in this case httpbin.org/get and we passed it through Vegeta attack
2. vegeta attack is the main command that ran the Vegeta load test with 5 requests per second for 5 seconds
3. The last but equally important command executed was vegeta report get show the report of the attack as text.

You can see a sample output below:

Vegeta load testing tool ran the attack of 25 requests spread over 5 seconds at 5 RPS. The minimum response time was 240 ms and the maximum was 510 ms with a 100% success rate. This means all the requests came back as a 200. Further, let's have a look at how we can see a more graphical output.

Vegeta Load testing with graphical output

Another representation of Vegeta load testing results is an easy to understand graph. We can get a graph output with the below command:

cd && echo "GET http://httpbin.org/get" | vegeta attack -duration=30s -rate=10 -output=results-veg-httpbin-get.bin && cat results-veg-httpbin-get.bin | vegeta plot --title="HTTP Bin GET 10 rps for 30 seconds" > http-bin-get-10rps-30seconds.html

Let’s analyze how we used Vegeta for load testing httpbin.org here:

1. We went to the user home with cd command
2. Then we set up the URL for vegeta attack by echoing GET http://httpbin.org/get
3. This step is when we “attack” (a.k.a load test) httpbin servers at 10 requests per second for 30 seconds duration (so in total 300 requests in 30 seconds) we also specified that we want the output at results-vegeta-httbin-get.bin file
4. Now this result is like a binary that can’t be read easily so the next thing is we read the contents of this binary file with cat and passed it to vegeta plot with a fancy title and filename to get the HTML file
5. When we open the created HTML file we can see a graph like below in the HTML file:

So we sent 300 requests and all of them came back with a 200, the max response time was 552 milliseconds. One of the fastest response times was 234 milliseconds. This gives us a clear picture that HTTP bin can easily handle 10 requests per second for 30 seconds.

I would advise you to not try it many times, HTTPBin.org might block your IP thinking you are DDOSing their system.

Generally, you get the idea of how you use Vegeta for load testing your own services.

My service uses an Auth token

Well, all the services won’t be open to all, most will use a JWT or some other way to authenticate and authorize users. To test such services you can use a command like below:

cd && echo "GET http://httpbin.org/get" | vegeta attack -header "authorization: Bearer <your-token-here>" -duration=40s -rate=10 -output=results-veg-token.bin && cat results-veg-token.bin | vegeta plot --title="HTTP Get with token" > http-get-token.html

This example uses the same pattern as the above one, the main difference here is the use of -header param in the vegeta attack command used for Vegeta load testing.

If you want to test an HTTP POST with a custom body please refer to the Vegeta docs. It is best to test the GET APIs to know the load unless you have a write-heavy application/API.

How do I load test multiple URLs?

Testing multiple URLs with different HTTP methods is also relatively easy with Vegeta. Let’s have a look at this in the example below with a couple of GET requests:

1. Create a targets.txt file (filename can be anything) with content like below that has a list of your URLs prefixed by the HTTP verb. In the one below I am load testing 3 GET URLs

                            GET http://httpbin.org/get

                            GET http://httpbin.org/ip

     

1. Now similar to the first example with the text output run this command in the folder the targets.txt file is created: vegeta attack -duration=5s -rate=5 --targets=targets.txt | vegeta report --type=text
2. We will see a text output like below:

As we have seen doing load testing on multiple URLs with Vegeta is a breeze. Vegeta load testing can easily be done for other HTTP verbs like POST and PUT. Please refer to Vegeta docs.

Conclusion

This post was like scratching the surface with a primer on load testing with Vegeta. There are many advanced things that can be done with Vegeta load testing. Vegeta has been very useful on multiple occasions. I had once used Vegeta to load test Google Cloud Functions and Google Cloud Run with the same code to see the response time difference between those two for a talk. The graph comparing both the services made the difference crystal clear.

In another instance, we tested a new public-facing microservice that was replacing a part of an old monolith. It was very useful doing Vegeta load testing to know the response time difference for similar Request Per Second loads.

Load testing the application or API you want to go to production with is crucial.

We once had to open up an API to a much higher load than it would normally get. Our load testing with Vegeta really helped us determine the resources and level of horizontal scaling the API would need to work without issue.

All thanks to Vegeta it was much easier than using another tool or service.