From 41bd9f0eb5e36fdd6ae5844433aaa03443884473 Mon Sep 17 00:00:00 2001 From: Loretta Date: Mon, 13 Jul 2026 08:56:51 +0200 Subject: [PATCH] Clarify SignalR log writer docs and comments Updated docs and inline comments to clarify that the generic `AcSignaRClientLogItemWriter` expects the consumer to provide the log item type, typically with `[AcBinarySerializable]`. Improved Hungarian explanations for the diagnostic logger and filtering logic. Refined descriptions in `LOGGING_TODO.md`, `SIGNALR_BINARY_PROTOCOL_TODO.md`, and `README.md` for accuracy and reduced ambiguity. No functional code changes. --- AyCode.Core/docs/LOGGING/LOGGING_TODO.md | 12 ++++++------ .../Loggers/AcSignaRClientLogItemWriter.cs | 6 +++--- AyCode.Services/docs/LOGGING/README.md | 2 +- .../SIGNALR_BINARY_PROTOCOL_TODO.md | 2 +- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/AyCode.Core/docs/LOGGING/LOGGING_TODO.md b/AyCode.Core/docs/LOGGING/LOGGING_TODO.md index 44eab79..f668b85 100644 --- a/AyCode.Core/docs/LOGGING/LOGGING_TODO.md +++ b/AyCode.Core/docs/LOGGING/LOGGING_TODO.md @@ -122,17 +122,17 @@ services.AddAcLoggerFactory(); ### Why this is a separate TODO from ACCORE-LOG-T-R7L3 ACCORE-LOG-T-R7L3 is about the **framework-level decision** (keep both patterns vs deprecate legacy). ACCORE-LOG-T-W4H9 is the **consumer-level execution** of that decision for the server plugin — independent of whether ACCORE-LOG-T-R7L3 ultimately deprecates the legacy path or keeps it alive. Migrating the server plugin removes ACCORE-LOG-I-K7M2 noise regardless of ACCORE-LOG-T-R7L3's outcome. -## ACCORE-LOG-T-D7S3: Protokoll-diagnosztikai logger a log-feltöltő csatornának (szűrt writer-lista) — ⚠️ ÁTGONDOLANDÓ +## ACCORE-LOG-T-D7S3: A SignalR log-feltöltő writer diagnosztikai loggere (szűrt writer-lista) — ⚠️ ÁTGONDOLANDÓ **Priority:** P3 · **Type:** Feature (döntés függőben) · **Related:** `../../../AyCode.Services/docs/SIGNALR_BINARY_PROTOCOL/SIGNALR_BINARY_PROTOCOL_TODO.md#accore-sbp-t-t5r2` -**Státusz: ÁTGONDOLANDÓ — még kérdéses, kell-e egyáltalán. A jelenlegi megoldás (`NullLogger.Instance` a loggerHub AcBinary-protokollján, ld. FruitBank `SignaRClientLogItemWriter.CreateProtocolOptions`) alapvetően jó:** a hiba-út már látható (a writer `ReportFailureOnce` Console.Error-jelentése a `SendAsync`-kivételeknél a serializer-hibákat is elkapja), csak a Debug/Trace-szintű protokoll-trace néma. +**Státusz: ÁTGONDOLANDÓ — még kérdéses, kell-e egyáltalán. A jelenlegi megoldás (a hívó süket loggert — `NullLogger.Instance` — ad a writer kapcsolat-protokolljának) alapvetően jó:** a hiba-út már látható (a writer `ReportFailureOnce` Console.Error-jelentése a `SendAsync`-kivételeknél a serializer-hibákat is elkapja), csak a mély diagnosztikai trace néma. -**Cél (ha bevezetjük):** a log-feltöltő csatorna (`AcSignaRClientLogItemWriter`) protokollja süket logger helyett diagnosztikai loggert kapjon, amiből a feltöltő writer **strukturálisan ki van szűrve** — a visszacsatolási hurok (log → sorosítás → protokoll-log → feltöltés → …) bekötése így lehetetlen marad, de a protokoll-diagnosztika a host TÖBBI writerére (konzol, fájl, DB — bármi, amit a host regisztrál) kimegy, és automatikusan követi a jövőbeli writer-regisztrációkat. +**Cél (ha bevezetjük):** az `AcSignaRClientLogItemWriter` kapcsolat-diagnosztikája süket logger helyett olyan loggert kapjon, amiből a feltöltő writer **strukturálisan ki van szűrve** — a visszacsatolási hurok (log → sorosítás → diagnosztika-log → feltöltés → …) bekötése így lehetetlen marad, a diagnosztika viszont a host TÖBBI writerére (konzol, fájl, DB — bármi regisztrált) kimegy, és automatikusan követi a jövőbeli writer-regisztrációkat. **Megbeszélt terv (2026-07):** 1. `IAcSignalRLogWriter` marker-interfész az `AcSignaRClientLogItemWriter`-re — a szűrés típus-alapú: `writers.Where(w => w is not IAcSignalRLogWriter).ToList()` (saját, materializált lista az új loggernek). -2. A diagnosztikai logger **üresen** születik — a szűrt lista a feltöltő ctorába NEM injektálható (körkörös DI: a feltöltő maga is eleme az `IEnumerable`-nek). A host `Build()` után tölti fel: `host.Services.GetServices().Where(…).ToList()` → `SetWriters(…)`. +2. A diagnosztikai logger **üresen** születik — a szűrt lista a feltöltő ctorába NEM injektálható (körkörös DI: a feltöltő maga is eleme az `IEnumerable`-nek). A host `Build()` után tölti fel: `GetServices().Where(…).ToList()` → `SetWriters(…)`. 3. Keret-kiegészítés kell: `AcLoggerBase.SetWriters`/`AddWriters` (a `LogWriters` jelenleg protected). -4. Default szint: Debug — a Trace-re átsorolt per-üzenet protokoll-sorokkal (ACCORE-SBP-T-T5R2) normál üzemben csend; debugkor Detail/Trace-re engedve jön a teljes trace. +4. Default szint: Debug — a soronkénti trace zajszintje protokoll-oldali kérdés, ld. ACCORE-SBP-T-T5R2. -**Ismert apró rés:** az első pár protokoll-sor (handshake, induló `StartAsync`) még az üres loggert látja — a Trace-átsorolás után gyakorlatilag irreleváns. +**Ismert apró rés:** a kapcsolat-felépítés első diagnosztika-sorai még az üres loggert látják — elhanyagolható. diff --git a/AyCode.Services/Loggers/AcSignaRClientLogItemWriter.cs b/AyCode.Services/Loggers/AcSignaRClientLogItemWriter.cs index e61de88..fdbec43 100644 --- a/AyCode.Services/Loggers/AcSignaRClientLogItemWriter.cs +++ b/AyCode.Services/Loggers/AcSignaRClientLogItemWriter.cs @@ -20,9 +20,9 @@ namespace AyCode.Services.Loggers } /// - /// SignalR log-item feltöltő writer, generikus wire-típussal. A -et az - /// alkalmazás adja (pl. FruitBank: FbLogItem [AcBinarySerializable] — így a csatorna AcBinary-protokollal mehet; - /// a generált serializer az app rétegében él, az AyCode.Entities generator-mentes marad). + /// SignalR log-item feltöltő writer, generikus wire-típussal. A -et a fogyasztó + /// adja (tipikusan egy [AcBinarySerializable]-lel jelölt AcLogItemClient-leszármazott — így a csatorna + /// AcBinary-protokollal mehet; a generált serializer a fogyasztó rétegében él, az AyCode.Entities generator-mentes marad). /// Az opcionális acBinaryProtocolOptions-szel a kapcsolat az AcBinary protokollt használja; /// enélkül a SignalR default JSON-ja megy (back-compat). /// diff --git a/AyCode.Services/docs/LOGGING/README.md b/AyCode.Services/docs/LOGGING/README.md index 5fa0b90..37389ad 100644 --- a/AyCode.Services/docs/LOGGING/README.md +++ b/AyCode.Services/docs/LOGGING/README.md @@ -26,7 +26,7 @@ Note: `Forget()` — fire-and-forget, no await on the HTTP response. HTTP/2 by d ## AcSignaRClientLogItemWriter -SignalR log transport writer, generic in the wire type (2026-07): `AcSignaRClientLogItemWriter : AcLogItemWriterBase` — the app supplies its own `TLogItem` (e.g. FruitBank's `LogItemClient : AcLogItemClient` with `[AcBinarySerializable]`, so the generated serializer lives in the app layer and AyCode.Entities stays generator-free). The non-generic `AcSignaRClientLogItemWriter` shim (= ``, JSON) keeps existing consumers working. Sends items to a dedicated logger hub. Manages its own `HubConnection`: +SignalR log transport writer, generic in the wire type (2026-07): `AcSignaRClientLogItemWriter : AcLogItemWriterBase` — the consumer supplies its own `TLogItem : AcLogItemClient` (typically marked `[AcBinarySerializable]`, so the generated serializer lives in the consumer layer and AyCode.Entities stays generator-free). The non-generic `AcSignaRClientLogItemWriter` shim (= ``, JSON) keeps existing consumers working. Sends items to a dedicated logger hub. Manages its own `HubConnection`: ```csharp await _hubConnection.SendAsync("AddLogItem", logItem); diff --git a/AyCode.Services/docs/SIGNALR_BINARY_PROTOCOL/SIGNALR_BINARY_PROTOCOL_TODO.md b/AyCode.Services/docs/SIGNALR_BINARY_PROTOCOL/SIGNALR_BINARY_PROTOCOL_TODO.md index 20db2f8..c4640ef 100644 --- a/AyCode.Services/docs/SIGNALR_BINARY_PROTOCOL/SIGNALR_BINARY_PROTOCOL_TODO.md +++ b/AyCode.Services/docs/SIGNALR_BINARY_PROTOCOL/SIGNALR_BINARY_PROTOCOL_TODO.md @@ -11,7 +11,7 @@ ## ACCORE-SBP-T-T5R2: Per-üzenet diagnosztikai sorok átsorolása Trace szintre **Priority:** P2 · **Type:** Behaviour / zajcsökkentés · **Related:** `../../../AyCode.Core/docs/LOGGING/LOGGING_TODO.md#accore-log-t-d7s3` -**Probléma:** a protokoll soronkénti diagnosztikája túl magas szinten logol — `Serialize/Deserialize start/end` = **Info**, `WriteArgument`/`ReadSingleArgument`/`ReadArguments`/`ParseInvocation`/`TryParseMessage` = **Debug/Trace**. Következmény: a szerver-konzolt elárasztja (a loggerHub-on MINDEN felküldött log-item ~8 protokoll-sort termel; az fbHub-forgalom ugyanígy), és egy leendő kliens-oldali protokoll-diagnosztika (ACCORE-LOG-T-D7S3) default szinten spammelne. +**Probléma:** a protokoll soronkénti diagnosztikája túl magas szinten logol — `Serialize/Deserialize start/end` = **Info**, `WriteArgument`/`ReadSingleArgument`/`ReadArguments`/`ParseInvocation`/`TryParseMessage` = **Debug/Trace**. Következmény: minden hub-üzenet ~4–8 diagnosztika-sort termel a protokoll-loggerrel rendelkező oldalon — nagy forgalomnál konzol-áradat, és egy mindig-bekötött diagnosztikai logger (ld. ACCORE-LOG-T-D7S3) default szinten spammelne. **Megoldás:** a per-üzenet sorok `LogTrace`-re; hiba/anomália marad Warning/Error. A `Serialize end totalSentSize=…` jellegű összegző sorok szintje mérlegelendő (Debug-on hagyva olcsó forgalmi áttekintést adnak).