README

一个（非官方）WordPress 插件，用于向 Sentry 报告 PHP 和 JavaScript 错误。

是什么？

此插件可以将 PHP 错误（可选）和 JavaScript 错误（可选）报告给 Sentry 并与其发布跟踪集成。

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

要求 & Sentry PHP SDK

此插件需要 PHP 5.4+，但强烈建议用户使用不再处于生命终结（EOL）状态的 PHP 版本，并且不再受支持。有关仍受支持的 PHP 版本的最新列表，请参阅：https://php.ac.cn/supported-versions.php。

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

请注意，版本 3.x 是 wp-sentry 插件的最新版本，仅支持 PHP 7.1 及以上版本。如果您需要 PHP 5.4-7.2 的支持，请查看版本 2.x，但请注意，使用的 Sentry PHP SDK 有很多不同之处。

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

使用方法

1. 通过克隆或复制此存储库到您的 wp-contents/plugins 文件夹来安装此插件
2. 按照以下说明配置您的 DSN
3. 通过 WordPress 管理界面激活插件

注意：此插件默认不执行任何操作，也没有管理界面。必须首先配置 DSN。

配置

（可选）通过将此片段添加到您的 wp-config.php 中并替换 PHP_DSN 为您在 Sentry 项目设置中的“客户端密钥（DSN）”下找到的实际 DSN 来跟踪 PHP 错误

define( 'WP_SENTRY_PHP_DSN', 'PHP_DSN' );

注意：请勿设置此常量以禁用 PHP 跟踪器。

注意：此常量之前称为 WP_SENTRY_DSN，但仍受支持。

（可选）设置 PHP 跟踪器将跟踪的错误类型

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

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

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

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

define( 'WP_SENTRY_SEND_DEFAULT_PII', true );

（可选）通过将此片段添加到您的 wp-config.php 中并替换 JS_DSN 为您在 Sentry 项目设置中的“客户端密钥（DSN）”下找到的实际 DSN 来跟踪 JavaScript 错误

define( 'WP_SENTRY_BROWSER_DSN', 'JS_DSN' );

注意：不要将此常量设置为禁用JavaScript跟踪器。

注意：此常量之前称为WP_SENTRY_PUBLIC_DSN，但仍受支持。

（可选）通过将此片段添加到您的wp-config.php并替换0.3为您希望的平均采样率（0.3表示采样约30%的流量）来启用JavaScript性能跟踪。

define( 'WP_SENTRY_BROWSER_TRACES_SAMPLE_RATE', 0.3 );

注意：不要设置此常量或将其设置为0.0以禁用JavaScript性能跟踪。

（可选）定义您网站的一个版本；默认使用主题版本。这用于跟踪错误发生在您网站的哪个版本。当与发布跟踪结合使用时，这是一个非常强大的功能。

define( 'WP_SENTRY_VERSION', 'v4.2.0' );

（可选）定义您网站的环境。默认为未指定。

define( 'WP_SENTRY_ENV', 'production' );

过滤器

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

注意：一些过滤器在Sentry跟踪器初始化时触发，所以如果您在主题或WP Sentry之后加载的插件中定义它们，它们将不会触发。

PHP和JavaScript跟踪器的通用

wp_sentry_user_context（数组）

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

警告：这些值在JS跟踪器中公开，所以请确保不要公开任何私人信息！

示例用法

/**
 * Customize sentry user context.
 *
 * @param array $user The current sentry user context.
 *
 * @return array
 */
function customize_sentry_user_context( array $user ) {
    return array_merge( $user, array(
        'a-custom-user-meta-key' => 'custom value',
    ));
}
add_filter( 'wp_sentry_user_context', 'customize_sentry_user_context' );

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

仅适用于PHP跟踪器

wp_sentry_dsn（字符串）

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

示例用法

/**
 * Customize sentry dsn.
 *
 * @param string $dsn The current sentry DSN.
 *
 * @return string
 */
function customize_sentry_dsn( $dsn ) {
    return 'https://<key>:<secret>@sentry.io/<project>';
}
add_filter( 'wp_sentry_dsn', 'customize_sentry_dsn' );

注意： 此过滤器在WordPress的after_setup_theme动作上触发。不鼓励使用此过滤器，而是建议在wp-config.php中使用WP_SENTRY_PHP_DSN常量定义DSN。

