Skip to content

feat(metrics): add Doctrine DBAL metrics#31

Merged
jstojiljkovic merged 4 commits into
tracewayapp:masterfrom
srekcud:feat/metrics-doctrine
May 10, 2026
Merged

feat(metrics): add Doctrine DBAL metrics#31
jstojiljkovic merged 4 commits into
tracewayapp:masterfrom
srekcud:feat/metrics-doctrine

Conversation

@srekcud

@srekcud srekcud commented May 4, 2026

Copy link
Copy Markdown
Contributor

Instruments

  • db.client.operation.duration (Histogram, s) — semconv Stable

Attributes: db.system.name, db.namespace, server.address, server.port,
db.operation.name (leading SQL keyword), db.collection.name (primary table when
unambiguous), error.type on failure.

Config

open_telemetry:
    metrics:
        enabled: true
        doctrine:
            enabled: true

Behaviour

  • Stacks as a regular DBAL middleware. MeteredDriver resolves the per-connection context
    (db.system.name from the driver string, db.namespace from dbname, server address/port from
    connection params) once at connect time and binds it to a single DbMetricRecorder shared by
    the connection wrapper and its prepared statements.
  • Records duration for Connection::query(), Connection::exec(), prepared
    Statement::execute(), and the transaction control methods
    (beginTransaction/commit/rollBack).
  • SQL text is never recorded. Only the leading keyword and the table name when extractable,
    both reused from the existing SqlOperationExtractor to keep cardinality bounded.

Notes

  • Review patterns from Feat/metrics foundation #27 applied up-front: error.type uses FQCN with parent-class
    fallback, histogram declares second-based buckets, every recording path is wrapped in a
    swallowing try/catch so a broken meter provider cannot mask the original DBAL exception.
  • DBAL 3 statement signature differs (execute($params = null) returning bool); the
    MeteredConnectionDbal3/MeteredStatementDbal3 pair mirrors the existing
    TraceableConnectionDbal3/TraceableStatementDbal3 split and is excluded from PHPStan analysis
    the same way (validated via the DBAL 3 CI matrix instead).
  • Same Util\ErrorTypeResolver as the parallel http-client and http-server PRs; whichever
    merges first lands it on master, the others rebase clean.
  • 22 new tests covering recorder, connection, statement, driver, attributes, transaction
    aggregation, anonymous-class fallback, bucket boundaries, broken-recorder swallow.

srekcud added 3 commits May 4, 2026 11:36
Wraps DBAL connections through a sibling of TraceableMiddleware to emit
db.client.operation.duration (Histogram, seconds, semconv Stable) for
every query, exec, prepared statement execution and transaction control
call. Per-connection context (db.system.name, db.namespace, server.*)
is resolved once at connect time. Supports DBAL 3 and DBAL 4. Recording
failures are swallowed so a broken meter provider can never replace the
original DBAL exception.

Introduces Util\ErrorTypeResolver to share the FQCN/anonymous-class
fallback used by the metric recorder; the existing inline copy in
OpenTelemetryMetricsMiddleware is left untouched and can be migrated
in a follow-up cleanup once this lands.
Adds unit tests for DbMetricRecorder, MeteredConnectionDbal4,
MeteredStatementDbal4 and MeteredDriver. Verifies attribute extraction
(operation/collection), error.type FQCN with anonymous-class fallback,
second-based bucket boundaries, transaction control aggregation, and
that recording failures never mask DBAL exceptions.
Documents the new metrics.doctrine.enabled flag, lists
db.client.operation.duration alongside the existing messaging metrics,
and clarifies that no SQL text is recorded — only the leading keyword
and an extracted table name when unambiguous.
@codecov-commenter

codecov-commenter commented May 4, 2026

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 73.13433% with 54 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/Doctrine/Middleware/MeteredConnectionDbal3.php 0.00% 44 Missing ⚠️
src/Doctrine/Middleware/MeteredStatementDbal3.php 0.00% 10 Missing ⚠️

📢 Thoughts on this report? Let us know!

Adds MeteredMiddlewareTest, DBAL 3 connection/statement tests (group
dbal3, validated by the existing CI matrix), failure-path tests for
exec/begin/commit/rollBack on the DBAL 4 connection, dbSystem resolver
data provider on MeteredDriver, and BundleBootTest cases for the
doctrine metrics wiring.
@jstojiljkovic
jstojiljkovic self-requested a review May 10, 2026 08:51
@jstojiljkovic
jstojiljkovic merged commit e2a4c55 into tracewayapp:master May 10, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants