Skip to content

Map bridge/2DC pool topology in @ydbjs/telemetry#642

Open
polRk wants to merge 1 commit into
mainfrom
claude/quizzical-leavitt-4131e0
Open

Map bridge/2DC pool topology in @ydbjs/telemetry#642
polRk wants to merge 1 commit into
mainfrom
claude/quizzical-leavitt-4131e0

Conversation

@polRk

@polRk polRk commented Jul 15, 2026

Copy link
Copy Markdown
Member

What

Wire the bridge (2DC) topology diagnostics_channel events that @ydbjs/core now publishes into @ydbjs/telemetry OTel spans and metrics.

Why

Core's endpoints engine gained bridge/pool observability (8f0fc0f), but @ydbjs/telemetry only mapped the ydb.node.pile connection attribute. The new discovery.completed fields (selfLocation, piles, primaryPile) and the new pool.opened / pool.stats / pile.changed / pile.fallback channels went unconsumed, so bridge topology and the aggregate routing snapshot were invisible in traces and metrics. This completes the mapping.

Changes

  • Traces (channels.ts, semconv/{spans,events}.ts)
    • ydb:driver.discovery.completed also sets ydb.discovery.self_location and ydb.discovery.primary_pile on the ydb.Discovery span (dropped off-bridge).
    • New event mapping: ydb:driver.pile.changedydb.driver.pile.changed span event with ydb.driver.pile.primary_before/primary_after. It fires inside the discovery span (in publishRoundDiagnostics), so it attaches; the structured roster stays on the bus.
  • Metrics (metrics.ts, state/connection-pool.ts, semconv/metrics.ts)
    • Observable gauges from ydb:driver.connection.pool.stats, keyed by DriverIdentity: ydb.driver.pool.routable (tag ydb.routing.tier ∈ {prefer, fallback}), ydb.driver.pool.pessimized, ydb.driver.pool.nodes (per pile, tagged ydb.pile.name/ydb.pile.status).
    • ydb:driver.connection.pool.opened config folded into per-driver state; preferPrimaryPile/localityEnabled ride the routable gauge as tags (they define what prefer/fallback mean; one fixed value per driver → bounded cardinality).
    • Counters ydb.driver.pile.fallbacks (tagged ydb.pile.fallback.active) and ydb.driver.pile.changes. State cleared on ydb:driver.closed.
    • pool.stats / pile.fallback fire outside any span (async consume loop) → metrics-only, never attached to a span, per the producer contract.
  • Docs: extend the telemetry changeset (bumped patch → minor — new instruments/attributes are a backwards-compatible feature) and the README channel/instrument tables + cardinality budget.

No breaking changes — purely additive.

Testing

  • New packages/telemetry/src/bridge.test.ts (10 tests): span-event assertions (discovery attrs bridge + non-bridge, pile.changed event) and metric-reader assertions (all three pool gauges, routing-mode tags present/absent, both counters, teardown on driver.closed). Placed under src/ (the uni project) since they have no external deps.
  • npx vitest --run --project uni packages/telemetry/src — 16 pass.
  • Full uni suite — 1033 pass / 1 skipped (no regressions).
  • Existing int telemetry suites (metrics, propagation) — 30 pass.
  • cd packages/telemetry && npx tsc --noEmit clean; oxlint packages/telemetry/src clean.

Checklist

  • Changeset added (if package changes)
  • README updated (if public API changed)

Wire the new @ydbjs/core bridge (2DC) diagnostics_channel events into
OTel spans and metrics, completing the mapping that previously only
carried the ydb.node.pile connection attribute.

- Traces: set ydb.discovery.self_location / ydb.discovery.primary_pile
  on the Discovery span from discovery.completed; record a
  ydb.driver.pile.changed span event (primary before/after) that fires
  inside the discovery span.
- Metrics: observable gauges ydb.driver.pool.{routable,pessimized,nodes}
  reconstructed from ydb:driver.connection.pool.stats (routing tier,
  per-pile node counts), with routing mode folded in from pool.opened;
  counters ydb.driver.pile.{fallbacks,changes}. All keyed by driver
  identity and cleared on driver.closed. pool.stats / pile.fallback are
  metrics-only (fire outside any span).
- Tests: cover the new span-event and metric-reader mappings.
- Update the telemetry changeset (bump minor — new instruments/attrs)
  and README channel enumeration.
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.

2 participants