stayallive/wp-sentry

一个(非官方)WordPress插件,用于向Sentry报告PHP和JavaScript错误。

资助包维护!
stayallive

安装量: 123,048

依赖项: 0

建议者: 0

安全: 0

星标: 300

关注者: 12

分支: 48

开放问题: 1

类型:wordpress-plugin


README

一个(非官方)WordPress插件,用于向Sentry报告PHP和JavaScript错误。

是什么?

此插件可以(可选地)向Sentry报告PHP错误和JavaScript错误,并与其版本跟踪集成。

它将自动检测认证用户,并在可能的情况下添加上下文。所有上下文/标签都可以使用以下提到的过滤器进行调整。

要求

此插件需要PHP 7.2+,但强烈建议用户使用非生命结束(EOL)且不再受支持的PHP版本。有关仍受支持的PHP版本的最新列表,请参阅:https://php.ac.cn/supported-versions.php

  • 此插件的2.1.*版本将是支持PHP 5.3的最后一个版本。
  • 此插件的2.2.*版本将是支持PHP 5.4的最后一个版本。
  • 此插件的3.11.*版本将是支持PHP 7.1的最后一个版本。

注意:版本5.x是wp-sentry插件的最新版本,仅支持PHP 7.2及以上。如果您需要PHP 5.4-7.1的支持,请查看版本2.x3.x,但请注意,Sentry PHP SDK的使用有很多差异。

  • wp-sentry插件的2.x版本使用官方Sentry PHP SDK的1.x版本。
  • wp-sentry插件的3.x版本使用官方Sentry PHP SDK的2.x版本。
  • wp-sentry插件的4.x5.x6.x版本使用官方Sentry PHP SDK的3.x版本。
  • wp-sentry插件的7.x+版本使用官方Sentry PHP SDK的4.x版本。

使用方法

有几个选项可以开始使用此插件。

注意:默认情况下,此插件不会执行任何操作,并且只有诊断管理界面以测试您是否正确设置了DSN并发送测试事件。设置DSN是必需的。

WordPress插件仓库

  1. 从WordPress插件仓库安装此插件:https://wordpress.org/plugins/wp-sentry-integration/
  2. 如配置部分所述配置您的DSN
  3. 通过WordPress管理界面或wp-cli激活插件

手动插件安装

  1. 发布页面下载插件
  2. 解压并将其文件夹放置在您的wp-content/plugins文件夹中
  3. 如配置部分所述配置您的DSN
  4. 通过WordPress管理界面或wp-cli激活插件

使用composer

  1. 在您的项目中运行composer require stayallive/wp-sentry
  2. 如配置部分所述配置您的DSN
  3. 通过WordPress管理界面或wp-cli激活插件

配置

要开始使用此插件,首先为PHP端或浏览器端或两者都设置DSN

所有其他配置选项都是可选的,但建议您阅读它们,看看是否有适用于您或您想配置的项目。

注意:在您的wp-config.php中配置常量时,请将此操作放在That's all, stop editing! Happy publishing.行之前,否则它们将不会生效!

DSN

Sentry使用称为DSN(更多信息)的东西来配置SDK。

WP_SENTRY_PHP_DSN(PHP)

要跟踪PHP错误,请将此片段添加到您的wp-config.php中,并用您在Sentry中项目设置下的“客户端密钥(DSN)”中找到的实际DSN替换PHP_DSN

define( 'WP_SENTRY_PHP_DSN', 'PHP_DSN' );

注意:不要设置此常量以禁用PHP跟踪器。

注意:此常量之前称为WP_SENTRY_DSN,但现在仍然受到支持。

WP_SENTRY_BROWSER_DSN(浏览器)

要跟踪JavaScript错误,请将此片段添加到您的wp-config.php中,并用您在Sentry中项目设置下的“客户端密钥(DSN)”中找到的实际DSN替换JS_DSN

define( 'WP_SENTRY_BROWSER_DSN', 'JS_DSN' );

