mumzworld / magento2-opentelemetry

mumzworld/magento2-opentelemetry

OpenTelemetry integration package for Magento 2 applications with complete observability stack

Mumzworld Development Team

library Compatibility: 2.4.7-2.4.9 Code Quality: Fail Tests: N/A Security: Pass MIT

Get this package

Free

Install

Add the repository once:

composer config repositories.packagento composer https://packagento.com/

Then require:

composer require mumzworld/magento2-opentelemetry:^1.0.1

Details

Latest version: 1.0.1
Released: 2026-05-26 13:00:17
Downloads: 0
License: MIT

Report this package

Seeing license violations, malicious code, IP infringement, or spam? Let our moderation team know.

Readme

Magento 2 Opentelemetry Instrumentation

Magento 2 OpenTelemetry Instrumentation

OpenTelemetry integration package for Magento 2 applications with complete observability stack

📖 Overview

A Composer library that adds OpenTelemetry tracing to Magento 2. It hooks into Magento core classes at runtime to automatically create spans for:

HTTP requests — REST API, GraphQL, Backend admin, HTTP client
Database — SQL query tracing
Cache — Page cache, Redis, Varnish
CLI — Commands, cron jobs, indexer operations
Entity — EAV and flat entity load/save
Business logic — Pricing, shipping, inventory, sales rules, repositories

🔄 OpenTelemetry Flow

[image: OpenTelemetry Flow]

📊 Grafana Traces

[image: Grafana Traces]

⚙️ How OpenTelemetry PHP SDK Works Under the Hood

1. PHP registers shutdown handler:
   OpenTelemetry\SDK\Common\Util\ShutdownHandler::register()

2. During shutdown:
   │
   └─> OpenTelemetry\SDK\Common\Util\ShutdownHandler::handleShutdown()
       │
       └─> Executes registered callbacks including:
           │
           └─> OpenTelemetry\SDK\Trace\TracerProvider->shutdown()
               │
               └─> Delegates to:
                   │
                   └─> OpenTelemetry\SDK\Trace\TracerSharedState->shutdown()
                       │
                       └─> Processes all span processors:
                           │
                           └─> OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor->shutdown()
                               │
                               └─> Final flush:
                                   │
                                   └─> OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor->flush()
                                       │
                                       └─> Delegates export to:
                                           │
                                           └─> OpenTelemetry\Contrib\Otlp\SpanExporter->export()
                                               │
                                               ├─> Serializes spans
                                               └─> Makes network call to collector

📋 Prerequisites

PHP 8.0+
PECL
Composer
OpenTelemetry PHP extension + PHP SDK
Magento Application
- Docker
- Host

🔧 OpenTelemetry Setup

1. Install OpenTelemetry PHP Extension

pecl install opentelemetry

2. Configure the .ini Settings

Add the following to your PHP .ini file (e.g. php.ini or a custom opentelemetry.ini):

OTEL_PHP_AUTOLOAD_ENABLED="true"
OTEL_SERVICE_NAME=magento2
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://[COLLECTOR-IP]:4318
OTEL_PROPAGATORS=baggage,tracecontext
;OTEL_PHP_DISABLED_INSTRUMENTATIONS=magento2
;OTEL_PHP_EXCLUDED_URLS="health_check.php,get.php"

3. Verify the Extension

php -m | grep opentelemetry
php --ri opentelemetry

4. Install the PHP SDK

composer require open-telemetry/sdk open-telemetry/api open-telemetry/sem-conv open-telemetry/exporter-otlp

Note: These packages are automatically installed as dependencies when you install mumzworld/magento2-opentelemetry. You only need to install them manually if you're setting up OpenTelemetry without this package.

📦 Package Installation

composer require mumzworld/magento2-opentelemetry

No Magento module setup is needed — the package bootstraps automatically via Composer's autoload mechanism.

🔍 What Is Auto-Instrumented

Once installed, this package automatically instruments the following Magento areas — no code changes required.

Core

Instrumentation	Hooked Class	Method
Magento Bootstrap	`Magento\Framework\App\Bootstrap`	`run()`, `terminate()`
Exception Handling	`Magento\Framework\App\Http`	`catchException()`
Profiler	`Magento\Framework\Profiler`	`start()`, `stop()`
Event Observers	`Magento\Framework\Event\InvokerInterface`	`dispatch()`

HTTP

Instrumentation	Hooked Class	Method
REST API	`Magento\Webapi\Controller\Rest\Interceptor`	`dispatch()`
REST Exceptions	`Magento\Framework\Webapi\Exception`	`__construct()`
GraphQL Dispatch	`Magento\GraphQl\Controller\GraphQl\Interceptor`	`dispatch()`
GraphQL Query	`Magento\Framework\GraphQl\Query\QueryProcessor`	`process()`
GraphQL Resolver	`Magento\Framework\GraphQl\Query\ResolverInterface`	`resolve()`
Backend Admin	`Magento\Backend\App\AbstractAction`	`dispatch()`
HTTP Client	`GuzzleHttp\Client`	`send()`

Database

Instrumentation	Hooked Class	Method
SQL Queries	`Magento\Framework\DB\Adapter\Pdo\Mysql`	`query()`

Cache

Instrumentation	Hooked Class	Method
FormKey Flush	`Magento\PageCache\Observer\FlushFormKey\Interceptor`	`execute()`
Full Cache Flush	`Magento\CacheInvalidate\Observer\FlushAllCacheObserver`	`execute()`
Cache Invalidation	`Magento\PageCache\Observer\InvalidateCache`	`execute()`
Redis	`Magento\Framework\Cache\Backend\Redis`	`test()`, `save()`, `remove()`, `clean()`
Varnish Purge	`Magento\CacheInvalidate\Model\PurgeCache`	`sendPurgeRequest()`

CLI

Instrumentation	Hooked Class	Method
CLI Runner	`Magento\Framework\Console\Cli`	`doRun()`
Console Commands	`Symfony\Component\Console\Command\Command`	`run()`
Cron Jobs	`Magento\Cron\Observer\ProcessCronQueueObserver`	`tryRunJob()`
Reindex	`Magento\Indexer\Model\Processor`	`reindexAllInvalid()`
Mview Actions	`Magento\Framework\Mview\View`	`executeAction()`
Mview Execute	`Magento\Framework\Mview\ActionInterface`	`execute()`
Mview Changelog	`Magento\Framework\Mview\View\ChangelogInterface`	`clear()`

Entity (EAV)

Instrumentation	Hooked Class	Method
Product	`Magento\Catalog\Model\ResourceModel\Product\Interceptor`	`load()`, `save()`, `delete()`
Category	`Magento\Catalog\Model\ResourceModel\Category\Interceptor`	`load()`, `save()`, `delete()`
Customer	`Magento\Customer\Model\ResourceModel\Customer\Interceptor`	`load()`, `save()`, `delete()`
Customer Address	`Magento\Customer\Model\ResourceModel\Address\Interceptor`	`load()`, `save()`, `delete()`

Entity (Flat)

Instrumentation	Hooked Class	Method
Quote	`Magento\Quote\Model\ResourceModel\Quote`	`load()`, `save()`, `delete()`
Quote Item	`Magento\Quote\Model\ResourceModel\Quote\Item`	`load()`, `save()`, `delete()`
Order	`Magento\Sales\Model\ResourceModel\Order`	`load()`, `save()`, `delete()`
Order Item	`Magento\Sales\Model\ResourceModel\Order\Item`	`load()`, `save()`, `delete()`
Invoice	`Magento\Sales\Model\ResourceModel\Order\Invoice`	`load()`, `save()`, `delete()`
Credit Memo	`Magento\Sales\Model\ResourceModel\Order\Creditmemo`	`load()`, `save()`, `delete()`

Business Logic (Misc)

Opt-in. This group is disabled by default — it produces the highest-volume spans (per-rule sales-rule evaluation, repository calls, pricing/tax calculation, address totals, etc.) and is best enabled selectively. Activate it by setting OTEL_MAGENTO_MISC_INSTRUMENTATION=true in your environment (.env, docker-compose.yml, nginx fastcgi_param, php-fpm pool, or export for CLI).

Instrumentation	Hooked Class	Method
Abstract DB	`Magento\Framework\Model\ResourceModel\Db\AbstractDb`	`load()`, `save()`, `delete()`
Product Repository	`Magento\Catalog\Model\ProductRepository`	`get()`, `getById()`
Category Repository	`Magento\Catalog\Model\CategoryRepository`	`get()`
Customer Repository	`Magento\Customer\Model\ResourceModel\CustomerRepository`	`get()`, `getById()`
Shipping Rates	`Magento\Shipping\Model\Shipping`	`collectRates()`
Final Price	`Magento\Catalog\Model\Product\Type\Price`	`getFinalPrice()`, `_applyTierPrice()`
Tax Calculation	`Magento\Tax\Model\Calculation`	`getRate()`
Sales Rules	`Magento\SalesRule\Model\Validator`	`process()`
Inventory	`Magento\CatalogInventory\Observer\QuantityValidatorObserver`	`execute()`
Totals Collector	`Magento\Quote\Model\Quote\TotalsCollector\Interceptor`	`collectAddressTotals()`
Address Totals	`Magento\Quote\Model\Quote\Address\Total\AbstractTotal`	`collect()`
Totals Collector	`Magento\Quote\Model\Quote\Address\Total\Collector`	`collect()`
Discount Calc	`Magento\SalesRule\Model\Rule\Action\Discount\AbstractDiscount`	`calculate()`

🚀 Optimization Tips

Install `ext-protobuf` PHP Extension

Preferred over the pure-PHP library google/protobuf for production:

pecl install protobuf

Option	Package	Performance
C extension (recommended)	`ext-protobuf` via `pecl install protobuf`	Native speed, minimal overhead
Pure-PHP library	`google/protobuf` via Composer	Slower serialization, higher CPU usage

NOTE: To reduce the latency imposed by the OTel exporter:

Use a local OTel collector (instead of remote)

Use the ext-protobuf C extension instead of the Composer package

