SERVER-48727 Document Internal Failpoints

2 files changed, 60 insertions, 1 deletions

diff --git a/docs/fail_points.md b/docs/fail_points.md
new file mode 100644
index 00000000000..e3ef1387b6b
--- /dev/null
+++ b/docs/fail_points.md
@@ -0,0 +1,58 @@
+# Fail Points
+
+[Fail points][fail_point] are test-only configurable hooks that can be triggered at runtime. Fail
+points allow tests to change behavior at pre-defined points to block threads, choose rarely executed
+branches, enhance diagnostics, or achieve any number of other aims. Fail points can be enabled,
+configured, and disabled via command request to a remote process or via an API within the same
+process.
+
+## Using Fail Points
+
+A fail point must first be defined using `MONGO_FAIL_POINT_DEFINE(myFailPoint)`. This statement
+adds the fail point to a registry and allows it to be evaluated in code. There are three common
+patterns for evaluating a fail point:
+- Exercise a rarely used branch:
+  `if (whenPigsFly || myFailPoint.shouldFail()) { ... }`
+- Block until the fail point is unset:
+  `myFailPoint.pauseWhileSet();`
+- Use the fail point's payload to perform custom behavior:
+  `myFailPoint.execute([](const BSONObj& data) { useMyPayload(data); };`
+
+For more complete usage, see the [fail point header][fail_point] or the [fail point
+tests][fail_point_test].
+
+## Configuring and Waiting on Fail Points
+
+Fail point configuration involves chosing a "mode" for activation (e.g., "alwaysOn") and optionally
+providing additional data in the form of a BSON object. For the vast majority of cases, this is done
+by issuing a `configureFailPoint` command request. This is made easier in JavaScript using the
+`configureFailPoint` helper from [fail_point_util.js][fail_point_util]. Fail points can also be
+useful in C++ unit tests and integration tests. To configure fail points on the local process, use
+a `FailPointEnableBlock` to enable and configure the fail point for a given block scope. Finally,
+a fail point can also be set via setParameter by its name prefixed with "failpoint." (e.g.,
+"failpoint.myFailPoint").
+
+Users can also wait until a fail point has been evaluated a certain number of times ***over its
+lifetime***. A `waitForFailPoint` command request will send a response back when the fail point has
+been evaluated the given number of times. For ease of use, the `configureFailPoint` JavaScript
+helper returns an object that can be used to wait a certain amount of times ***from when the fail
+point was enabled***. In C++ tests, users can invoke `FailPoint::waitForTimesEntered()` for similar
+behavior. `FailPointEnableBlock` records the amount of times the fail point had been evaluated when
+it was constructed, accessible via `FailPointEnableBlock::initialTimesEntered()`.
+
+For JavaScript examples, see the [fail point JavaScript test][fail_point_javascript_test]. For the
+command implementations, see [here][fail_point_commands].
+
+## The `failCommand` Fail Point
+
+The `failCommand` fail point is an especially developed fail point used to mock arbitrary response
+behaviors to requests filtered by command, appName, etc. It is most often used to simulate specific
+conditions between nodes like invalid replica set configurations. For examples of use, see the
+[failCommand JavaScript tests][fail_command_javascript_test].
+
+[fail_point]: ../src/mongo/util/fail_point.h
+[fail_point_test]: ../src/mongo/util/fail_point_test.cpp
+[fail_point_commands]: ../src/mongo/db/commands/fail_point_cmd.cpp
+[fail_point_util]: ../jstests/libs/fail_point_util.js
+[fail_point_javascript_test]: ../jstests/fail_point/fail_point.js
+[fail_command_javascript_test]: ../jstests/core/failcommand_failpoint.js
diff --git a/docs/index.md b/docs/index.md
index 451eb5f682a..fd7807cd849 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -9,7 +9,8 @@ For the full MongoDB docs, please see [mongodb.org](http://www.mongodb.org/)
 * [Command Dispatch](command_dispatch.md)
 * [Egress Networking](egress_networking.md)
 * [Exception Architecture](exception_architecture.md)
+* [Fail Points](fail_points.md)
 * [Memory Management](memory_management.md)
 * [Parsing Stack Traces](parsing_stack_traces.md)
 * [String Manipulation](string_manipulation.md)
-* [MongoDB Voluntary Product Accessibility Template® (VPAT™)](vpat.md)
\ No newline at end of file
+* [MongoDB Voluntary Product Accessibility Template® (VPAT™)](vpat.md)