Skip to content

feat(micrometer): OpenTelemetry database semantic conventions for query observations#233

Merged
zantvoort merged 1 commit into
mainfrom
feat/otel-db-semconv
Jul 11, 2026
Merged

feat(micrometer): OpenTelemetry database semantic conventions for query observations#233
zantvoort merged 1 commit into
mainfrom
feat/otel-db-semconv

Conversation

@zantvoort

Copy link
Copy Markdown
Collaborator

Observability backends key their database tooling on the OpenTelemetry database client semantic conventions over OTLP: latency panels, service-map database nodes, and query views recognize the standard db.* attributes. Storm's observations carried only storm.* key values, so its spans rendered as generic custom spans outside that tooling.

Fixes #231

What's included

  • OtelDatabaseObservationConvention (storm-micrometer): extends the default convention with db.system.name and db.operation.name as low-cardinality key values and db.query.text as a high-cardinality value (parameter placeholders only, never values). The storm.* key values remain for custom dashboards, and db.statement is kept for backends that predate the stabilized conventions. fromJdbcUrl derives the database product from a JDBC URL using the conventions' well-known identifiers (mariadb, postgresql, h2database, oracle.db, microsoft.sql_server, ibm.db2; other_sql fallback).
  • Spring Boot starters: storm.observations.semantic-conventions=otel activates the convention through the shared StormObservationAutoConfiguration, with the database product detected from the application's DataSource. A user-defined ObservationConvention bean still wins; an unknown property value fails startup with a descriptive error.
  • Ktor plugin: an ObservationConvention<StormQueryObservationContext> registered in the dependency container overrides the automatic binding's naming and key values, mirroring the starters' convention bean.

The result is backend-specific database UX from vendor-neutral telemetry: the same spans light up whichever OTLP-capable backend the application points at — Elastic, Grafana, Datadog — with zero vendor-specific code in Storm or the application.

Verification

  • Convention unit tests: standard attributes emitted alongside the storm.* key values; JDBC URL mapping for the well-known products.
  • Java starter: end-to-end test asserting db.system.name=h2database on an observation recorded through the auto-configured template with the property set, plus the fail-fast case for unknown property values.
  • Ktor: end-to-end test registering the convention in the dependency container and asserting the standard attributes on a live query observation.

Docs: Observability sections of spring-integration.md and ktor-integration.md, the yaml examples, and the changelog entry.

…ry observations

Observability backends key their database tooling on the OpenTelemetry
database client semantic conventions over OTLP: latency panels,
service-map database nodes, and query views recognize db.* attributes.
Storm's observations carried only storm.* key values, so its spans
rendered as generic custom spans outside that tooling.

- OtelDatabaseObservationConvention (storm-micrometer): extends the
  default convention with db.system.name, db.operation.name (low
  cardinality) and db.query.text (high cardinality, placeholders only,
  never parameter values), keeping the storm.* key values for custom
  dashboards and db.statement for backends that predate the stabilized
  conventions. fromJdbcUrl derives the database product from a JDBC URL
  using the conventions' well-known identifiers.
- Spring Boot starters: storm.observations.semantic-conventions=otel
  activates the convention, with the database product detected from the
  application's DataSource; an ObservationConvention bean still wins,
  and an unknown property value fails fast. Shared by both starters via
  StormObservationAutoConfiguration.
- Ktor plugin: an ObservationConvention<StormQueryObservationContext>
  registered in the dependency container overrides the naming and key
  values, mirroring the starters' convention bean.

The result is backend-specific database UX from vendor-neutral
telemetry: the same spans light up whichever OTLP-capable backend the
application points at.

Fixes #231
@zantvoort zantvoort merged commit 46f6630 into main Jul 11, 2026
7 checks passed
@zantvoort zantvoort deleted the feat/otel-db-semconv branch July 11, 2026 21:18
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.

Report query observations with OpenTelemetry database semantic conventions

1 participant