Sentry component for Hyperf. It integrates the Sentry PHP SDK with Hyperf application lifecycle events, logs, tracing, metrics, crons, and coroutine-friendly transport.
composer require friendsofhyperf/sentryOptional integrations require the related Hyperf or client packages, for example
hyperf/amqp, hyperf/crontab, hyperf/database, hyperf/rpc-multiplex,
elasticsearch/elasticsearch, phpmyadmin/sql-parser, or hyperf/engine.
php bin/hyperf.php vendor:publish friendsofhyperf/sentryThis publishes config/autoload/sentry.php. The core settings are:
<?phpreturn [
'dsn' => env('SENTRY_DSN', ''),
'release' => env('SENTRY_RELEASE'),
'environment' => env('APP_ENV', 'production'),
'sample_rate' => env('SENTRY_SAMPLE_RATE') === null ? 1.0 : (float) env('SENTRY_SAMPLE_RATE'),
'traces_sample_rate' => env('SENTRY_TRACES_SAMPLE_RATE') === null ? 1.0 : (float) env('SENTRY_TRACES_SAMPLE_RATE'),
'profiles_sample_rate' => env('SENTRY_PROFILES_SAMPLE_RATE') === null ? null : (float) env('SENTRY_PROFILES_SAMPLE_RATE'),
'send_default_pii' => env('SENTRY_SEND_DEFAULT_PII', true),
];The configuration file also accepts Sentry SDK options such as server_name,
traces_sampler, before_send_log, before_send_metric,
before_send_check_in, before_send_transaction, ignore_exceptions, and
ignore_transactions.
The component registers a logger.channels.sentry channel with
FriendsOfHyperf\Sentry\Monolog\LogsHandler when no Sentry logger channel is
already configured. Configure the minimum level with:
SENTRY_ENABLE_LOGS=trueSENTRY_LOGS_CHANNEL_LEVEL=debugTo send diagnostic logs produced by the Sentry SDK itself, configure a PSR logger:
<?phpreturn [
'logger' => Hyperf\Contract\StdoutLoggerInterface::class,
];php bin/hyperf.php sentry:about
php bin/hyperf.php sentry:test
php bin/hyperf.php sentry:test --dsn=https://examplePublicKey@o0.ingest.sentry.io/0
php bin/hyperf.php sentry:test --transaction=1sentry:about prints SDK, DSN, environment, release, sample rate, and PII status.
sentry:test sends a test exception and can also send a test transaction.
<?phpuseFriendsOfHyperf\Sentry\Annotation\Breadcrumb;
useFriendsOfHyperf\Sentry\Annotation\Graceful;
useFriendsOfHyperf\Sentry\Annotation\IgnoreException;
useFriendsOfHyperf\Sentry\Metrics\Annotation\Counter;
useFriendsOfHyperf\Sentry\Metrics\Annotation\Histogram;
useFriendsOfHyperf\Sentry\Tracing\Annotation\Trace;
#[IgnoreException]
class IgnoredDomainException extends RuntimeException
{
}
class UserService
{
#[Breadcrumb(category: 'user')]
#[Trace(op: 'service.user', description: 'Create user')]
#[Counter('user_create_total')]
#[Histogram('user_create_duration')]
publicfunctioncreate(array$payload): void
{
// ...
}
#[Graceful(strategy: Graceful::STRATEGY_SWALLOW, report: true)]
publicfunctionreportableFallback(): mixed
{
// ...
}
}Available graceful strategies are swallow, rethrow, fallback, and
translate.
The component enables tracing by default and can continue trace context across HTTP, RPC, queue, Kafka, AMQP, crontab, command, and coroutine boundaries.
SENTRY_TRACING_ENABLE_AMQP=trueSENTRY_TRACING_ENABLE_ASYNC_QUEUE=trueSENTRY_TRACING_ENABLE_COMMAND=trueSENTRY_TRACING_ENABLE_COROUTINE=trueSENTRY_TRACING_ENABLE_CRONTAB=trueSENTRY_TRACING_ENABLE_KAFKA=trueSENTRY_TRACING_ENABLE_MISSING_ROUTES=trueSENTRY_TRACING_ENABLE_REQUEST=trueSENTRY_TRACING_SPANS_CACHE=trueSENTRY_TRACING_SPANS_COORDINATOR=falseSENTRY_TRACING_SPANS_COROUTINE=trueSENTRY_TRACING_SPANS_DB=trueSENTRY_TRACING_SPANS_ELASTICSEARCH=trueSENTRY_TRACING_SPANS_FILESYSTEM=trueSENTRY_TRACING_SPANS_GRPC=trueSENTRY_TRACING_SPANS_GUZZLE=trueSENTRY_TRACING_SPANS_REDIS=trueSENTRY_TRACING_SPANS_RPC=trueSENTRY_TRACING_SPANS_SQL_QUERIES=trueSENTRY_TRACING_SPANS_VIEW=trueUse ignore_commands and ignore_transactions in config/autoload/sentry.php
to exclude noisy commands or routes. Use tracing_tags to control optional span
data such as SQL bindings, results, or response bodies.
Manual instrumentation is available through helper functions:
<?phpuseSentry\Tracing\SpanContext;
usefunctionFriendsOfHyperf\Sentry\trace;
trace(function () {
returndoSomething();
}, SpanContext::make()->setOp('task')->setDescription('Do something'));SENTRY_ENABLE_METRICS=trueSENTRY_ENABLE_DEFAULT_METRICS=trueSENTRY_ENABLE_COMMAND_METRICS=trueSENTRY_ENABLE_POOL_METRICS=trueSENTRY_ENABLE_QUEUE_METRICS=trueSENTRY_METRICS_INTERVAL=10Default metrics cover request timing, coroutine server stats, command timing,
database and Redis pools, and async queues when the related packages are present.
#[Counter] and #[Histogram] add method-level custom metrics.
Hyperf crontab events can be reported as Sentry check-ins:
SENTRY_CRONS_ENABLE=trueSENTRY_CRONS_CHECKIN_MARGIN=5SENTRY_CRONS_MAX_RUNTIME=15SENTRY_CRONS_TIMEZONE=UTCPer-crontab options can override checkin_margin, max_runtime,
failure_issue_threshold, recovery_threshold, and update_monitor_config.
Set monitor to false on a crontab to skip check-ins for that task.
The default binding uses FriendsOfHyperf\Sentry\Transport\CoHttpTransport.
Tune its queue and concurrency with:
SENTRY_TRANSPORT_CHANNEL_SIZE=512SENTRY_TRANSPORT_CONCURRENT_LIMIT=100SENTRY_HTTP_TIMEOUT=2.0- OpenTelemetry Semantic Conventions semantic-conventions
- Sentry Span Operations Naming Standards span-operations