README

关于

此软件包为 sentry.io PHP SDK 提供 Flow 集成。默认情况下，将一些关于 Flow 应用程序的基本信息添加到 sentry 事件中，但您可以轻松配置和扩展此软件包以满足您的需求。

安装

composer require netlogix/sentry

目前支持以下 Flow 版本

^7.3
^8.0

设置

必须配置 sentry DSN 客户端密钥。从项目设置（SDK 设置 -> 客户端密钥（DSN））获取。

Netlogix:
  Sentry:
    dsn: 'https://fd5c649e6e4d41dd8ca729b15cc5d1c7@o01392.ingest.sentry.io/123456789'

然后只需运行 ./flow sentry:test 将异常记录到 sentry。虽然技术上您 只需要 做这些，但您可能希望调整提供者 - 请参见下文。

配置

此软件包允许您通过更改每个作用域的提供者来配置应添加到 sentry 事件中的数据。目前，可用的作用域有 environment、extra、release、tags 和 user。

可以使用 PositionalArraySorter 位置字符串对提供者进行排序。对于 extra、tags 和 user 作用域，所有提供的数据将合并在一起。对于 environment 和 release 作用域，只支持单个值（您仍然可以配置多个提供者，但最后一个获胜）。

Netlogix:
  Sentry:
    scope:
      extra: [ ]

      release:
        # If you don't need a specific order, you can simply set the provider to true
        'Netlogix\Sentry\Scope\Release\PathPattern': true

      tags:
        # Numerical order can be used
        'Netlogix\Sentry\Scope\Tags\FlowEnvironment': '10'
        'Your\Custom\TagProvider': '20'

      user:
        'Your\Custom\UserProvider': 'start 1000'
        # If you don't want to add the currently authenticated Flow Account to the Event, simply disable the provider
        'Netlogix\Sentry\Scope\User\FlowAccount': false

环境

sentry SDK 将搜索环境变量 SENTRY_ENVIRONMENT 并使用其值作为当前环境。这仍然是默认设置，但是您可以将 Netlogix\Sentry\Scope\Environment\FlowSettings 提供者配置为使用不同的值。

Netlogix:
  Sentry:
    environment:
      setting: '%env:SENTRY_ENVIRONMENT%'

版本跟踪

您可以使用 Netlogix\Sentry\Scope\Release\PathPattern ReleaseProvider 从应用程序目录中提取当前版本。默认情况下，配置的 pathPattern 与 FLOW_PATH_ROOT 常量匹配。

Netlogix:
  Sentry:

    # Used by Netlogix\Sentry\Scope\Release\PathPattern
    release:
      # Path to use for extraction of release
      pathToMatch: '%FLOW_PATH_ROOT%'

      # Pattern to extract current release from file path
      # This pattern is matched against pathToMatch
      pathPattern: '~/releases/(\d{14})$~'

您还可以使用 Netlogix\Sentry\Scope\Release\FlowSettings 通过 Flow 配置（Netlogix.Sentry.release.setting，默认设置为 %env:SENTRY_RELEASE%）来设置版本。

自定义提供者

对于每个作用域，您可以实现自己的提供者。每个作用域都需要自己的接口。

作用域 environment => Netlogix\Sentry\Scope\Environment\EnvironmentProvider
作用域 extra => Netlogix\Sentry\Scope\Extra\ExtraProvider
作用域 release => Netlogix\Sentry\Scope\Release\ReleaseProvider
作用域 tags => Netlogix\Sentry\Scope\Tags\TagProvider
作用域 user => Netlogix\Sentry\Scope\User\UserProvider

然后只需将它们添加到配置中。

如果您需要访问抛出的异常，可以检查 Netlogix\Sentry\Scope\ScopeProvider::getCurrentThrowable()

<?php

namespace Netlogix\Sentry\Scope\Extra;

use Neos\Flow\Annotations as Flow;
use Neos\Flow\Exception as FlowException;
use Netlogix\Sentry\Scope\ScopeProvider;

/**
 * @Flow\Scope("singleton")
 */
final class ReferenceCodeProvider implements ExtraProvider
{

    private ScopeProvider $scopeProvider;

