Benchmarking Stirling-PDF Performance: Analyzing CPU and RAM Impact During Batch Document Conversions

Introduction

When deploying self-hosted document processing tools, understanding the underlying resource requirements is critical for maintaining system stability. Stirling-PDF has become a popular choice for developers needing a robust, local alternative to cloud-based PDF APIs. However, because PDF manipulation—such as merging, splitting, or OCR processing—is computationally expensive, it is essential to quantify Stirling-PDF performance before moving to a production environment. This article explores how Stirling-PDF behaves under load, how to measure its resource consumption, and how to tune your infrastructure to handle batch conversions efficiently.

Understanding the Stirling-PDF Architecture

Stirling-PDF is a Java-based application that leverages various libraries to perform document operations. Because it runs on the Java Virtual Machine (JVM), its performance characteristics are tied to memory management, garbage collection, and CPU-bound tasks like image rendering or text extraction. When you trigger a batch conversion, the application spawns worker threads to handle the workload. If you are running this in a containerized environment, these threads compete for the host's physical resources.

Unlike simple web services that are mostly I/O-bound, PDF processing is heavily CPU-bound. Operations like converting a high-resolution image-heavy PDF to a searchable format via OCR will pin CPU cores at 100% until the task completes. Understanding this is the first step in avoiding bottlenecks.

Setting Up a Benchmarking Environment

To accurately measure Stirling-PDF performance, you need a controlled environment. We will use a Docker-based setup on a Linux host. Ensure you have docker and docker-compose installed. For monitoring, we will use docker stats for real-time observation and cAdvisor or netdata for historical data.

The Docker Compose Configuration

Create a docker-compose.yml file to spin up your instance. We will explicitly define resource limits to observe how the application behaves when constrained.

version: '3.8'
services:
  stirling-pdf:
    image: frooodle/stirling-pdf:latest
    ports:
      - "8080:8080"
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
    environment:
      - DOCKER_ENABLE_SECURITY=false

Deploy this with docker-compose up -d. This configuration limits the container to two CPU cores and 2GB of RAM, which is a common starting point for small-to-medium self-hosted deployments.

Measuring CPU and RAM Impact

To benchmark the system, we need a representative workload. Create a folder containing 50 multi-page PDF documents. We will use a simple shell script to hit the Stirling-PDF API repeatedly to simulate a batch conversion task.

The Benchmarking Script

This script uses curl to send files to the /api/v1/merge endpoint. It measures the time taken for each request.

#!/bin/bash
for i in {1..50}; do
  start_time=$(date +%s%3N)
  curl -X POST -F 'files=@sample.pdf' http://localhost:8080/api/v1/merge > /dev/null
  end_time=$(date +%s%3N)
  echo "Request $i took $((end_time - start_time))ms"
done

While this script runs, execute docker stats in another terminal. You will notice that as the number of concurrent requests increases, the CPU usage will hit the 2.0 limit defined in our compose file, and memory usage will likely climb as the JVM allocates heap space for processing.

Analyzing Performance Bottlenecks

CPU Saturation

When CPU usage hits the limit, you will observe an increase in latency. The JVM's thread pool will queue incoming requests, leading to a backlog. If your tasks are time-sensitive, you may need to increase the CPU limit or scale horizontally by using a load balancer and multiple Stirling-PDF instances. Refer to scaling-pdf-processing-stirling-pdf-redis for details on handling high-volume queues.

Memory Pressure

PDF processing is memory-intensive because the application must load the document into memory to manipulate its structure. If you notice the container restarting, it is likely hitting the OOM (Out of Memory) killer. You can diagnose this by checking the container logs or using dmesg on the host. If you see frequent garbage collection pauses, you may need to adjust the JVM heap size using the JAVA_OPTS environment variable.

Optimizing for Production

To improve Stirling-PDF performance in production, consider the following strategies:

1. JVM Tuning: Adjust the initial and maximum heap size (-Xms and -Xmx) to prevent the JVM from constantly resizing the heap during large batch jobs.
2. Resource Allocation: If you are running multiple services on one host, use cgroups to ensure Stirling-PDF has guaranteed CPU shares.
3. Storage Latency: Ensure your PDFs are stored on fast SSD storage. Reading and writing large files to slow network-attached storage (NAS) will introduce significant I/O wait times, which are often mistaken for CPU bottlenecks.
4. Queueing: For extremely high volumes, do not send requests directly to the API. Instead, use a task queue like RabbitMQ or Redis to buffer requests, allowing the PDF processor to work through them at a sustainable rate.

Verifying Improvements

After applying optimizations, rerun the benchmarking script. Compare the average request time and the standard deviation. A successful optimization should result in a lower average latency and, more importantly, a more consistent response time across all 50 requests. If you are using monitor-postgresql-with-netdata or a similar monitoring stack, verify that the CPU usage spikes are now within the expected range for your hardware.

Conclusion

Benchmarking Stirling-PDF performance is essential for any developer looking to integrate document processing into their infrastructure. By understanding the relationship between CPU-bound PDF operations and JVM memory management, you can effectively size your containers and avoid common pitfalls. Always start with a baseline, monitor your resource usage under load, and tune your JVM and container limits iteratively to find the sweet spot for your specific workload.