Proposal: Introduce db.response.affected_rows Semantic Attribute

[StroSte]

Area(s)

area:db

Propose new conventions

This proposal introduces a new database-related semantic attribute/metric:

Attribute: db.response.affected_rows
Metric: db.client.response.returned_rows

This attribute represents the number of rows affected by a database operation.
It complements the existing attribute db.response.returned_rows and metric db.client.response.returned_rows, which captures the number of rows returned by a query.

While returned_rows is suitable for SELECT operations, many database actions—such as INSERT, UPDATE, DELETE —do not return rows but still affect a measurable number of rows. The lack of a standardized attribute for this information currently results in inconsistent instrumentation across libraries and vendors.

The new attribute is intended to be part of the Trace and Metric semantic conventions for database clients.

Previous Work

Related ideas have been discussed before. In particular, @trask mentioned a similar concept in #1438 (comment), where a Cosmos-DB-specific row_count metric was introduced. That discussion, however, focused on a single instrumentation and did not attempt to define a generic, cross-database semantic attribute.

At the moment, the Semantic Conventions only define db.client.response.returned_rows, which applies to read operations. There is no standardized attribute that captures the number of affected rows for write operations (INSERT / UPDATE / DELETE) across SQL and NoSQL systems.

This proposal builds on the ideas touched on in the Cosmos DB discussion but aims to generalize the concept and provide a consistent attribute applicable to all database client instrumentations.

Instrumentations / Systems Expected to Implement These Conventions

The attribute is relevant for a broad range of database instrumentations, including:

• SQL clients (PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite, etc.)
• ORM frameworks (Hibernate, JPA implementations, Sequelize, Prisma, Ecto, etc.
• NoSQL systems that report affected rows-equivalents (e.g., Redis DEL count, MongoDB modifiedCount)
• Vendor-specific drivers and middleware layers
• Any OpenTelemetry instrumentation that performs row-modifying operations and can obtain the affected row count

Benefits to the Ecosystem

Standardization
Today, many instrumentations report affected row counts using inconsistent attribute names or omit them entirely. Introducing this attribute aligns mutating operations with the same level of observability provided for returning operations.

Improved Performance Diagnosis
Users can more easily:

• identify unexpectedly large bulk updates,

• detect data-modification anomalies,

• correlate high impact operations with performance regressions.

• Parity with returned_rows

• Ensures full coverage of both read- and write-oriented database operations.

• Cross-vendor Interoperability
  A shared attribute schema enables APM tools and backends to interpret affected row counts consistently across languages and database systems.

• Enables Higher-Level Insights

Common usage patterns such as auditing, capacity planning, or anomaly detection become easier when affected row metrics are available across all instrumentations.

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[thompson-tomo]

Note the current attribute is called db.response.returned_rows. I don't like using the term rows as it doesn't support non table based db systems hence have raised #2725