Check API - Revision history

Devdocsbot: Protected "Check API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-06-23T23:57:11Z

Protected "Check API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision		Revision as of 23:57, 23 June 2022
(No difference)

Devdocsbot: Update migration status and path

2022-06-23T23:55:21Z

Update migration status and path

← Older revision		Revision as of 23:55, 23 June 2022
Line 1:		Line 1:
			{{Template:Migrated\|newDocId=/docs/apis/subsystems/check/}}
	{{Moodle 3.9}}		{{Moodle 3.9}}
	== Checks ==		== Checks ==

Brendanheywood: /* The result summary */

2022-05-11T03:07:30Z

The result summary

← Older revision		Revision as of 03:07, 11 May 2022
Line 125:		Line 125:
	=== The result summary ===		=== The result summary ===
	The summary could change depending on the result of the check but for a simple check might be a fixed string, not html. Try to keep the summary to 1 line as this might typically be the thing which gets passed through to a paging system and could be truncated.		The summary could change depending on the result of the check but for a simple check might be a fixed string, not html. Try to keep the summary to 1 line as this might typically be the thing which gets passed through to a paging system and could be truncated.

			=== The details ===
			Unlike the summary the details is allowed and encouraged to be html. Often it will be a bullet list of a table of the things that it asserted which make up the check.

	=== The action link ===		=== The action link ===
	The action link is the place to go to help fix the issue. It should be as specific as possibly, such as a deep link into an admin settings page, and can include hash anchors.		The action link is the place to go to help fix the issue. It should be as specific as possibly, such as a deep link into an admin settings page, and can include hash anchors.

Brendanheywood: /* Status checks (status) */

2022-03-15T22:35:48Z

Status checks (status)

Show changes

Stronk7: fix link

2022-01-31T08:59:08Z

fix link