// You can _optionally_ enable or disable the JavaScript tracker in certain parts of your site with these constants:
define('WP_SENTRY_BROWSER_ADMIN_ENABLED', true);    // Add the JavaScript tracker to the admin area. Default: true
define('WP_SENTRY_BROWSER_LOGIN_ENABLED', true);    // Add the JavaScript tracker to the login page. Default: true
define('WP_SENTRY_BROWSER_FRONTEND_ENABLED', true); // Add the JavaScript tracker to the front end. Default: true

注意:不要设置此常量以禁用JavaScript跟踪器。

注意:此常量之前称为WP_SENTRY_PUBLIC_DSN,但现在仍然受到支持。

隐私

WP_SENTRY_SEND_DEFAULT_PII

如果此标志启用,则由活动集成添加某些可识别的个人身份信息。如果没有此标志,它们从一开始就不会添加到事件中。

如果可能,建议启用此功能并使用服务器端PII剥离来删除值。

启用时,当前登录用户和IP地址将被添加到事件中。

define( 'WP_SENTRY_SEND_DEFAULT_PII', true );

选项

WP_SENTRY_VERSION

定义您网站的版本。默认情况下将使用活动主题的版本,如果无法解析主题版本,则默认为unspecified

这用于跟踪错误发生在您网站的哪个版本。当与发布跟踪结合使用时,这是一个非常强大的功能。

define( 'WP_SENTRY_VERSION', 'v8.1.0' );

WP_SENTRY_ENV

定义您网站的配置环境。默认为wp_get_environment_type()中的WordPress环境类型,如果未配置,则默认为unspecified

这用于跟踪错误发生在您网站的哪个环境中。

define( 'WP_SENTRY_ENV', 'production' );

WP_SENTRY_ERROR_TYPES(PHP)

设置PHP跟踪器将跟踪的错误类型

define( 'WP_SENTRY_ERROR_TYPES', E_ALL & ~E_DEPRECATED & ~E_NOTICE & ~E_USER_DEPRECATED & ~E_USER_NOTICE );

注意:您可以设置任何组合的错误类型,有关更多信息,请参阅PHP文档

设置跟踪

WP_SENTRY_TRACES_SAMPLE_RATE(PHP)

设置性能跟踪所需的采样率。将0.3替换为您想要的采样率(0.3表示采样约30%的流量)

// https://docs.sentry.io/platforms/php/performance/#configure
define( 'WP_SENTRY_TRACES_SAMPLE_RATE', 0.3 ); // traces_sample_rate

启用跟踪还会设置SAVEQUERIES,这可能会使用更多内存来保存您环境中执行的所有查询。如果这不是您想要的,您可以通过配置WP_SENTRY_TRACING_FEATURES来禁用查询跟踪。

注意:不要设置此常量或将采样率设置为0.0以禁用性能监控。

WP_SENTRY_TRACING_FEATURES(PHP)

通过将此片段添加到您的wp-config.php以启用性能监控功能。

define( 'WP_SENTRY_TRACING_FEATURES', [
	'db' => [
		'spans' => true,
		'breadcrumbs' => defined( 'SAVEQUERIES' ) && SAVEQUERIES,
	],
	'http' => [
		'spans' => true,
		'breadcrumbs' => true,
	],
	'transients' => [
		'spans' => true,
		'breadcrumbs' => true,
	],
] );

注意:不配置此常量将默认为上述配置。

WP_SENTRY_BROWSER_TRACES_SAMPLE_RATE(浏览器)

通过将此片段添加到您的wp-config.php并替换0.3为您想要的采样率(0.3表示采样大约30%的流量)来启用JavaScript性能跟踪。

// https://docs.sentry.io/platforms/javascript/performance/#configure-the-sample-rate
define( 'WP_SENTRY_BROWSER_TRACES_SAMPLE_RATE', 0.3 ); // tracesSampleRate

// These options are passed directly to `new BrowserTracing({})`
// define( 'WP_SENTRY_BROWSER_TRACING_OPTIONS', [] );

