mirrors/mongodb
mirrors/mongodb
0
0
Fork 0
mirror of https://github.com/mongodb/mongo.git synced 2024-11-25 09:19:32 +01:00
Code Issues Releases Activity
d5ff440817
mongodb/docs/fail_points.md
Ben Caimano a3f092645d SERVER-48727 Document Internal Failpoints
2020-09-17 19:33:21 +00:00

3.3 KiB
Raw Blame History

Fail Points

Fail points 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 or the fail point tests.

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 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. For the command implementations, see here.

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.