Skip to content

Correlation ID Audit Propagation

Paulo Gomes da Cruz Junior edited this page Sep 11, 2026 · 4 revisions

Correlation ID Audit Propagation

Pattern

Waste Plus propagates the current Micrometer trace ID into PostgreSQL transaction-local state through a Hibernate ConnectionProvider decorator. The pattern is AOP-free, filter-free, and application-ThreadLocal-free. It was selected to keep correlation capture compatible with the project's GraalVM native-image direction.

Connection provider

CorrelationIdConnectionProvider decorates Hibernate's DatasourceConnectionProviderImpl. After acquiring a connection, it reads tracer.currentSpan(). For a non-noop span with a nonblank trace ID, it returns a DeferredCorrelationIdConnection. The wrapper binds the trace ID exactly once immediately before the first statement-producing call (createStatement, prepareStatement, prepareCall, or setSavepoint):

SELECT set_config('app.correlation_id', ?, true)

The true argument makes the setting transaction-local, which prevents a value from bleeding into a later transaction when a pooled connection is reused. Calls without an active span, with a noop span, or with a blank trace ID return the raw connection. Delegate configuration, lifecycle, stop, and unwrap behavior is forwarded.

Hibernate wiring

Production configuration creates one DatasourceConnectionProviderImpl, binds the application DataSource, wraps it, and registers it with Hibernate's canonical JdbcSettings.CONNECTION_PROVIDER property through a HibernatePropertiesCustomizer. The customizer and its @SuppressWarnings({"deprecation", "removal"}) are intentional: this manual wiring avoids bean-container reflection and remains GraalVM-safe.

Audit migration

Migration V1.0.6__audit_correlation_id.sql adds or guards audit_event.correlation_id, creates a partial (correlation_id, changed_at DESC) index, and reads:

corr_id := current_setting('app.correlation_id', true);

The trigger stores the value only in hrs.audit_event; hrs.audit_change remains unchanged. V1.0.5 already defines audit_event.correlation_id as VARCHAR(128), and V1.0.6's guarded declaration preserves that effective width. The trigger uses session_user as the invoker fallback under SECURITY DEFINER. Any future narrowing requires a separately reviewed migration.

Validation boundary

The pattern was validated on Spring Boot 4.1.0, Hibernate ORM 7.4.1.Final, PostgreSQL 17, and the JVM. Six Testcontainers scenarios passed: active span, no span, raw JDBC write, distinct sequential transactions, same-thread connection reuse without bleed, and direct verification that the trigger uses current_setting(..., true). A web-level MockMvc B3 test used @AutoConfigureTracing and verified the supplied trace ID in audit_event.correlation_id. The integration tests are intentionally not @Transactional; fixture maintenance uses TransactionTemplate, and hrs.district_volume is never wiped.

Native-image compilation and runtime validation were not run. They remain follow-up work. The cost of running set_config before first statement use should be measured if connection handling changes.

Related work

The pattern supports the audit trigger framework tracked in PR #1188.

Merged to main via PR #1258 (V1.0.6 audit correlation-ID migration and Hibernate ConnectionProvider decorator).

Decision record

The deferred-bind architectural decision is recorded in ADR 001: Deferred-Bind ConnectionProvider for Transaction-Local GUC.

Component reference

The implementing class is documented at CorrelationIdConnectionProvider.

Waste Plus Wiki

Home

Architecture

Codes

Decisions

Knowledge Base

Development

Changes

Clone this wiki locally