注意:不要设置此常量或将采样率设置为0.0以禁用JavaScript性能跟踪。

WP_SENTRY_BROWSER_REPLAYS_SESSION_SAMPLE_RATE(浏览器)

通过将此片段添加到您的wp-config.php并替换0.3为您想要的采样率(0.3表示采样大约30%的流量)来启用JavaScript会话回放。

// These options are injected into the `Sentry.init()` call
// https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration
define( 'WP_SENTRY_BROWSER_REPLAYS_SESSION_SAMPLE_RATE', 0.1 ); // replaysSessionSampleRate
define( 'WP_SENTRY_BROWSER_REPLAYS_ON_ERROR_SAMPLE_RATE', 1.0 ); // replaysOnErrorSampleRate

// These options are passed directly to `new Replay({})`
// - https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration
// - https://docs.sentry.io/platforms/javascript/session-replay/privacy/#privacy-configuration
// define( 'WP_SENTRY_BROWSER_SESSION_REPLAY_OPTIONS', [ 'maskAllText' => true ] );

注意:不要设置这些常量或将采样率设置为0.0以禁用JavaScript会话回放。

设置配置文件

WP_SENTRY_PROFILES_SAMPLE_RATE(PHP)

注意:此功能需要安装Excimer PHP扩展。有关更多信息,请参阅Sentry PHP SDK文档

Sentry的跟踪必须启用,以便配置文件生效。因此,您还需要配置WP_SENTRY_TRACES_SAMPLE_RATE以启用配置文件。

为配置文件设置想要的采样率。将0.3替换为您想要的采样率(0.3表示采样大约30%的流量)

define( 'WP_SENTRY_TRACES_SAMPLE_RATE', 0.3 ); // traces_sample_rate
// https://docs.sentry.io/platforms/php/profiling/#configure
define( 'WP_SENTRY_PROFILES_SAMPLE_RATE', 0.3 ); // profiles_sample_rate

注意:不要设置此常量或将采样率设置为0.0以禁用性能监控。

设置用户反馈

WP_SENTRY_BROWSER_FEEDBACK_OPTIONS(浏览器)

通过将此片段添加到您的wp-config.php,您可以使用用户反馈小部件(官方文档)。

define( 'WP_SENTRY_BROWSER_FEEDBACK_OPTIONS', [ 'enabled' => true ] );

所有选项都直接传递给feedbackIntegration(),您可以在官方文档中了解所有可用选项。

过滤器

此插件为插件/主题开发者提供了以下过滤器。

注意:一些过滤器在Sentry追踪器初始化时触发,因此如果您在主题或插件中定义它们,则不会触发。

适用于PHP和浏览器

wp_sentry_user_context(数组)

您可以使用此过滤器扩展PHP和JS追踪器的Sentry用户上下文。

警告:这些值在JS追踪器中公开,请确保您不公开任何隐私信息!

示例用法

add_filter( 'wp_sentry_user_context', function ( array $user ) {
	return array_merge( $user, array(
		'a-custom-user-meta-key' => 'custom value',
	));
} );

注意: 此过滤器在WordPress set_current_user 动作上触发,并且只有当WP_SENTRY_SEND_DEFAULT_PII常量设置为true时才会触发。

仅适用于PHP

wp_sentry_dsn(字符串)

您可以使用此过滤器覆盖PHP追踪器使用的Sentry DSN。

警告:不推荐这样做,请使用WP_SENTRY_PHP_DSN常量在您的wp-config.php中设置DSN!

示例用法

add_filter( 'wp_sentry_dsn', function ( $dsn ) {
	return 'https://<key>:<secret>@sentry.io/<project>';
} );

注意: 此过滤器在WordPress after_setup_theme 动作上触发。不推荐使用此过滤器,而是使用WP_SENTRY_PHP_DSN常量在wp-config.php中定义DSN。

wp_sentry_scope(void)

您可以使用此过滤器自定义Sentry 范围

示例用法

