README

基于简单配置的 CakePHP 3 监控插件

安装

1. 在您的 composer.json 中要求插件

	"require": {
		...
		"scherersoftware/cake-monitor": "dev-master",
		...
	}

2. 使用 composer 包含插件

在项目文件夹中打开终端并运行以下命令

$ composer update
$ composer install

3. 在您的 config/bootstrap.php 中加载插件

Plugin::load('Monitor', ['bootstrap' => true, 'routes' => true]);

4. 在您的 config/app.php 中添加配置

	'CakeMonitor' => [
		'accessToken' => 'Header token (CAKEMONITORTOKEN) used for authentication',
		'projectName' => 'Name of the Cake Project',
		'serverDescription' => 'Identifier of the server - use of env() is recommended',
		'onSuccess' => function() {
			// callback function in case every check was successful
			die('Do things if everything is fine');
		}
	]

注意，Header token（accessToken）是允许访问监控URL所必需的。如果您的检查功能揭示了关于项目的机密信息，请将此令牌视为机密。使用合适的浏览器插件修改HTTP请求头，当您调用监控URL时。

使用方法

默认情况下，此插件会对项目的所有 MySQL 表执行状态检查。此行为可以在 app.php 中被覆盖。

定义自定义检查函数

在您的 app.php 中定义自定义检查函数。检查可以作为数组字段定义，其中包含匿名回调函数。数组 'checks' 与位于 vendor/scherersoftware/cake-monitor/config/monitor.default.php 中的数组合并，该数组包含默认数据库检查函数。

您可以使用该函数作为参考来实现任何检查函数。

'CakeMonitor' => [
	'accessToken' => 'CAKEMONITORTOKEN',
	'projectName' => 'Name of the Cake Project',
	'serverDescription' => 'Identifier of the server - use of env() is recommended',
	'onSuccess' => function() {
		// callback function in case every check was successful
		die('Do things if everything is fine');
	},
	'checks' => [
		'FUNCTION_NAME' => [
			'callback' => function() {
				// your check function
				// see the default 'DATABASE' function for further information
				return true;
			}
		]
	]
]

如果每个检查函数都无异常执行，则调用 'onSuccess' 回调函数。

调用

通过调用以下URL运行当前检查并查看其输出：http://YOUR_PROJECT_URL.tld/monitor

Sentry 错误报告

该插件包含将 CakePHP 的错误报告挂钩并发送异常到出色的错误报告服务 Sentry 的功能。

配置

您的 app.php 中的 CakeMonitor 配置部分必须包含一个 Sentry 键

'Sentry' => [
	'enabled' => !Configure::read('debug'), # Boolean value to enable sentry error reporting
	'dsn' => '', # The DSN for the Sentry project. You find this on the Sentry Project Settings Page.
	'sanitizeFields' => [ # An array of fields, whose values will be removed before sending
						  # data to sentry. Be sure to include fields like session cookie names, 
						  # sensitive environment variables and other private configuration.
		'password',
		'rememberuser',
		'auth_token',
		'api_token',
		'mysql_password',
		'email_password',
		'cookie'
	],
	// Optional callback for special filtering
	'sanitizeExtraCallback' => function (&$data) {
		if (isset($data['user']['id'])) {
			$data['user']['id'] = '*****';
		}
	},
	'extraDataCallback' => function() { # Extra data to send with every Sentry call. Works with SentryHandler::captureMessage() only!
        	if (!empty($_SESSION['Test'])) {
            		return $_SESSION['Test'];
        	}
    	}
]

在您的 bootstrap.php 中，您必须告诉 CakePHP 使用哪个 ErrorHandler。请查找以下部分

/**
 * Register application error and exception handlers.
 */
$isCli = PHP_SAPI === 'cli';
if ($isCli) {
	(new ConsoleErrorHandler(Configure::read('Error')))->register();
} else {
	(new ErrorHandler(Configure::read('Error')))->register();
}

并将其修改如下

/**
 * Register application error and exception handlers.
 */
Plugin::load('Monitor', ['bootstrap' => true, 'routes' => true]); # important for loading and merging the configuration

$isCli = php_sapi_name() === 'cli';
if ($isCli) {
	(new \Monitor\Error\ConsoleErrorHandler(Configure::consume('Error')))->register();
} else {
	(new \Monitor\Error\ErrorHandler(Configure::consume('Error')))->register();
}	 

从现在开始，如果配置值 CakeMonitor.Sentry.enabled 为 true，则错误和异常将报告给 Sentry，而不会更改 CakePHP 的任何默认 ErrorHandler 行为。

如果您使用的是 cake 3.3 及以上版本，您必须使用此插件提供的 ErrorHandlerMiddleware 来启用 Sentry 错误跟踪。

在您的 Application.php 中使用 Monitor\Middleware\ErrorHandlerMiddleware 而不是 Cake\Error\Middleware\ErrorHandlerMiddleware。

示例

将异常记录到 Sentry

$sentryHandler = new SentryHandler();
$sentryHandler->handle($exception);

将消息记录到 Sentry

$sentryHandler = new SentryHandler();
$sentryHandler->captureMessage('Error within request.', null, [
	'extra' => [
		'result' => $result,
		'status' => $status
	]
]);