Add in Surreal DB client spans #1107 #2571

thompson-tomo · 2025-07-29T04:30:45Z

Progresses #1107

Changes

This adds SurrealDB as a db system, so that it can be used in telemetry and defines client spans.

Usage Example

Health Check of the connection to the db #2205 data about db & messaging checks Xabaril/AspNetCore.Diagnostics.HealthChecks#2228. The definition of a health check event is much like an exception/event and as mentioned in the semconv meeting, 28/7/25, if attributes are not listed they are implicitly opt-in. As such this is just like if you were to put db.system.name on an exception it is beneficial. In some health checks it is even possible to check the health of db's not just sever connection etc hence even more reason to leverage the db namespace to capture that data.
Client api calls Create spans for create operations #12 surrealdb/surrealdb.net#206

Note: if the PR is touching an area that is not listed in the existing areas, or the area does not have sufficient domain experts coverage, the PR might be tagged as experts needed and move slowly until experts are identified.

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
Change log entry added, according to the guidelines in When to add a changelog entry.
- If your PR does not need a change log, start the PR title with [chore]
Links to the prototypes or existing instrumentations (when adding or changing conventions)

lmolkova · 2025-07-29T15:36:56Z

Is there an instrumentation that needs it? Please also provide links to prototype(s)

thompson-tomo · 2025-08-04T04:23:26Z

yes, there is and the health check example was already linked. Have added client library example as well.

Odonno · 2025-08-04T10:19:58Z

docs/database/surrealdb.md

+| [`db.operation.name`](/docs/registry/attributes/db.md) | string | The name of the operation or command being executed. [9] | `EXECUTE`; `INSERT` | `Recommended` [10] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`db.query.summary`](/docs/registry/attributes/db.md) | string | Low cardinality summary of a database query. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`db.query.text`](/docs/registry/attributes/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`db.stored_procedure.name`](/docs/registry/attributes/db.md) | string | The name of a stored procedure within the database. [15] | `GetCustomer` | `Recommended` [16] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |


question: SurrealDB does not provide a notion of Stored procedure but a similar one named Functions, see https://surrealdb.com/docs/surrealql/statements/define/function. Should we keep the name using Functions, or should we rename that attribute?

Will update the description of the attribute to indicate that these are referred to as functions in surrealdb.

Changes have been made.

Odonno · 2025-08-04T10:28:38Z

docs/database/surrealdb.md

+
+**[1] `db.namespace`:** If a database system has multiple namespace components (e.g. schema name and database name), they SHOULD be concatenated
+from the most general to the most specific namespace component,
+using `|` as a separator between the components.


suggestion: given that SurrealDB has a notion of both namespace & database for each client, shouldn't we add a small section around this specific feature, associated with a proper example? (e.g. Namespace|Database?)

docs/database/surrealdb.md

Odonno · 2025-08-04T10:41:04Z

docs/database/surrealdb.md

+
+**[8] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+
+**[9] `db.operation.name`:** The operation name SHOULD NOT be extracted from `db.query.text`.


suggestion: A good idea would be to list all possible operation names, given we already have that here: https://github.com/surrealdb/surrealdb/blob/3540101309327da9f2f9336a3d0486f4ae41f455/crates/core/src/rpc/method.rs#L3

What I will do is update the description to indicate that the operation name should be set based on the api method being called.

thompson-tomo · 2025-08-05T02:55:53Z

@Odonno it would be appreciated if you could give this another review from the surrealdb perspective. 🙂

Odonno · 2025-08-05T08:20:17Z

docs/database/surrealdb.md

+
+**[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
+
+**[7] `db.operation.name`:** The operation name is to reflect the api method being called ie upsert.


suggestion: I would have expect a list item or table for each operation name, so that every client uses the same name/convention. What do you think?

I have looked at other db provider docs and none of them except for cosmosdb provide table/lists of operation names.

Odonno

Gonna add @kearfy as a second reviewer

Add in Surreal DB open-telemetry#1107

5feed7a

thompson-tomo requested review from a team as code owners July 29, 2025 04:30

github-project-automation bot added this to Semantic Conventions Triage Jul 29, 2025

github-project-automation bot moved this to Untriaged in Semantic Conventions Triage Jul 29, 2025

github-actions bot added enhancement New feature or request area:db labels Jul 29, 2025

Add explicit documentation

edff90b

thompson-tomo force-pushed the feature/#1107_AddSurrealDB branch from db5fa6e to edff90b Compare August 4, 2025 04:22

Odonno reviewed Aug 4, 2025

View reviewed changes

thompson-tomo force-pushed the feature/#1107_AddSurrealDB branch 4 times, most recently from 836c630 to 086d88e Compare August 5, 2025 02:54

Doc cleanup

865b839

thompson-tomo force-pushed the feature/#1107_AddSurrealDB branch from 086d88e to 865b839 Compare August 5, 2025 02:57

Odonno reviewed Aug 5, 2025

View reviewed changes

thompson-tomo changed the title ~~Add in Surreal DB #1107~~ Add in Surreal DB client spans #1107 Aug 5, 2025


		[8] `db.operation.batch.size`: Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.

		[9] `db.operation.name`: The operation name SHOULD NOT be extracted from `db.query.text`.


		[6] `db.operation.batch.size`: Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.

		[7] `db.operation.name`: The operation name is to reflect the api method being called ie upsert.

Add in Surreal DB client spans #1107 #2571

Are you sure you want to change the base?

Add in Surreal DB client spans #1107 #2571

Uh oh!

Conversation

thompson-tomo commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Usage Example

Merge requirement checklist

Uh oh!

lmolkova commented Jul 29, 2025

Uh oh!

thompson-tomo commented Aug 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thompson-tomo Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thompson-tomo commented Aug 5, 2025

Uh oh!

Odonno Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Odonno left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thompson-tomo commented Jul 29, 2025 •

edited

Loading

thompson-tomo Aug 4, 2025 •

edited

Loading

Odonno Aug 5, 2025 •

edited

Loading