add_filter( 'wp_sentry_scope', function ( \Sentry\State\Scope $scope ) {
	$scope->setTag('my-custom-tag', 'tag-value');

	return $scope;
} );

注意: 此过滤器在WordPress after_setup_theme 动作上触发。

wp_sentry_options

您可以使用此过滤器来自定义 Sentry 选项

示例用法

add_filter( 'wp_sentry_options', function ( \Sentry\Options $options ) {
	// Only sample 90% of the events
	$options->setSampleRate(0.9);

	return $options;
} );

注意: 此过滤器在WordPress after_setup_theme 动作上触发。

wp_sentry_before_send

您可以使用此过滤器过滤发送到 Sentry 的错误事件。有关文档中有关过滤的更多信息

示例用法

add_filter( 'wp_sentry_before_send', function ( \Sentry\Event $event, ?\Sentry\EventHint $hint = null ) {
    // Don't send error event with level `warning` for the Hello Dolly example plugin
    if ( $hint->exception !== null && $event->getLevel() === \Sentry\Severity::warning() && strpos( $hint->exception->getFile(), 'plugins/hello.php' ) !== false ) {
        return null;
    }
    
    return $event;
}, 2 );

注意: 如果您想将事件发送到 Sentry,请勿忘记返回 $event,返回 null 将丢弃事件。

针对浏览器特定

wp_sentry_public_dsn (字符串)

您可以使用此过滤器覆盖用于 JS 跟踪器的 Sentry DSN。

警告: 这不推荐,请在您的 wp-config.php 中使用 WP_SENTRY_BROWSER_DSN 常量来设置 DSN!

示例用法

add_filter( 'wp_sentry_public_dsn', function ( $dsn ) {
	return 'https://<key>@sentry.io/<project>';
} );

wp_sentry_public_options (数组)

您可以使用此过滤器自定义/覆盖用于初始化 JS 跟踪器的 Sentry 选项

警告: 这些值会公开暴露,请确保您没有公开任何私密信息!

示例用法

add_filter( 'wp_sentry_public_options', function ( array $options ) {
	return array_merge( $options, array(
		'sampleRate' => '0.5',
		'denyUrls' => array(
			'https://github.com/',
			'regex:\\w+\\.example\\.com',
		),
	));
} );

注意: denyUrlsallowUrlsignoreErrors 选项数组中,以 regex: 前缀开头的项将被转换为纯正则表达式。

wp_sentry_public_context (数组)

您可以使用此过滤器自定义/覆盖 Sentry 上下文,您可以修改 usertags 上下文。

警告: 这些值会公开暴露,请确保您没有公开任何私密信息!

示例用法

add_filter( 'wp_sentry_public_context', function ( array $context ) {
	$context['tags']['my-custom-tag'] = 'tag-value';

	return $context;
} );

高级用法

大量通知

WordPress 生态系统中许多插件生成通知,这些通知被 Sentry 插件捕获。

这可能导致事件数量激增,甚至由于这些事件被发送到 Sentry 而导致页面加载速度变慢。

为了防止这种情况,您可以在您的 wp-config.php 中设置以下内容以过滤掉通知类型的错误。

define( 'WP_SENTRY_ERROR_TYPES', E_ALL & ~E_NOTICE & ~E_USER_NOTICE );

注意:您可以设置任何组合的错误类型,有关更多信息,请参阅PHP文档

捕获已处理的异常

对异常的最佳处理方式是捕获和处理它,然而您可能仍然想知道是否发生了异常。

Sentry 插件仅捕获未处理的异常和致命错误,要捕获已处理的异常,您可以执行以下操作

