OpenTelemetry tracing support by tewbo · Pull Request #786 · ydb-platform/ydb-python-sdk

tewbo · 2026-03-21T03:32:03Z

Pull request type

What is the current behavior?

The YDB Python SDK does not provide built-in OpenTelemetry tracing support. There is legacy integration with OpenTracing API which uses the deprecated standard.

Issue Number: N/A

What is the new behavior?

Adds OpenTelemetry tracing support to the YDB Python SDK. When enabled via enable_tracing(), the SDK automatically creates spans for key operations:

ydb.CreateSession — session creation
ydb.ExecuteQuery — query execution (session and transaction level, both sync and async)
ydb.Commit / ydb.Rollback — transaction commit and rollback
ydb.Driver.Initialize — driver initialization

Each span includes standard attributes: db.system.name, db.namespace, server.address, server.port, ydb.session.id, ydb.node.id, ydb.tx.id.

W3C Trace Context (traceparent) is automatically propagated in gRPC metadata, enabling end-to-end distributed tracing between client and YDB server. Execute spans cover the full operation lifecycle, including streaming result iteration — not just the initial gRPC call. Errors are recorded on spans with error.type, db.response.status_code, and exception events.

Tracing is opt-in (pip install ydb[tracing] + enable_tracing()). Without it, the SDK behavior is unchanged — all tracing code paths are no-op.

Other information

Includes unit tests for sync, async, error handling, parent-child relationships, context propagation, noop mode, and concurrent span isolation

Query-service retries now emit an umbrella INTERNAL ydb.RunWithRetry span and a ydb.Try INTERNAL span per attempt. Each ydb.Try carries the ydb.retry.backoff_ms attribute (the sleep preceding the attempt — 0 for the first one, i.e. the next-attempt timeline includes the backoff). Retriable exceptions are recorded on the owning ydb.Try span, and an exception that escapes the whole retry loop (including an asyncio.CancelledError hitting a backoff sleep) is recorded on the outer ydb.RunWithRetry span. CLIENT spans (ydb.CreateSession, ydb.ExecuteQuery, ydb.Commit, ydb.Rollback) now also emit network.peer.address / network.peer.port for the concrete node serving the session, while server.address / server.port keep meaning the host from the connection string. Also fixes a "Пр" typo in docs/opentelemetry.rst and corrects span names (ydb.CommitTransaction -> ydb.Commit, ydb.RollbackTransaction -> ydb.Rollback). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Move ydb.RunWithRetry / ydb.Try span emission directly into retry_operation_sync / retry_operation_async in ydb/retries.py, and drop the short-lived ydb.query._retries shim. Tracing is still no-op by default, so there is no cost for the table-service callers that share the same retry loop; we just stop duplicating the retry logic to add spans. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…p session.id/tx.id RPC (CLIENT-kind) spans now carry the peer metadata from the discovery endpoint map, not from the grpc-target string of the request: * network.peer.address = EndpointInfo.address (the node host) * network.peer.port = EndpointInfo.port * ydb.node.dc = EndpointInfo.location To do that, EndpointOptions and Connection now also carry address/port/ location populated by resolver.endpoints_with_options(); sessions resolve their peer tuple via driver._store.connections_by_node_id after CreateSession returns, which is the right place to ask which node owns this session. Dropped the noisy ydb.session.id and ydb.tx.id attributes - they pollute every span and are recoverable from trace context if really needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

vgvoleg

Поправьте замечания и сделайте rebase на свежий main.

# Conflicts: # CHANGELOG.md # ydb/aio/query/base.py # ydb/query/base.py

robot-vibe-db · 2026-05-01T11:24:55Z

AI Review Summary

Verdict: ✅ No critical issues found

Critical issues

No critical issues found.

Other findings

Minor | High: Docs say ydb.retry.backoff_ms is "0 for the first one" but the code omits the attribute entirely on the first ydb.Try span — docs/opentelemetry.rst:108
Minor | Medium: __del__ in response iterators calls ContextVar.reset(token) which can raise ValueError if GC runs the finaliser in a different execution context, producing noisy stderr warnings — ydb/query/base.py:124, ydb/aio/query/base.py:49
Minor | Low: Outer except Exception in execute() methods ends the span but does not pop the gRPC propagation token, leaking a stale ContextVar value if the iterator constructor raises — ydb/query/session.py:536 (same pattern in transaction.py and aio/query/session.py)
Nit | High: Copy-paste artifact in "Typical local run" docs — cd ../.. followed by duplicated commands that would fail outside the repo root — docs/opentelemetry.rst:248-250

This review was generated automatically. Critical issues require attention; other findings are advisory.
If this comment was useful, please give it a 👍 — it helps us improve the review bot.

KirillKurdyukov · 2026-05-02T08:13:38Z