← Older revision		Revision as of 08:59, 31 January 2022
Line 6:		Line 6:
	https://tracker.moodle.org/browse/MDL-67818		https://tracker.moodle.org/browse/MDL-67818

	A Check is a runtime test to make sure something is working well. You can think of Checks as similar and complimentary to the [[~~Unit_test_API~~]] and [[Acceptance_testing]] but the next layer around them, and done at run time rather than dev time or build time. Like other forms of testing the tests themselves should easy to read and reason about and confirm as valid. As many types of runtime checks can't be unit tested, the checks '''are''' the test.		A Check is a runtime test to make sure something is working well. You can think of Checks as similar and complimentary to the [[PHPUnit]] and [[Acceptance_testing]] but the next layer around them, and done at run time rather than dev time or build time. Like other forms of testing the tests themselves should easy to read and reason about and confirm as valid. As many types of runtime checks can't be unit tested, the checks '''are''' the test.

	Checks can be used for a variety of purposes including:		Checks can be used for a variety of purposes including:

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T19:17:15Z
Text replacement - "<code bash>" to "<syntaxhighlight lang="bash">"

				
				
				
				
				
				← Older revision
				Revision as of 19:17, 14 July 2021
				
Line 24:
Line 24:
Having these centralized and with a consistent contract makes it much easier to ensure the whole system is running smoothly. This makes it possible for an external integration with monitoring systems such as Nagios / Icinga. The Check API is expose as an NPRE compliance cli script: Having these centralized and with a consistent contract makes it much easier to ensure the whole system is running smoothly. This makes it possible for an external integration with monitoring systems such as Nagios / Icinga. The Check API is expose as an NPRE compliance cli script:



<code bash> <syntaxhighlight lang="bash">
php admin/cli/checks.php php admin/cli/checks.php
</syntaxhighlight> </syntaxhighlight>



Mudrd8mz: Text replacement - "" to ""

2021-07-14T13:33:09Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:33, 14 July 2021
				
Line 120:
Line 120:
And make a new check class in mod/myplugin/classes/check/foobar.php and the only mandatory method is get_result(). By default it will use a set language string but you can override the get_name() method to reuse an existing string. And make a new check class in mod/myplugin/classes/check/foobar.php and the only mandatory method is get_result(). By default it will use a set language string but you can override the get_name() method to reuse an existing string.



<code php> <syntaxhighlight lang="php">
$string['checkfoobar'] = 'Check the foos to make sure they are barred'; $string['checkfoobar'] = 'Check the foos to make sure they are barred';
</syntaxhighlight> </syntaxhighlight>



<code php> <syntaxhighlight lang="php">
<?php <?php
namespace mod_myplugin\check; namespace mod_myplugin\check;
Line 168:
Line 168:
/mod/myplugin/lib.php /mod/myplugin/lib.php



<code php> <syntaxhighlight lang="php">
function mod_myplugin_security_checks() { function mod_myplugin_security_checks() {
     return [new mod_myplugin\check\foobar()];      return [new mod_myplugin\check\foobar()];
Line 180:
Line 180:
If you plan to return multiple instances of a check class, make sure that each instance has a unique id. If you plan to return multiple instances of a check class, make sure that each instance has a unique id.



<code php> <syntaxhighlight lang="php">
function mod_myplugin_security_checks() { function mod_myplugin_security_checks() {
     return [      return [
Line 217:
Line 217:
Checks can provide details on a check, such as the complete list of bad records. Generally this type of information might be expensive to produce so you can defer this lookup until get_details() is called specifically rather than setting this in the constructor. It will only be loaded on demand and shown when you drill down into the check details page. Checks can provide details on a check, such as the complete list of bad records. Generally this type of information might be expensive to produce so you can defer this lookup until get_details() is called specifically rather than setting this in the constructor. It will only be loaded on demand and shown when you drill down into the check details page.



<code php> <syntaxhighlight lang="php">
<?php <?php
namespace mod_myplugin\check; namespace mod_myplugin\check;
Line 230:
Line 230:






<code php> <syntaxhighlight lang="php">
class foobar_result extends \core\check\result { class foobar_result extends \core\check\result {
     ...      ...





Mudrd8mz: Text replacement - "" to ""
2021-07-14T13:03:32Z
Text replacement - "</code>" to "</syntaxhighlight>"

				
				
				
				
				
				← Older revision
				Revision as of 13:03, 14 July 2021
				
Line 26:
Line 26:
<code bash> <code bash>
php admin/cli/checks.php php admin/cli/checks.php
</code> </syntaxhighlight>



== Result states of a check == == Result states of a check ==
Line 122:
Line 122:
<code php> <code php>
$string['checkfoobar'] = 'Check the foos to make sure they are barred'; $string['checkfoobar'] = 'Check the foos to make sure they are barred';
</code> </syntaxhighlight>



<code php> <code php>
Line 148:
Line 148:
     }      }
} }
</code> </syntaxhighlight>



=== The result summary === === The result summary ===
Line 172:
Line 172:
     return [new mod_myplugin\check\foobar()];      return [new mod_myplugin\check\foobar()];
} }
</code> </syntaxhighlight>



=== Multiple instances of checks === === Multiple instances of checks ===
Line 187:
Line 187:
     ];      ];
} }
</code> </syntaxhighlight>



Set the internal id in a way which is unique across all instances in your components namespace: Set the internal id in a way which is unique across all instances in your components namespace:
Line 206:
Line 206:
     ...      ...
} }
</code> </syntaxhighlight>



=== Make checks as fast as practical === === Make checks as fast as practical ===
Line 227:
Line 227:
     }      }
} }
</code> </syntaxhighlight>






Line 237:
Line 237:
     }      }
} }
</code> </syntaxhighlight>



For a real example see: For a real example see:





Mudrd8mz: Text replacement - "

" to ""

2021-07-14T13:02:47Z
Text replacement - "<code php>  " to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:02, 14 July 2021
				
Line 191:
Line 191:
Set the internal id in a way which is unique across all instances in your components namespace: Set the internal id in a way which is unique across all instances in your components namespace:



<code php> <syntaxhighlight lang="php"><?php
  
<?php 
namespace mod_myplugin\check; namespace mod_myplugin\check;
use core\check\check; use core\check\check;





Tsala: see also link to user docs
2020-08-04T08:54:49Z
see also link to user docs

				
				
				
				
				
				← Older revision
				Revision as of 08:54, 4 August 2020
				
Line 248:
Line 248:



Some checks are by their nature asynchronous. For instance having moodle send an email to itself and then having it processed by the inbound mail handler to make it's properly configured (see https://tracker.moodle.org/browse/MDL-48800). In cases like these please make sure the age or staleness of the check is shown in the summary, and you should also consider turning the result status into a warning if the result is too old. If appropriate make the threshold a configurable admin setting. Some checks are by their nature asynchronous. For instance having moodle send an email to itself and then having it processed by the inbound mail handler to make it's properly configured (see https://tracker.moodle.org/browse/MDL-48800). In cases like these please make sure the age or staleness of the check is shown in the summary, and you should also consider turning the result status into a warning if the result is too old. If appropriate make the threshold a configurable admin setting.

==See also==

* [[:en:Performance overview|Performance overview]] user docs

← Older revision		Revision as of 19:17, 14 July 2021
Line 24:		Line 24:
	Having these centralized and with a consistent contract makes it much easier to ensure the whole system is running smoothly. This makes it possible for an external integration with monitoring systems such as Nagios / Icinga. The Check API is expose as an NPRE compliance cli script:		Having these centralized and with a consistent contract makes it much easier to ensure the whole system is running smoothly. This makes it possible for an external integration with monitoring systems such as Nagios / Icinga. The Check API is expose as an NPRE compliance cli script:

	<~~code~~ bash>		<syntaxhighlight lang="bash">
	php admin/cli/checks.php		php admin/cli/checks.php
	</syntaxhighlight>		</syntaxhighlight>

← Older revision		Revision as of 13:33, 14 July 2021
Line 120:		Line 120:
	And make a new check class in mod/myplugin/classes/check/foobar.php and the only mandatory method is get_result(). By default it will use a set language string but you can override the get_name() method to reuse an existing string.		And make a new check class in mod/myplugin/classes/check/foobar.php and the only mandatory method is get_result(). By default it will use a set language string but you can override the get_name() method to reuse an existing string.

	<~~code~~ php>		<syntaxhighlight lang="php">
	$string['checkfoobar'] = 'Check the foos to make sure they are barred';		$string['checkfoobar'] = 'Check the foos to make sure they are barred';
	</syntaxhighlight>		</syntaxhighlight>

	<~~code~~ php>		<syntaxhighlight lang="php">
	<?php		<?php
	namespace mod_myplugin\check;		namespace mod_myplugin\check;
Line 168:		Line 168:
	/mod/myplugin/lib.php		/mod/myplugin/lib.php

	<~~code~~ php>		<syntaxhighlight lang="php">
	function mod_myplugin_security_checks() {		function mod_myplugin_security_checks() {
	return [new mod_myplugin\check\foobar()];		return [new mod_myplugin\check\foobar()];
Line 180:		Line 180:
	If you plan to return multiple instances of a check class, make sure that each instance has a unique id.		If you plan to return multiple instances of a check class, make sure that each instance has a unique id.

	<~~code~~ php>		<syntaxhighlight lang="php">
	function mod_myplugin_security_checks() {		function mod_myplugin_security_checks() {
	return [		return [
Line 217:		Line 217:
	Checks can provide details on a check, such as the complete list of bad records. Generally this type of information might be expensive to produce so you can defer this lookup until get_details() is called specifically rather than setting this in the constructor. It will only be loaded on demand and shown when you drill down into the check details page.		Checks can provide details on a check, such as the complete list of bad records. Generally this type of information might be expensive to produce so you can defer this lookup until get_details() is called specifically rather than setting this in the constructor. It will only be loaded on demand and shown when you drill down into the check details page.

	<~~code~~ php>		<syntaxhighlight lang="php">
	<?php		<?php
	namespace mod_myplugin\check;		namespace mod_myplugin\check;
Line 230:		Line 230:


	<~~code~~ php>		<syntaxhighlight lang="php">
	class foobar_result extends \core\check\result {		class foobar_result extends \core\check\result {
	...		...

← Older revision		Revision as of 13:03, 14 July 2021
Line 26:		Line 26:
	<code bash>		<code bash>
	php admin/cli/checks.php		php admin/cli/checks.php
	</~~code~~>		</syntaxhighlight>

	== Result states of a check ==		== Result states of a check ==
Line 122:		Line 122:
	<code php>		<code php>
	$string['checkfoobar'] = 'Check the foos to make sure they are barred';		$string['checkfoobar'] = 'Check the foos to make sure they are barred';
	</~~code~~>		</syntaxhighlight>

	<code php>		<code php>
Line 148:		Line 148:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	=== The result summary ===		=== The result summary ===
Line 172:		Line 172:
	return [new mod_myplugin\check\foobar()];		return [new mod_myplugin\check\foobar()];
	}		}
	</~~code~~>		</syntaxhighlight>

	=== Multiple instances of checks ===		=== Multiple instances of checks ===
Line 187:		Line 187:
	];		];
	}		}
	</~~code~~>		</syntaxhighlight>

	Set the internal id in a way which is unique across all instances in your components namespace:		Set the internal id in a way which is unique across all instances in your components namespace:
Line 206:		Line 206:
	...		...
	}		}
	</~~code~~>		</syntaxhighlight>

	=== Make checks as fast as practical ===		=== Make checks as fast as practical ===
Line 227:		Line 227:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>


Line 237:		Line 237:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	For a real example see:		For a real example see:

← Older revision		Revision as of 13:02, 14 July 2021
Line 191:		Line 191:
	Set the internal id in a way which is unique across all instances in your components namespace:		Set the internal id in a way which is unique across all instances in your components namespace:

	<~~code~~ php>		<syntaxhighlight lang="php"><?php

	<?php
	namespace mod_myplugin\check;		namespace mod_myplugin\check;
	use core\check\check;		use core\check\check;

← Older revision		Revision as of 08:54, 4 August 2020
Line 248:		Line 248:

	Some checks are by their nature asynchronous. For instance having moodle send an email to itself and then having it processed by the inbound mail handler to make it's properly configured (see https://tracker.moodle.org/browse/MDL-48800). In cases like these please make sure the age or staleness of the check is shown in the summary, and you should also consider turning the result status into a warning if the result is too old. If appropriate make the threshold a configurable admin setting.		Some checks are by their nature asynchronous. For instance having moodle send an email to itself and then having it processed by the inbound mail handler to make it's properly configured (see https://tracker.moodle.org/browse/MDL-48800). In cases like these please make sure the age or staleness of the check is shown in the summary, and you should also consider turning the result status into a warning if the result is too old. If appropriate make the threshold a configurable admin setting.

			==See also==

			* [[:en:Performance overview\|Performance overview]] user docs

Check API - Revision history

Devdocsbot: Protected "Check API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

Devdocsbot: Update migration status and path

Brendanheywood: /* The result summary */

Brendanheywood: /* Status checks (status) */

Stronk7: fix link

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - " " to ""

Tsala: see also link to user docs

Mudrd8mz: Text replacement - "`" to ""`

Mudrd8mz: Text replacement - "`" to ""`

`Mudrd8mz: Text replacement - "`" to ""

Mudrd8mz: Text replacement - "`" to ""`