try {
	myMethodThatCanThrowAnException();
} catch ( \Throwable $e ) {
    // Option #1: Use the `captureException` or `captureMessage` action
    // It's safe to call these actions even if the plugin is disabled (it will simply do nothing)
    do_action( 'sentry/captureException', $e );
    do_action( 'sentry/captureMessage', $e->getMessage() ); // it is recommended to use `captureException`

    // Option #2: Use the `wp_sentry_safe` function to interact with the Sentry SDK directly
	// It's advised to wrap this in a function_exists check to prevent errors when the plugin is disabled
	if ( function_exists( 'wp_sentry_safe' ) ) {
		wp_sentry_safe( function ( \Sentry\State\HubInterface $client ) use ( $e ) {
			$client->captureException( $e );
		} );
	}

	wp_die( 'There was an error doing this thing you were doing, we have been notified!' );
}

如果您只需要为已处理的异常附加额外数据,您可以添加 结构化上下文

$e = new Exception('Some exception I want to capture with extra data.');

if (function_exists('wp_sentry_safe')) {
	wp_sentry_safe(function (\Sentry\State\HubInterface $client) use ($e) {
		$client->withScope(function (\Sentry\State\Scope $scope) use ($client, $e) {
			$scope->setContext('user_data', $e->getData());
			$client->captureException($e);
		});
	});
}

如果您需要在每种情况下都向作用域添加数据,请使用 wp_sentry_scope 过滤器 中的 configureScope

在 WordPress 之前加载 Sentry

由于 WP Sentry 是一个 WordPress 插件,它会在 WordPress 加载之后加载,除非您正在使用必须使用的插件(请参阅捕获插件错误),否则在加载其他一些插件并抛出错误后,Sentry 将无法捕获这些错误。

为了解决这个问题,您可以选择在 WordPress 启动之前从您的 wp-config.php 文件中加载插件。

通过在 wp-config.php 中的 /* That's all, stop editing! Happy blogging. */ 注释之前添加以下片段,就可以简单地进行此操作

// It's possible your WordPress installation is different, check to make sure this path is correct for your installation
require_once __DIR__ . '/wp-content/plugins/wp-sentry-integration/wp-sentry.php';

同时确保在上述片段之前设置了任何配置选项,如 WP_SENTRY_PHP_DSN,否则它们将没有效果。

捕获插件错误

由于此插件名为 wp-sentry-integration,它加载得稍晚,可能会错过在它之前加载的插件的错误或通知。

您可以通过创建文件 wp-content/mu-plugins/wp-sentry-integration.php(如果 mu-plugins 目录不存在,则必须创建它)来解决这个问题。

<?php

/**
 * Plugin Name: WordPress Sentry
 * Plugin URI: https://github.com/stayallive/wp-sentry
 * Description: A (unofficial) WordPress plugin to report PHP and JavaScript errors to Sentry.
 * Version: must-use-proxy
 * Author: Alex Bouma
 * Author URI: https://alex.bouma.dev
 * License: MIT
 */

$wp_sentry = WP_CONTENT_DIR . '/plugins/wp-sentry-integration/wp-sentry.php';

// Do not crash in case the plugin is not installed
if ( ! file_exists( $wp_sentry ) ) {
	return;
}

require $wp_sentry;

现在 wp-sentry-integration 将始终加载,并且在其他所有插件之前加载。

注意:建议您将原始的 wp-sentry-integration 保留在 /wp-content/plugins 文件夹中,以便通过 WordPress 更新器继续接收更新。然而,如果上述脚本处于活动状态(因为它始终处于启用状态),启用或禁用这些选项没有任何作用。

仅捕获特定主题和/或插件的错误

以下是一个示例,说明如何使用 Sentry SDK 的 before_send 回调来仅捕获在特定主题或插件中发生的错误。

请参阅过滤器文档: wp_sentry_option

add_filter( 'wp_sentry_options', function ( \Sentry\Options $options ) {
	$options->setBeforeSendCallback( function ( \Sentry\Event $event ) {
		$exceptions = $event->getExceptions();

		// No exceptions in the event? Send the event to Sentry, it's most likely a log message
		if ( empty( $exceptions ) ) {
			return $event;
		}

		$stacktrace = $exceptions[0]->getStacktrace();

		// No stacktrace in the first exception? Send it to Sentry just to be safe then
		if ( $stacktrace === null ) {
			return $event;
		}

		// Little helper and fallback for PHP versions without the str_contains function
		$strContainsHelper = function ( $haystack, $needle ) {
			if ( function_exists( 'str_contains' ) ) {
				return str_contains( $haystack, $needle );
			}

			return $needle !== '' && mb_strpos( $haystack, $needle ) !== false;
		};

		foreach ( $stacktrace->getFrames() as $frame ) {
			// Check the the frame happened inside our theme or plugin
			// Change THEME_NAME and PLUGIN_NAME to whatever is required
			// And / or modify this `if` statement to detect other variables
			if ( $strContainsHelper( $frame->getFile(), 'themes/THEME_NAME' )
				 || $strContainsHelper( $frame->getFile(), 'plugins/PLUGIN_NAME' )
			) {
				// Send the event to Sentry
				return $event;
			}
		}

		// Stacktrace contained no frames in our theme and/or plugin? We send nothing to Sentry
		return null;
	} );

	return $options;
} );

客户端钩子

当使用 Sentry 浏览器集成时,可以在 Sentry 初始化之前在客户端浏览器中执行一些工作,以更改选项或阻止浏览器 SDK 初始化。

您可以通过在包含 Sentry 浏览器 JavaScript 文件之前定义一个 wp_sentry_hook JavaScript 函数来完成此操作(请保持此函数小巧简单,因为其中发生的任何错误都不会由浏览器 SDK 跟踪)。

使用 wp_add_inline_script 禁用浏览器 SDK 的快速示例

add_action( 'wp_enqueue_scripts', function () {
	wp_add_inline_script( 'wp-sentry-browser', 'function wp_sentry_hook(options) { return someCheckInYourCode() ? true : false; }', 'before' );
} );

wp_sentry_hook 函数返回 false 时,将停止 Sentry Brower SDK 的初始化。任何其他返回值都将被忽略。

要修改选项,可以修改 wp_sentry_hook 的第一个参数传递的对象,该对象稍后将被传递给 Sentry.init 以初始化浏览器 SDK。

在初始化之前修改 PHP SDK ClientBuilder 或选项

由于 PHP SDK 初始化得很快,以便捕获早期错误,因此无法使用 WordPress 钩子修改选项或 ClientBuilder

可以通过使用名为 WP_SENTRY_CLIENTBUILDER_CALLBACK 的常量设置回调来在初始化 PHP SDK 之前修改选项和 ClientBuilder

当插件创建新的 ClientBuilder 实例以创建新的 PHP SDK 客户端时,将执行此回调。

您可以将以下示例放置在 wp-config.php 文件中,以确保它在 PHP SDK 初始化之前可用

function wp_sentry_clientbuilder_callback( \Sentry\ClientBuilder $builder ): void {
    // For example, disabling the default integrations
	$builder->getOptions()->setDefaultIntegrations( false );
}

define( 'WP_SENTRY_CLIENTBUILDER_CALLBACK', 'wp_sentry_clientbuilder_callback' );

HTTP 代理

如果您需要使用 HTTP 代理将事件发送到 Sentry,您可以设置 WordPress HTTP 代理支持,并将此插件将这些设置传输到 Sentry SDK。

有关如何设置 WordPress 代理常量的更多信息,请参阅此处:https://developer.wordpress.org/reference/classes/wp_http_proxy/#description

有一个需要注意的地方,如果您在 WordPress 中使用 HTTP 代理,但不想让 Sentry 使用它,则应将 wp-config.php 中的 WP_SENTRY_PROXY_ENABLED 设置为 false。设置 WP_PROXY_BYPASS_HOSTS 不会生效!

安全漏洞

如果您在 WordPress Sentry (wp-sentry) 中发现安全漏洞,请向 Alex Bouma 发送电子邮件至 alex+security@bouma.me。所有安全漏洞都将得到迅速处理。

许可证

WordPress Sentry (wp-sentry) 插件是开源软件,许可协议为 MIT 许可证