Limiting the Number of Spans

See OpenTelemetry SDK Environment Variables — Attribute Limits for details on:

Limiting the number of span attributes
Limiting the length of span attribute values
Limiting the number of events

Export Settings

Setting	Purpose	Default	Suggested	Effect of Tuning
`OTEL_BSP_MAX_QUEUE_SIZE`	Max number of spans buffered in memory	2048	10000+	Prevents spans being dropped under high load
`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`	Max spans exported per batch	512	1000–5000	Reduces export cycles, improves throughput
`OTEL_BSP_SCHEDULE_DELAY`	How often (ms) the processor checks the queue for exporting	5000 ms	100–200 ms	Faster flushing during long-running requests
`OTEL_BSP_EXPORT_TIMEOUT`	Max time (ms) allowed for a single export batch	30000 ms	1000–2000 ms	Prevents request shutdown from blocking if exporter is slow/hangs

⚡ Performance Considerations

Sampling: Use appropriate sampling rates for production (0.1 = 10%)
Batching: Configure batch processors in collector
Resource Limits: Set memory and CPU limits
Network: Use gRPC for better performance
Storage: Configure appropriate retention policies

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📄 License

This package is licensed under the MIT License.

💬 Support

For support and questions:

Create an issue in the repository
Check the troubleshooting section
Review the Magento 2 OpenTelemetry documentation

Built with ❤️ by Mumzworld Development Team

Changelog

No changelog yet

The vendor hasn't published a changelog. Tagged releases appear in the Versions tab.

Versions 2

Versions
Version	Stability	QA Status	Compatibility	Released
1.0.1	stable	Fail	Magento 2.4.7-2.4.9 Details	2026-05-26 13:00:17
1.0.0	stable	Not tested	Not yet tested Details	2026-04-08 14:55:09

Dependencies 6

Requires 6

Package	Constraint
magento/framework	*
open-telemetry/api	^1.2
open-telemetry/exporter-otlp	^1.2
open-telemetry/sdk	^1.2
open-telemetry/sem-conv	^1.30
php	^8.1

Quality 12

Compatibility

Each Magento release line is installed on its supported PHP versions, then the module is built (DI compilation + static-content deploy) and its unit and integration suites are run. The matrix shows the lines and PHP versions the module is confirmed to install and run on. Code-quality results further down (phpstan, phpcs, …) are reported separately and never affect compatibility.

Compatibility matrix (Magento × PHP)
Magento	PHP 8.2	PHP 8.3	PHP 8.4	PHP 8.5
2.4.7	Pass	Pass
2.4.8		Pass	Pass
2.4.9			Pass	Pass

Code Quality

Advisory checks against the module's source. Static analysis runs once across the whole module; PHPStan re-runs per Magento + PHP version because resolvable symbols differ between releases. These NEVER affect the Compatibility badge. A phpcs finding can't make a module incompatible.

Static analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

Static analysis results
Tool	Status	Findings	Summary
PHPCS	Warning	5	5 warnings (ruleset: Magento2) — 2 auto-fixable with phpcbf
PHPMD	Warning	29	29 rule violations (UnusedFormalParameter:16, IfStatementAssignment:8, UnusedLocalVariable:3, UnusedPrivateMethod:1, ExcessiveClassComplexity:1)
Cpd	Pass	0
Composer validate	Info	2	valid; 2 advisory notes (composer validate --strict)

PHPStan

Type-checks the module's PHP against a real Magento install at the configured gate level. Re-runs per Magento and PHP version because resolvable symbols differ between releases.

PHPStan results by Magento and PHP version
Magento	PHP 8.2	PHP 8.3	PHP 8.4	PHP 8.5
2.4.7	56	56
2.4.8		56	56
2.4.9			56	56

Tests

Unit and integration suites, run for each applicable Magento and PHP version. A test failure speaks to the module's behaviour, not its compatibility with a Magento line, so it is reported here separately and never reddens the compatibility matrix.

Unit tests

Unit tests results by Magento and PHP version
Magento	PHP 8.2	PHP 8.3	PHP 8.4	PHP 8.5
2.4.7	N/A	N/A
2.4.8		N/A	N/A
2.4.9			N/A	N/A

Integration tests

Integration tests results by Magento and PHP version
Magento	PHP 8.2	PHP 8.3	PHP 8.4	PHP 8.5
2.4.7	N/A	N/A
2.4.8		N/A	N/A
2.4.9			N/A	N/A

Security

Security checks run directly against the module: an audit of its declared dependencies for known vulnerabilities (composer audit) and a scan of its source for malware and web-shell signatures. Each runs once. A malware detection fails the version outright.

Security results
Tool	Status	Findings	Summary
Composer audit	Pass	0
Malware scan	Pass	0

License

License

MIT

Authors

Mumzworld Development Team <[email protected]>

Make it pay

Turn an existing module into recurring revenue.

If you already maintain a Magento 2 module on GitHub or GitLab, listing it on Packagento takes about five minutes. We mirror your tags, handle distribution signing, and route paid licenses through Stripe Connect, so you can keep shipping the way you already do.

List your module