PHPackages                             roqmeu/symfony-span-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. roqmeu/symfony-span-bundle

ActiveSymfony-bundle[Logging & Monitoring](/categories/logging)

roqmeu/symfony-span-bundle
==========================

Symfony Span Bundle

v1.0.1(3mo ago)0671↑1322.2%MITPHPPHP ^7.4 || ^8.0

Since Mar 2Pushed 3mo agoCompare

[ Source](https://github.com/roqmeu/symfony-span-bundle)[ Packagist](https://packagist.org/packages/roqmeu/symfony-span-bundle)[ RSS](/packages/roqmeu-symfony-span-bundle/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (2)Dependencies (26)Versions (3)Used By (0)

Symfony Span bundle
===================

[](#symfony-span-bundle)

Symfony-бандл, добавляющий трассировку и инструментирование для HTTP, Doctrine, Messenger и других компонентов. Готов к интеграции с Elastic APM, OpenTelemetry и подобными системами наблюдаемости.

Возможности
-----------

[](#возможности)

- Автоинструментирование Symfony HTTP Client, Guzzle, Doctrine DBAL, Symfony Messenger и OldSound RabbitMqBundle.
- Централизованное управление трейсами и спанами, совместимое с OpenTelemetry naming-конвенциями.
- Событийная модель работы: бандл диспатчит события жизненного цикла спанов/трейсов; адаптеры экспортируют данные во внешние системы.
- Поддержка Distributed Tracing для передачи контекста трассировки через HTTP и очереди сообщений.
- Встроенный мост к Elastic APM, учитывающий спецификации агента, маппинг контекста и поддерживающий Distributed Tracing.
- Профайлинг приложения через `ext-excimer`.

Требования
----------

[](#требования)

- PHP `^7.4` или `^8.0`.
- Symfony компоненты (Config, DependencyInjection, EventDispatcher) версий `^5.0 || ^6.0 || ^7.0`.
- Поддержка Symfony Messenger `^5.4 || ^6.4 || ^7.0`.
- Поддержка Doctrine DBAL `^3.0 || ^4.0`.
- Поддержка Guzzle `^7.0`.
- Поддержка OldSound RabbitMqBundle `^2.0`.
- Для профилинга (опционально): PHP-расширение `excimer` (`ext-excimer`).

Установка
---------

[](#установка)

```
composer require roqmeu/symfony-span-bundle
```

Если вы не используете Symfony Flex, добавьте бандл вручную в `config/bundles.php`:

```
return [
    // ...
    Roqmeu\SpanBundle\SpanBundle::class => ['all' => true],
];
```

После установки бандл предоставляет сервисы `SpanTracer`, `SpanInteractor`, которые можно внедрять через автоконфигурацию.

Быстрый старт
-------------

[](#быстрый-старт)

1. Включите бандл и трассировку в конфиге (по умолчанию всё выключено).
2. Включите мост, например, `span.bridge.elastic_apm` (по умолчанию всё выключено).
3. Подключите бандл и соберите контейнер.
4. Подпишитесь на события `TraceStartedEvent`, `TraceEndedEvent`, `SpanStartedEvent`, `SpanEndedEvent`, если требуется собственный экспорт.
5. Используйте `SpanTracer` для создания и завершения спанов в пользовательском коде или полагайтесь на готовые интеграции.

Конфигурация
------------

[](#конфигурация)

По умолчанию бандл **выключен**. Автоинструментирование и листенеры включаются только при явном включении флагов.

Пример `config/packages/span.yaml`:

```
span:
  enabled: true

  tracing:
    enabled: true

  bridge:
    elastic_apm:
      # bool или placeholder (%env(bool:...)% или bool %parameter%)
      enabled: '%env(bool:default::ELASTIC_APM_ENABLED)%'
      # bool или placeholder (%env(bool:...)% или bool %parameter%)
      use_span_compression: false

  profiling:
    # bool или placeholder (%env(bool:...)% или bool %parameter%)
    enabled: '%env(bool:default::PROFILER_ENABLED)%'

    # Порог (секунды). Минимум 0.01, по умолчанию 0.1.
    threshold: 0.1

    # Фильтры корневого спана, для которого включаем профилинг.
    # Если задан allowed_*, то соответствующий ignored_* игнорируется.
    allowed_types: ~
    ignored_types: [ console ]
    allowed_subtypes: ~
    ignored_subtypes: ~
```

Ключевые моменты:

- `span.enabled`: включает регистрацию сервисов `SpanTracer`/`SpanInteractor`/`EventDispatcher`. Если `false`, регистрируются null-реализации (`NullSpanTracer`, `NullSpanInteractor`, `NullEventDispatcher`).
- `span.enabled` и `span.tracing.enabled` влияют на сборку контейнера (регистрация сервисов и compiler passes), поэтому их следует задавать как обычные `true/false` (не placeholder).
- `span.tracing.enabled`: включает листенеры HTTP/Console и автоинструментирование (Doctrine DBAL middleware, Symfony HttpClient, Guzzle, Symfony Messenger, OldSound RabbitMqBundle). Работает только если `span.enabled: true`.
- `span.profiling.enabled`: включает профилинг через `ext-excimer` (если расширение отсутствует — используется `SpanNullProfiler`). Работает только если `span.enabled: true`.
- `span.bridge.elastic_apm.enabled`: включает регистрацию `ElasticApmBridge` и его обработчики событий. Можно задавать как placeholder — в этом случае сервис будет зарегистрирован, а фактическое включение/выключение будет происходить по значению параметра/ENV в рантайме.
- `span.bridge.elastic_apm.use_span_compression`: настройка для Distributed Tracing при использовании span compression в Elastic APM агенте. Можно задавать как placeholder.

Архитектура и концепции
-----------------------

[](#архитектура-и-концепции)

### Типизация и именование

[](#типизация-и-именование)

Бандл опирается на стандарты OpenTelemetry, Elastic Common Schema и Sentry.

- Span содержит пару `type` + `subtype` и `сontext`.
- Ответственность за генерацию id, имени передана мостам (например, ElasticApmBridge), которые вычисляют их по собственным правилам на основе контекста, пример ElasticApmBridge:
    - HTTP server: ` `
    - HTTP client: ` `
    - DB: ` `
    - Messaging: ` `
    - Console: ``
- Контекст высокой кардинальности хранится в `Roqmeu\SpanBundle\State\Context`.

Поддерживаемые интеграции
-------------------------

[](#поддерживаемые-интеграции)

### HTTP (Symfony HttpClient & Guzzle)

[](#http-symfony-httpclient--guzzle)

- Автоинструментирование клиентов и ответов, с поддержкой потоковой обработки chunk'ов.
- Сбор HTTP-метаданных (метод, URI, статус, целевой хост/порт).

### Symfony HTTP Server

[](#symfony-http-server)

- `TracingRequestListener` создаёт root span для входящих HTTP-запросов.
- Определяет имя транзакции по маршруту и выставляет `successful` в зависимости от статуса ответа.

### Console команды

[](#console-команды)

- `TracingCommandListener` создаёт и завершает трассы вокруг Symfony Console команд.
- Имя транзакции совпадает с именем команды.

### Doctrine DBAL

[](#doctrine-dbal)

- Middleware перехватывает запросы, транзакции и prepared statements.
- Заполняет тип `db.` и контекст (instance, statement, адрес сервера).

### Symfony Messenger

[](#symfony-messenger)

- Автоинструментирование producer/consumer для sync и Redis/AMQP драйверов.
- Создаёт `producer` и `consumer` спаны, нормализует имена очередей, переносит контекст цели и заполняет `server.host`/`server.port` по параметрам соединения.

### OldSound RabbitMqBundle

[](#oldsound-rabbitmqbundle)

- Автоинструментирование producer/consumer (включая batch, multiple, dynamic, anon).
- Создаёт `producer` и `consumer` спаны, нормализует имена очередей, переносит контекст цели и заполняет `server.host`/`server.port` по параметрам соединения.

Экспорт и события
-----------------

[](#экспорт-и-события)

Все интеграции сообщают о жизненном цикле через события:

- `TraceStartedEvent` / `TraceEndedEvent`
- `SpanStartedEvent` / `SpanEndedEvent`

### Elastic APM Bridge

[](#elastic-apm-bridge)

`Roqmeu\SpanBundle\Bridge\ElasticApmBridge` подписан на `SpanStartedEvent` и `TraceEndedEvent` и экспортирует Trace в Elastic APM, соблюдая требования агента:

- Корневой спан преобразуется в транзакцию с корректным `type`, `outcome` и `result`. Имя транзакции генерируется мостом на основе контекста.
- Дочерние спаны создаются через `beginChildSpan`, учитывая тип и сабтайп.
- Контекст HTTP/DB/Messaging маппится в `destination` и `service.target`. Мост самостоятельно выбирает `target` на основе контекста.
- Поддерживается Distributed Tracing за счёт "раннего" создания транзакций и спанов (stubs), так как Elastic APM Agent позволяет инжектировать заголовки `traceparent` только на этапе создания сегмента.

Мост по умолчанию выключен. Для включения задайте `span.bridge.elastic_apm.enabled: true` (или placeholder) и убедитесь, что установлен и доступен `elastic/apm-agent-php` (проверяется по наличию класса `Elastic\Apm\ElasticApm`). Если вы хотите получать спаны из автоинструментирования Symfony/Doctrine/Messenger, дополнительно включайте `span.tracing.enabled: true`.

Если нужна другая система экспорта, подпишитесь на события и реализуйте собственный транспорт.

Локальная разработка
--------------------

[](#локальная-разработка)

В репозитории присутствует `docker-compose.yml` и `Makefile`, упрощающие запуск окружения:

- `.env` содержит версии PHP и библиотек.
- `make up` — поднимает окружение (PHP + PostgreSQL + Redis).
- `make init` - устанавливает указанные в `.env` версии библиотек.
- `make reup` — перезапускает контейнеры с пересозданием.
- `make rebi` — пересобирает образ PHP и обновляет контейнеры.
- `make sh` / `make shr` — открывает shell внутри контейнера от имени `www-data` или `root`.

Тестирование и качество
-----------------------

[](#тестирование-и-качество)

- `make lint` — запускает Easy Coding Standard (`ecs`).
- `make stan` — запускает PHPStan с проектной конфигурацией.
- `make test` — обновляет автозагрузчик и запускает Codeception функциональные тесты.
- `make chain` — выполняет полный цикл: очистка кеша, линтер, статический анализ, тесты.

Конфигурация Codeception лежит в `codeception.yml`, тестовые фикстуры — в `test/fixture`, функциональные сценарии — в `test/functional`.

План развития
-------------

[](#план-развития)

- Добавить поддержку многоканальной отправки в `TracingProducerMiddleware`.

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance81

Actively maintained with recent releases

Popularity19

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~14 days

Total

2

Last Release

98d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/671bfd370bde00b7da2aaf229a14f58f304d3ef8781409b42fba766f612525ea?d=identicon)[roqmeu](/maintainers/roqmeu)

---

Top Contributors

[![roqmeu](https://avatars.githubusercontent.com/u/48632573?v=4)](https://github.com/roqmeu "roqmeu (8 commits)")

---

Tags

symfonyprofilingapmtracingopentelemetryotelotlp

###  Code Quality

TestsCodeception

Static AnalysisPHPStan

Code StyleECS

Type Coverage Yes

### Embed Badge

![Health badge](/badges/roqmeu-symfony-span-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/roqmeu-symfony-span-bundle/health.svg)](https://phpackages.com/packages/roqmeu-symfony-span-bundle)
```

###  Alternatives

[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k17.5M373](/packages/easycorp-easyadmin-bundle)[friendsofopentelemetry/opentelemetry-bundle

Traces, metrics, and logs instrumentation within your Symfony application

6510.2k](/packages/friendsofopentelemetry-opentelemetry-bundle)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.4M517](/packages/shopware-core)[traceway/opentelemetry-symfony

Pure-PHP OpenTelemetry instrumentation for Symfony — automatic HTTP, Console, HttpClient, Messenger, Doctrine DBAL, Cache, Twig tracing and Monolog log-trace correlation with response propagation, a lightweight Tracing helper, route templates, and semantic conventions. No C extension required (ext-protobuf recommended for production).

724.6k](/packages/traceway-opentelemetry-symfony)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)