docs: backend logging convention#100
Merged
Merged
Conversation
Adds local-dev/logging.md describing the five-method Logger (info/event/debug/error/scope), service-injection model, handle<X>(deps) route factory pattern, and dual stdout-human / file-JSON output. Loosely ported from github.com/AquiGorka/go-logger so behavior parallels the Go reference. Logger and OTEL stay independent — OTEL coverage is a follow-up thread. README links to the new doc from the existing debugging section.
This was referenced May 27, 2026
Merged
AquiGorka
added a commit
to Moonlight-Protocol/network-dashboard-platform
that referenced
this pull request
May 31, 2026
## Summary Adopts the convention defined in [`local-dev/logging.md`](Moonlight-Protocol/local-dev#100). First of four backend migrations (provider/council/pay are pending). - **New Logger** at `src/utils/logger/index.ts` — TS port of [AquiGorka/go-logger](https://github.com/AquiGorka/go-logger). Five methods (`info`, `event`, `debug`, `error`, `scope`), four levels (`Debug`, `Info`, `Event`, `Disabled`), nested scopes, dual stdout-human / file-JSON output. - **No module-level singleton.** `src/config/logger.ts` now exports `createLogger()`; `main.ts` is the only construction site and threads `{ log, bus }` through to every service and free function. - **`NetworkEventBus`** becomes a DI'd class — takes `{ log }` in its constructor, no longer exported as a singleton. The stray `console.warn` in its `publish()` catch is now `log.error`. - **HTTP routes** use the `handle<X>(deps)` factory pattern. `handleNetworkWs(deps)` returns the request handler; `buildNetworkWsRouter(deps)` and `buildApiRouter(deps)` wire it up. - **Sync free functions** (`refreshWasmRegistry`, `fetchCouncilTopology`, `refreshTopology`, `coldStartScan`, `evaluateUnknownContract`, `drainPendingAdoptions`, `startSorobanWatcher`, `startScheduler`) all take `{ log, bus }` deps and scope internally via `log.scope("funcName")`. - **Removed** the local `describeErr()` helper — the new Logger handles error stringification for both human and JSON sinks via `instanceof Error` / `safeJsonValue`. - **Migrated all 42 LOG calls** + the one stray `console.warn` per the convention's mapping rules. No OTEL changes (this repo has no OTEL today). ## Logging coverage | Subsystem | Levels emitted | |---|---| | HTTP routes (`handleNetworkWs`) | info, event, debug, error | | Background services (soroban-watcher, scheduler) | info, event, debug, error | | External API calls (council-platform, GitHub releases, Stellar RPC) | info, event, debug, error | | Error paths | error | | Bootstrap (`main.ts`) | info, event, debug, error | ## Verified locally (pre-push) - `deno fmt --check`: clean - `deno lint`: clean (22 files) - `deno task test`: 17 passed, 0 failed - `deno task check`: clean - `grep -rn 'LOG\.(...)' src/`: 0 hits - `grep -rn 'console\.(...)' src/`: 0 hits - `grep -rn 'describeErr' src/`: 0 hits ## Test plan - [ ] CI green on this branch - [ ] PM merges PR #100 (logging convention doc) first, then this - [ ] Smoke test locally with `LOG_LEVEL=info` via `local-dev/up.sh` to confirm output format matches the spec Last commit (`chore: bump version to 0.1.4`) is the patch-bump-alone commit per the open-pr-checklist.
AquiGorka
added a commit
to Moonlight-Protocol/provider-platform
that referenced
this pull request
May 31, 2026
## Summary Adopts the convention defined in [`local-dev/logging.md`](Moonlight-Protocol/local-dev#100). Final repo of the 4-repo backend logging migration. - **New Logger** at `src/utils/logger/index.ts` — TS port of [AquiGorka/go-logger](https://github.com/AquiGorka/go-logger). Five methods, four levels. - **`src/config/logger.ts`** exports `createLogger()`. No singleton. - **Service classes** (`Mempool`, `Executor`, `Verifier`, `MetricsCollector`, `EventWatcher`, `ChannelRegistry`, `EventBus`, `InMemorySessionManager`) take `{ log }` via constructor or `setLogger()`. - **HTTP handler factories**: every handler in `stellar/auth/*`, `bundle/*`, `dashboard/*` (auth, utxos, treasury, audit-export, transactions, pp, council, bundle-admin), `pay/*` (kyc, transactions, self/balance, custodial/*, demo/*, escrow/*, report) becomes `handle<X>(deps)`. Sub-routers become `build<X>Router(deps)`. - **`appendRequestIdMiddleware`** becomes a factory. - **`log-and-throw` helper retired** — all 10 `logAndThrow(...)` call sites replaced with bare `throw`. - **Free service functions** (`createDashboardChallenge`, `verifyDashboardChallenge`, `queryBalances`, `createEscrow`, `claimEscrowForAddress`, `getEscrowSummary`, `emit-helpers`) take deps. - **All 163 LOG calls + 2 stray console.warn migrated.** `LOG.trace` dropped. - **`PLG_ProcessErrorResponse`** takes optional deps to keep pipeline factories caller-compatible. - **No OTEL changes** — `withSpan`, `span.addEvent`, `tracer.startSpan` all preserved. ## Logging coverage | Subsystem | Levels emitted | |---|---| | HTTP routes (stellar/auth, bundle, dashboard, pay, events, waitlist) | info, event, debug, error | | Background services (Mempool, Executor, Verifier, EventWatcher, MetricsCollector) | info, event, debug, error | | DB layer (event-driven status updates) | event, error | | External APIs (Stellar RPC, Horizon, council-platform) | info, event, debug, error | | Error paths | error | ## Verified locally (pre-push) - `deno fmt --check`: clean - `deno lint`: clean - `deno task test:unit`: 60 passed, 0 failed - `deno task test:pay`: 136 passed, 0 failed - `grep -rn 'LOG\.(...)' src/`: 0 hits - `grep -rn 'console\.(...)' src/` (excl logger module + node_modules): 0 hits ## Test plan - [ ] CI green - [ ] Merge after local-dev PR #100 lands
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
logging.md— the convention every backend platform follows once the per-repo migration PRs land. Loosely ports AquiGorka/go-logger to TypeScript.Key points the doc pins down:
info(msg),event(msg),debug(key, value),error(err, msg),scope(name). No warn / fatal / trace.Debug < Info < Event < Disabled.erroralways emits regardless of level..(log.scope("a").scope("b")→main.a.b).{ log: Logger; ... }.handle<Operation>(deps): (ctx) => .... Noctx.state.log.LOG.info("X", { a, b })collapses tolog.info(funcName)+log.debug("a", a)+log.debug("b", b)+log.event("X"). ExistingLOG.warnsplits betweenerrorandeventby intent.README's "Debugging test failures with traces" section gets a one-sentence pointer to the new doc.
Test plan
logging.mdend-to-end and confirms the convention matches intentNo code in this PR — convention only.
deno.jsonhas noversionfield in this repo, so no patch bump.