Add debug logging to @ydbjs/coordination

- Add 'coordination' category to @ydbjs/debug loggers
- Log session lifecycle: start, ready, close, destroy, reconnect, expiry
- Log all semaphore operations: acquire, release, create, update, delete, describe, watch
- Log stream events: open, close, send/recv messages, protocol frames (ping/pong, started, stopped, failure)
- Log node management: describe, create, alter, drop
- Log client-level operations: createSession, openSession, withSession
- Use loggers.coordination.extend('session|stream|client|node') for scoped namespaces

Author: polRk

packages/coordination/src/client.ts

@@ -1,10 +1,13 @@
 import type { Driver } from '@ydbjs/core'
+import { loggers } from '@ydbjs/debug'
 
 import { CoordinationNodeRuntime } from './runtime/node-runtime.js'
 import { getSessionRuntime } from './internal/session-runtime.js'
 import type { CoordinationNodeConfig, CoordinationNodeDescription } from './runtime/node-runtime.js'
 import { CoordinationSession } from './session.js'
 
+let dbg = loggers.coordination.extend('client')
+
 export interface SessionOptions {
 	description?: string
 	recoveryWindow?: number
@@ -22,18 +25,22 @@ export class CoordinationClient {
 	}
 
 	describeNode(path: string, signal?: AbortSignal): Promise<CoordinationNodeDescription> {
+		dbg.log('describeNode path=%s', path)
 		return this.#nodeRuntime.describe(path, signal)
 	}
 
 	createNode(path: string, config: CoordinationNodeConfig, signal?: AbortSignal): Promise<void> {
+		dbg.log('createNode path=%s', path)
 		return this.#nodeRuntime.create(path, config, signal)
 	}
 
 	alterNode(path: string, config: CoordinationNodeConfig, signal?: AbortSignal): Promise<void> {
+		dbg.log('alterNode path=%s', path)
 		return this.#nodeRuntime.alter(path, config, signal)
 	}
 
 	dropNode(path: string, signal?: AbortSignal): Promise<void> {
+		dbg.log('dropNode path=%s', path)
 		return this.#nodeRuntime.drop(path, signal)
 	}
 
@@ -46,12 +53,15 @@ export class CoordinationClient {
 			throw signal.reason
 		}
 
+		dbg.log('createSession path=%s', path)
 		let session = new CoordinationSession(this.#driver, { path, ...options }, signal)
 
 		try {
 			await getSessionRuntime(session).waitReady(signal)
+			dbg.log('createSession ready path=%s sessionId=%s', path, session.sessionId)
 			return session
 		} catch (error) {
+			dbg.log('createSession failed path=%s %O', path, error)
 			session.destroy(error)
 			throw error
 		}
@@ -62,8 +72,10 @@ export class CoordinationClient {
 		options?: SessionOptions,
 		signal?: AbortSignal
 	): AsyncIterable<CoordinationSession> {
+		dbg.log('openSession started path=%s', path)
 		for (;;) {
 			if (signal?.aborted) {
+				dbg.log('openSession stopped (signal aborted) path=%s', path)
 				return
 			}
 
@@ -74,8 +86,11 @@ export class CoordinationClient {
 			// oxlint-disable-next-line no-await-in-loop
 			let shouldOpenNext = await shouldOpenNextSession(session, signal)
 			if (!shouldOpenNext) {
+				dbg.log('openSession ended (no reconnect needed) path=%s', path)
 				return
 			}
+
+			dbg.log('openSession reconnecting path=%s', path)
 		}
 	}
 
@@ -85,11 +100,13 @@ export class CoordinationClient {
 		options?: SessionOptions,
 		signal?: AbortSignal
 	): Promise<T> {
+		dbg.log('withSession path=%s', path)
 		let session = await this.createSession(path, options, signal)
 
 		try {
 			return await callback(session)
 		} finally {
+			dbg.log('withSession closing path=%s', path)
 			await session.close(signal)
 		}
 	}

packages/coordination/src/runtime/node-runtime.ts

@@ -16,9 +16,12 @@ import {
 import { StatusIds_StatusCode } from '@ydbjs/api/operation'
 import type { Entry } from '@ydbjs/api/scheme'
 import type { Driver } from '@ydbjs/core'
+import { loggers } from '@ydbjs/debug'
 import { YDBError } from '@ydbjs/error'
 import type { Client } from 'nice-grpc'
 
+let dbg = loggers.coordination.extend('node')
+
 export interface CoordinationNodeConfig {
 	selfCheckPeriod?: number
 	sessionGracePeriod?: number
@@ -41,6 +44,7 @@ export class CoordinationNodeRuntime {
 	}
 
 	async describe(path: string, signal?: AbortSignal): Promise<CoordinationNodeDescription> {
+		dbg.log('describe path=%s', path)
 		let request = create(DescribeNodeRequestSchema, { path })
 		let response = signal
 			? await this.#client.describeNode(request, { signal })
@@ -72,6 +76,7 @@ export class CoordinationNodeRuntime {
 	}
 
 	async create(path: string, cfg: CoordinationNodeConfig, signal?: AbortSignal): Promise<void> {
+		dbg.log('create path=%s', path)
 		let request = create(CreateNodeRequestSchema, { path, config: toNodeConfigMessage(cfg) })
 		let response = signal
 			? await this.#client.createNode(request, { signal })
@@ -88,6 +93,7 @@ export class CoordinationNodeRuntime {
 	}
 
 	async alter(path: string, cfg: CoordinationNodeConfig, signal?: AbortSignal): Promise<void> {
+		dbg.log('alter path=%s', path)
 		let request = create(AlterNodeRequestSchema, { path, config: toNodeConfigMessage(cfg) })
 		let response = signal
 			? await this.#client.alterNode(request, { signal })
@@ -104,6 +110,7 @@ export class CoordinationNodeRuntime {
 	}
 
 	async drop(path: string, signal?: AbortSignal): Promise<void> {
+		dbg.log('drop path=%s', path)
 		let request = create(DropNodeRequestSchema, { path })
 		let response = signal
 			? await this.#client.dropNode(request, { signal })