robot-vibe-db

AI Review Summary

Verdict: ✅ No critical issues found

Critical issues

No critical issues found.

Other findings

Major | High: Async Connection class is missing peer_address, peer_port, peer_location slots/init — network.peer.* and ydb.node.dc span attributes are silently never populated in the async path — ydb/aio/connection.py:143-165

This review was generated automatically. Critical issues require attention; other findings are advisory.
If this comment was useful, please give it a 👍 — it helps us improve the review bot.

tewbo added 2 commits March 21, 2026 06:27

+ otel sync tracing support

6490021

+ add async spans

5998749

tewbo marked this pull request as draft March 23, 2026 10:36

KirillKurdyukov self-requested a review March 23, 2026 13:47

tewbo added 6 commits March 24, 2026 07:47

+ test and refactor

db01212

* format

acdc32f

* add otel to test requirements

7bf72a9

fix black checkstyle

74cc57d

fix flake8 checkstyle

de1d6d9

make property from driver config

3dda417

tewbo marked this pull request as ready for review March 24, 2026 07:02

KirillKurdyukov reviewed Mar 24, 2026

View reviewed changes

Comment thread ydb/opentelemetry/_plugin.py Outdated

vgvoleg requested changes Mar 27, 2026

View reviewed changes

Comment thread setup.py Outdated

Comment thread examples/opentelemetry/example.py Outdated

Comment thread ydb/opentelemetry/_plugin.py Outdated

tewbo added 3 commits April 4, 2026 21:56

Merge remote-tracking branch 'upstream/main' into otel-tracing-support

7c620ae

add docs and fix pr review comments

b574b77

fix checkstyle and tests

7af5e2c

tewbo marked this pull request as draft April 9, 2026 17:56

ci: retry failed workflow

3e6b95e

tewbo marked this pull request as ready for review April 9, 2026 18:15

KirillKurdyukov and others added 3 commits April 20, 2026 14:38

vgvoleg requested changes Apr 22, 2026

View reviewed changes

KirillKurdyukov added 5 commits May 1, 2026 09:33

fix issue

70b778d

fix issue

c66205a

Merge remote-tracking branch 'origin/main' into otel-tracing-support

29a76ac

# Conflicts: # CHANGELOG.md # ydb/aio/query/base.py # ydb/query/base.py

fix issue

bce0e02

fix issue

60b9a58

vgvoleg added the need_ai_review label May 1, 2026

robot-vibe-db Bot removed the need_ai_review label May 1, 2026

robot-vibe-db Bot added the ai_review_in_process label May 1, 2026

robot-vibe-db Bot reviewed May 1, 2026

View reviewed changes

Comment thread docs/opentelemetry.rst Outdated

Comment thread docs/opentelemetry.rst Outdated

Comment thread ydb/query/base.py Outdated

Comment thread ydb/query/session.py

robot-vibe-db Bot added ai_reviewed and removed ai_review_in_process labels May 1, 2026

KirillKurdyukov added 6 commits May 2, 2026 09:21

fix issue

31b2cf2

fix issue

763052a

fix issue

dd60ff0

fix issue

93fa974

fix issue

c4e304d

added ydb.BeginTransaction

0beb6d0

KirillKurdyukov added 8 commits May 2, 2026 19:15

added healthcheck

0220d7e

micro refactoring

e6721d0

added tests

135916b

refactoring

b5264e2

fix linter

75f95ea

fix linter

9ec6959

fix linter

515d57c

fix linter

fc01331

vgvoleg added need_ai_review and removed ai_reviewed labels May 4, 2026

robot-vibe-db Bot added ai_review_in_process and removed need_ai_review labels May 4, 2026

robot-vibe-db Bot reviewed May 4, 2026

View reviewed changes

Comment thread ydb/aio/connection.py

robot-vibe-db Bot added ai_reviewed and removed ai_review_in_process labels May 4, 2026

fix issue

e6deab1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenTelemetry tracing support#786

OpenTelemetry tracing support#786
tewbo wants to merge 35 commits intoydb-platform:mainfrom
tewbo:otel-tracing-support

tewbo commented Mar 21, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vgvoleg left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

robot-vibe-db Bot commented May 1, 2026

Uh oh!

KirillKurdyukov commented May 2, 2026

Uh oh!

robot-vibe-db Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

tewbo commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request type

What is the current behavior?

What is the new behavior?

Other information

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vgvoleg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

robot-vibe-db Bot commented May 1, 2026

AI Review Summary

Critical issues

Other findings

Uh oh!

KirillKurdyukov commented May 2, 2026

Uh oh!

robot-vibe-db Bot left a comment

Choose a reason for hiding this comment

AI Review Summary

Critical issues

Other findings

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tewbo commented Mar 21, 2026 •

edited

Loading