README

此库实现了PSR-3 日志接口，将日志消息和异常发送到Integration Eye 实例。

安装

此库可在Packagist上找到，因此您可以使用Composer进行安装。

composer require integration-eye/logging-probe

要使用此库，您需要提供 Client 接口的实现。如果您安装了 symfony/http-client 包，将提供默认实现。

composer require symfony/http-client

有关自定义 Client 实现的更多信息，请参阅Client。

简单用法

存在一个 Logger::fromDsn($dsn) 工厂函数，用于简单实例化 Logger。

$logger = Logger::fromDsn('https://username:password@integrationeye.example.com');

Logger 实现了 PSR-3 日志接口，因此您可以使用它如下

$logger->debug('Trying out Integration Eye');

$logger->critical(new RuntimeException('Sometimes something goes wrong.'));

$logger->notice('It is shiny today', [
    'temperature' => '28',
    'date' => new DateTime(),
]);

您可以将内部标志（如 @principal）传递到上下文中，它将被用作元数据。

$logger->info('User just logged in.', [
    '@principal' => 'username',
    'method' => 'password',
]);

有关提供 @principal 的更多信息，请参阅PrincipalProvider。

高级用法

Logger 由 MessageFactory 实例和 Client 实现组成。

以下是一个创建 Logger 的示例，不使用 Logger::fromDsn($dsn) 工厂方法。

$configuration = Configuration::fromDsn('https://username:password@integrationeye.example.com');
$messageFactory = new MessageFactory($configuration);

$client = new DefaultClient();
$logger = new Logger($messageFactory, $client);

扩展

Client

Client 接口包含一个方法 sendMessage(Configuration $configuration, array $payload): void，其目的是向配置的端点发送 POST 请求。

可选的默认实现使用 symfony/http-client，但您可以根据需要提供自己的实现。

以下是一个用于测试目的的现有客户端的简化示例。

class EchoClient implements Client
{
    public function sendMessage(Configuration $configuration, array $payload): void
    {
        echo sprintf("Url: %s\n", $configuration->getUrl());
        echo sprintf("Authorization: Basic %s\n", $configuration->getBasicAuth());
        echo sprintf("Payload:\n%s\n", json_encode($payload, JSON_PRETTY_PRINT));
    }
}

PrincipalProvider

要发送带有日志的 @principal 元数据，您可以提供 PrincipalProvider 的实现。它有一个方法 getPrincipal(): ?string，您可以重写它。

以下是一个自定义实现的示例

class CustomPrincipalProvider implements PrincipalProvider
{
    private $securityContext;

    public function __construct(SecurityContext $securityContext)
    {
        $this->securityContext = $securityContext;
    }

    public function getPrincipal(): ?string
    {
        if ($this->securityContext->isLoggedIn()) {
            return $this->securityContext->getUsername();
        }

        return null;
    }
}

$messageFactory->setPrincipalProvider(new CustomPrincipalProvider($securityContext));

如果您愿意，可以使用内置的 DefaultPrincipalProvider 来静态解析主体。

$messageFactory->setPrincipalProvider(new DefaultPrincipalProvider('username'));
// or just
$messageFactory->setPrincipal('username');

Mapper

您可以为简化日志提供 Mapper 接口的实现。它包含两个方法 supports(string $key, $value): bool 和 map(string $key, $value): array。

以下是一个用于 JsonSerializable 对象的现有映射器的简化示例

class JsonMapper implements Mapper
{
    public function supports(string $key, $value): bool
    {
        return $value instanceof \JsonSerializable;
    }

    public function map(string $key, $value): array
    {
        return [$key => json_encode($value)];
    }
}

$messageFactory->addMapper(new JsonMapper());

此库提供了一些内置映射器

DateTimeMapper 用于格式化 DateTime 对象
JsonMapper 用于序列化 JsonSerializable 对象
ExceptionMapper 用于序列化 Throwable 对象并提供 @exception、@stackTrace 元数据

$messageFactory->addMapper(new DateTimeMapper('d.m.Y H:i:s'));
// or just
$messageFactory->addDateTimeMapper(); // default format 'c'

$messageFactory->addMapper(new JsonMapper());
// or just
$messageFactory->addJsonMapper();

$messageFactory->addMapper(new ExceptionMapper('exception_key'));
// or just
$messageFactory->addExceptionMapper(); // default key 'exception'

当您使用 Logger::fromDsn($dsn) 或 MessageFactory::instance($configuration) 时，所有内置映射器将自动注册并使用其默认配置。

integration-eye / logging-probe

维护者

详细信息