opencodeco/hyperf-opentelemetry

OpenTelemetry instrumentation for Hyperf framework

v0.2.0 2025-10-13 13:18 UTC

Requires

• php: >=8.1
• hyperf/command: ~3.1.0
• hyperf/crontab: ~3.1.0
• hyperf/database: ~3.1.0
• hyperf/di: ~3.1.0
• hyperf/event: ~3.1.0
• hyperf/guzzle: ~3.1.0
• hyperf/http-server: ~3.1.0
• open-telemetry/api: ^1.1
• open-telemetry/context-swoole: ^1.0
• open-telemetry/exporter-otlp: ^1.1
• open-telemetry/sdk: ^1.1
• open-telemetry/sem-conv: ^1.27

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.40
• hyperf/testing: ^3.0
• mockery/mockery: ^1.6
• phpmd/phpmd: ^2.14
• rector/rector: ^1.0
• roave/security-advisories: dev-latest
• squizlabs/php_codesniffer: ^3.7
• swoole/ide-helper: ^5.1

MIT

• Thiago Faino
• Lucas Angeli

• php
• Metrics
• logs
• tracing
• hyperf
• opentelemetry

README

Instrumentation library for Hyperf applications with OpenTelemetry support.

This library enables instrumentation of Hyperf-based applications for exporting metrics, traces, and logs compatible with the OpenTelemetry standard.

✨ Features

• 📦 Ready-to-use with Swoole and Coroutine
• 📊 Custom metrics support via Meter
• 📈 Trace instrumentation for:
  • HTTP requests (Hyperf\HttpServer)
  • Redis
  • Guzzle
  • SQL queries (Hyperf\Database)
• ♻️ Integration with Swoole ContextStorage

📦 Installation

composer require opencodeco/hyperf-opentelemetry

⚙️ Configuration

1. Publish the configuration file

php bin/hyperf.php vendor:publish opencodeco/hyperf-opentelemetry

Edit the file config/autoload/open-telemetry.php to adjust settings (enable/disable features, OTLP endpoints, resource attributes, etc).

1. Configure environment variables

Example .env:

OTEL_TRACES_ENDPOINT=http://otelcol:4318/v1/traces
OTEL_METRICS_ENDPOINT=http://otelcol:4318/v1/metrics

1. Add instrumentation middlewares

config/autoload/middlewares.php:

<?php

declare(strict_types=1);

use Hyperf\OpenTelemetry\Middleware\MetricMiddleware;
use Hyperf\OpenTelemetry\Middleware\TraceMiddleware;

return [
    'http' => [
        MetricMiddleware::class,
        TraceMiddleware::class,
    ],
];

👨‍💻 Development

Build the image

make build

Install dependencies

make install

Run tests

make test

🤝 Contributing

Please see CONTRIBUTING for details.