kabiroman/adaptive-entity-manager-opentelemetry-bridge

OpenTelemetry bridge for Adaptive Entity Manager - adds distributed tracing and observability to entity lifecycle operations

dev-main 2025-12-17 21:34 UTC

Requires

• php: >=8.1
• kabiroman/adaptive-entity-manager-bundle: ^2.5.0
• open-telemetry/api: ^1.0
• psr/log: ^1.0 || ^2.0 || ^3.0
• symfony/event-dispatcher: ^6.0 || ^7.0
• symfony/framework-bundle: ^6.0 || ^7.0

Requires (Dev)

• open-telemetry/exporter-otlp: ^1.0
• open-telemetry/sdk: ^1.0
• phpunit/phpunit: ^10.5
• symfony/monolog-bundle: ^3.0 || ^4.0
• symfony/phpunit-bridge: ^6.4
• symfony/yaml: ^7.3

Suggests

• open-telemetry/exporter-otlp: Required for exporting traces to OTLP collectors (Jaeger, Tempo, etc.)
• open-telemetry/sdk: Required for actual tracing functionality

MIT

• Ruslan Kabirov

• symfony
• manager
• bundle
• entity
• opentelemetry

README

This Symfony bundle automatically creates OpenTelemetry spans for persist, update, and remove operations from kabiroman/adaptive-entity-manager-bundle and resolves manager names based on entity namespaces.

Installation

composer require kabiroman/adaptive-entity-manager-opentelemetry-bridge

Register the bundle in config/bundles.php and make sure an OTLP exporter/SDK is configured if you plan to export traces.

Configuration

Supported configuration structure (config/packages/adaptive_entity_manager_opentelemetry_bridge.yaml):

adaptive_entity_manager_opentelemetry_bridge:
    enabled: true
    manager_namespaces:
        sales: 'App\Domain\Sales\'
        legacy: 'App\Domain\Legacy\'

• enabled toggles tracing on or off.
• manager_namespaces maps manager names (keys) to namespace prefixes (values), which are used to determine entity ownership.

Usage

EntityPersistenceTracingSubscriber listens to lifecycle events emitted by AdaptiveEntityManager. Thanks to autoconfiguration, it receives TracerInterface, LoggerInterface (if available), the enabled flag, and namespace mapping from the bundle configuration.

Span naming

Spans are named according to the following pattern:

aem.{operation}.{EntityShortName}

Examples:

• aem.persist.User
• aem.update.Order
• aem.remove.Product

Span attributes

• aem.operation: persist, update, or remove
• aem.entity.class: fully qualified class name
• aem.entity.short_class: short class name
• aem.entity.id: result of getId() (when available)
• aem.manager: manager name resolved from namespace or unknown
• aem.entity.changed_fields and aem.entity.changed_fields_count for updates
• component: adaptive-entity-manager

Events

• aem.entity.persisted — emitted after entity persist
• aem.entity.updated — emitted after entity update
• aem.entity.removed — emitted after entity removal

Troubleshooting

Spans do not appear in Jaeger/Tempo

1. Confirm that TracerInterface is registered:

   php bin/console debug:container TracerInterface

2. Make sure the subscriber and bundle are loaded:

   php bin/console debug:container EntityPersistenceTracingSubscriber

3. Check the configuration that Symfony loads:

   php bin/console debug:config adaptive_entity_manager_opentelemetry_bridge

4. Enable debug logging if needed:

   monolog:
       handlers:
           main:
               level: debug

aem.manager always reads unknown

Ensure the configured namespaces match your entity namespaces:

manager_namespaces:
    sales: 'App\Domain\Sales\'  # Must match the entity namespace prefix

• App\Domain\Sales\Entity\User ✅
• App\Entity\Sales\User ❌ (namespace differs)

Jaeger / Tempo / OTLP

The bundle relies on OpenTelemetry\API\Trace\TracerInterface, so actual exporting and exporter selection happens outside the bundle (for example, with OpenTelemetry\SDK and an OTLP exporter). Ensure a TracerInterface service is available in your application.

Graceful degradation

• If no TracerInterface is registered, spans are not created.
• When enabled is false, the subscriber is a no-op.
• If manager_namespaces is empty, the manager name defaults to unknown.
• The logger is optional and only used for debug output.

Examples

Minimal configuration example:

adaptive_entity_manager_opentelemetry_bridge:
    enabled: '%env(bool:OTEL_ENABLED)%'
    manager_namespaces:
        sales: 'App\Domain\Sales\'

When Jaeger/Tempo receives traces, look for spans such as aem.persist.User and aem.update.Order that include manager, entity class, and id attributes.

Roadmap

This package is actively maintained. See ROADMAP.md for planned features and future releases.

Upcoming:

• v1.1.0 (Q1 2026): Span customization hooks, behavior tests, and edge case coverage
• v1.2.0 (Q2 2026): Integration tests, performance benchmarks, and CI/CD

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - see LICENSE file for details.