wp_sentry_scope（void）

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

示例用法

/**
 * Customize Sentry PHP SDK scope.
 *
 * @param \Sentry\State\Scope $scope
 *
 * @return void
 */
function customize_sentry_scope( \Sentry\State\Scope $scope ) {
	$scope->setTag('my-custom-tag', 'tag-value');
}
add_filter( 'wp_sentry_scope', 'customize_sentry_scope' );

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

wp_sentry_options（数组）

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

示例用法

/**
 * Customize sentry options.
 *
 * @param array $options The current sentry options.
 *
 * @return array
 */
function customize_sentry_options( \Sentry\Options $options ) {
    // Only sample 90% of the events
    $options->setSampleRate(0.9);
}
add_filter( 'wp_sentry_options', 'customize_sentry_options' );

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

仅适用于JS跟踪器

wp_sentry_public_dsn（字符串）

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

警告：此值公开，所以请确保不要使用您的私人DSN！

示例用法

/**
 * Customize public sentry dsn.
 *
 * @param string $dsn The current sentry public dsn.
 *
 * @return string
 */
function customize_public_sentry_dsn( $dsn ) {
    return 'https://<key>@sentry.io/<project>';
}
add_filter( 'wp_sentry_public_dsn', 'customize_public_sentry_dsn' );

wp_sentry_public_options（数组）

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

警告：这些值公开，所以请确保不要公开任何私人信息！

示例用法

/**
 * Customize public sentry options.
 *
 * Note: Items prefixed with `regex:` in blacklistUrls and whitelistUrls option arrays
 * will be translated into pure RegExp.
 *
 * @param array $options The current sentry public options.
 *
 * @return array
 */
function customize_sentry_public_options( array $options ) {
    return array_merge( $options, array(
        'sampleRate' => '0.5',
        'blacklistUrls' => array(
            'https://github.com/',
            'regex:\\w+\\.example\\.com',
        ),
    ));
}
add_filter( 'wp_sentry_public_options', 'customize_sentry_public_options' );

wp_sentry_public_context（数组）

您可以使用此过滤器自定义/覆盖Sentry上下文，您可以修改user、tags和extra上下文。

警告：这些值公开，所以请确保不要公开任何私人信息！

示例用法

/**
 * Customize public sentry context.
 *
 * @param array $context The current sentry public context.
 *
 * @return array
 */
function customize_sentry_public_context( array $context ) {
    $context['tags']['my-custom-tag'] = 'tag-value';

    return $context;
}
add_filter( 'wp_sentry_public_context', 'customize_sentry_public_context' );

大量通知

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

这可能导致事件数量过多，甚至因为将这些事件传输到Sentry而导致页面加载速度变慢。

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

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

捕获已处理的异常

处理异常的最好方法是自行捕获它，但是您可能仍然想了解它。

Sentry插件仅捕获未处理的异常和致命错误，要捕获已处理的异常，您可以这样做：

try {
	myMethodThatCanThrowAnException();
} catch ( \Exception $e ) {
	// We are using wp_sentry_safe to make sure this code runs even if the Sentry 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!' );
}

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

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->setExtra('user_data', $e->getData());
            $client->captureException($e);
        });
    });
}

如果您需要在任何情况下都向作用域添加数据，请在wp_sentry_scope 过滤器中使用 configureScope。

捕获插件错误

由于此插件名为 wp-sentry-integration，它加载较晚，可能会错过在此插件之前加载的插件中发生的错误或通知。

您可以通过创建文件 wp-content/mu-plugins/wp-sentry-integration.php（如果 mu-plugins 目录不存在，您也必须创建它）来修复这个问题。

<?php

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

if ( ! file_exists( $wp_sentry ) ) {
	return;
}

require $wp_sentry;

define( 'WP_SENTRY_MU_LOADED', true );

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

注意：我们建议您将原始的 wp-sentry-integration 留在 /wp-content/plugins 文件夹中，以便通过 WordPress 更新器接收更新。然而，如果上面的脚本激活（因为它将始终启用），启用或禁用没有任何作用。

高级：客户端钩子

当使用 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 浏览器 SDK 的初始化将被停止。任何其他返回值都将被忽略。

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

许可证

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