From f2130fd0d7b97d81e0dc95341ea5b63ad2773feb Mon Sep 17 00:00:00 2001 From: Jean Boussier Date: Tue, 19 Sep 2023 14:22:51 +0200 Subject: [PATCH] Add a Why Migrate? guide I didn't want to open the can of worm of comparison tables with other servers, but I've received some comments that suggest it may be a good idea to more clearly state the expected tradeoffs to manage expectations. --- README.md | 14 +++++++ docs/WHY_MIGRATE.md | 93 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 docs/WHY_MIGRATE.md diff --git a/README.md b/README.md index b9af1035..91212d20 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,23 @@ both the request and response in between `pitchfork` and slow clients. or ports yourself. `pitchfork` can spawn and manage any number of worker processes you choose to scale to your backend. +* Adaptative timeout: request timeout can be extended dynamically on a + per request basis, which allows to keep a strict overall timeout for + most endpoints, but allow a few endpoints to take longer. + * Load balancing is done entirely by the operating system kernel. Requests never pile up behind a busy worker process. +## When to Use + +Pitchfork isn't inherently better than other Ruby application servers, it mostly +focus on different tradeoffs. + +If you are fine with your current server, it's best to stick with it. + +If there is a problem you are trying to solve, please read the +[migration guide](docs/WHY_MIGRATE.md) first. + ## Requirements Ruby(MRI) Version 2.5 and above. diff --git a/docs/WHY_MIGRATE.md b/docs/WHY_MIGRATE.md new file mode 100644 index 00000000..e55582fb --- /dev/null +++ b/docs/WHY_MIGRATE.md @@ -0,0 +1,93 @@ +# Why migrate to Pitchfork? + +First and foremost, if you don't have any specific problem with your current server, then don't. + +Pitchfork isn't a silver bullet, it's a very opinionated software that focus on very specific tradeoffs, +that are different from other servers. + +## Coming from Unicorn + +### Why Migrate? + +#### Adaptative timeout + +Pitchfork allows to extend the request timeout on a per request basis, +this can be helpful when trying to reduce the global request timeout +to a saner value. You can enforce a stricter value, and extend it +in the minority of offending endpoints. + +#### Memory Usage - Reforking + +If you are unsatisfied with Unicorn memory usage, but threaded Puma isn't an option +for you, then Pitchfork may be an option if you are able to enable reforking. + +However be warned that making an application fork safe can be non-trivial, +and mistakes can lead to critical bugs. + +#### Rack 3 + +As of Unicorn `6.1.0`, Rack 3 isn't yet supported by Unicorn. + +Pitchfork is compatible with Rack 3. + +### Why Not Migrate? + +#### Reduced Features + +While Pitchfork started as a fork of Unicorn, many features such as daemonization, +pid file management, hot reload have been stripped. + +Pitchfork only kept features that makes sense in a containerized world. + +## Coming from Puma + +Generally speaking, compared to (threaded) Puma, Pitchfork *may* offer better latency and isolation at the expense of throughput. + +### Why Migrate? + +#### Latency + +If you suspect your application is subject to contention on the GVL or some other in-process shared resources, +then Pitchfork may offer improved latency. + +It is however heavily recommended to first confirm this suspicion with profiling +tools such as [gvltools](https://github.com/Shopify/gvltools). + +If you application isn't subject to in-process contention, Pitchfork is unlikely to improve latency. + +#### Out of Band Garbage Collection + +Another advantage of only processing a single request per process is that +[it allows to periodically trigger garbage collection when the worker isn't processing any request](https://shopify.engineering/adventures-in-garbage-collection). + +This can significantly improve tail latency at the expense of throughput. + +#### Resiliency and Isolation + +Since Pitchfork workers have their own address space and only process one request at a time +it makes it much harder for one faulty request to impact another. + +Even if a bug causes Ruby to crash, only the request that triggered the bug will be impacted. + +If a bug causes Ruby to hang, the monitor process will SIGKILL the worker and the capacity will be +reclaimed. + +This makes Pitchfork more resilient to some classes of bugs. + +#### Thread Safety + +Pitchfork doesn't require applications to be thread-safe. That is probably the worst reason +to migrate though. + +### Why Not Migrate? + +#### Memory Usage + +Without reforking enabled Pitchfork will without a doubt use more memory than threaded Puma. + +With reforking enabled, results will vary based on the application profile and the number of Puma threads, +but should be in the same ballpark, sometimes better, but likely worse, this depends on many variables and +can't really be predicted. + +However be warned that [making an application fork safe](FORK_SAFETY.md) can be non-trivial, +and mistakes can lead to critical bugs.