    public function __construct(ScopeProvider $scopeProvider)
    {
        $this->scopeProvider = $scopeProvider;
    }

    public function getExtra(): array
    {
        $throwable = $this->scopeProvider->getCurrentThrowable();

        if (!$throwable instanceof FlowException) {
            return [];
        }

        return ['referenceCode' => $throwable->getReferenceCode()];
    }

}

手动记录异常到 sentry

如果您需要手动将异常发送到 sentry（例如在 catch 块中），可以使用 Netlogix\Sentry\ThrowableStorage\SentryStorage

<?php

use Neos\Flow\Annotations as Flow;
use Netlogix\Sentry\ThrowableStorage\SentryStorage;

class LoggingManually {

    /**
     * @Flow\Inject
     * @var SentryStorage
     */
    protected $sentryStorage;

    public function log(): void {
        $exception = new \RuntimeException('foo', 1612114936);

        $this->sentryStorage->logThrowable($exception, ['some' => ['additional', 'data']]);
    }

}

忽略异常

如果您需要跳过将特定异常发送到 sentry，可以使用 Flow 的 renderingGroups。只需创建一个与您的异常匹配的组，并将 logException 设置为 false

Neos:
  Flow:
    error:
      exceptionHandler:
        renderingGroups:

          ignoredExceptions:
            matchingStatusCodes: [ 418 ]
            matchingExceptionClassNames: [ 'Your\Ignored\Exception' ]
            # It is also possible to match against \Throwable::getCode(). Please note that this is not a Flow feature.
            # Check \Netlogix\Sentry\ExceptionHandler\ExceptionRenderingOptionsResolver::resolveRenderingGroup() for more info
            # matchingExceptionCodes: [1638880375]
            options:
              logException: false

请注意，这也将禁用此异常的 Data/Logs/Exceptions 记录。

加密 POST 负载

默认情况下，POST有效负载数据的数组以“原样”形式传输到Sentry服务器。

当启用加密并设置了有效的RSA密钥指纹时，POST有效负载将被剥离，并替换为RSA加密字符串。

Netlogix:
  Sentry:

    privacy:
      encryptPostBody: true
      rsaKeyFingerprint: '6ff568ae0f9b44b69627e275accf163a'

未加密的POST数据在Sentry中通常看起来像这样

{
    "--some-form": {
        "__currentPage": 1,
        "__state": "TmV0bG9naXguU2VudHJ5IHN0YXRlIGRhdGE=",
        "__trustedProperties": "[Filtered]",
        "firstName": "John",
        "lastName": "Doe",
        "birthday": "2021-01-01",
        "email": "john.doe@netlogix.de",
        "message": "Lorem ipsum dolor sit amet"
    }
}

启用加密后，看起来是这样的

{
    "__ENCRYPTED__DATA__": {
        "encryptedData": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2ljaSBlbGl0LCBzZWQgZWl1c21vZCB0ZW1wb3IgaW5jaWR1bnQgdXQgbGFib3JlIGV0IGRvbG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3RydWQgZXhlcmNpdGF0aW9u",
        "envelopeKey": "ZGVzZXJ1bnQgbW9sbGl0IGFuaW0gaWQgZXN0IGxhYm9ydW0=",
        "initializationVector": "QmxpbmR0ZXh0"
    }
}

将会有一个额外的Sentry字段“加密的POST数据”，其中包含一个回链，可以用于加密并显示原始数据。

为了使这生效，必须有处理Neos.Sentry控制器的认证提供者。

如果与此包一起使用neos/neos CMS，则可以将neos后端认证提供者分配此任务。请参阅下面的代码片段。

如果在不使用neos/neos的情况下使用此包，则需要配置策略Netlogix.Sentry:Backend.EncryptedPayload的自定义权限。

Neos:
  Flow:
    security:
      authentication:
        providers:
          'Neos.Neos:Backend':
            requestPatterns:
              'Netlogix.Sentry:ShowEncryptedPayload':
                pattern: ControllerObjectName
                patternOptions:
                  controllerObjectNamePattern: 'Netlogix\Sentry\Controller\.*'

netlogix / sentry

维护者

详细信息