Bevezetés

A Konalytics v2 a Konasoft Kft. univerzális tevékenységnaplózó rendszere. A rendszer automatikusan rögzíti az alkalmazások HTTP forgalmát, és részletes betekintést nyújt a felhasználói viselkedésbe, az alkalmazáshasználati mintákba, valamint teljes körűen támogatja az audit követelményeket.

Az első verzióhoz képest a v2 teljesen újraírt, modern microservice architektúrára épülő rendszer. Az integrációhoz mindössze a NuGet csomag telepítése és néhány sornyi konfiguráció szükséges — a middleware automatikusan rögzít minden HTTP kérést.

A Konalytics v2 a következő funkciókat kínálja:

1. Automatikus naplózás — Minden HTTP kérés rögzítése middleware segítségével, konfiguráció nélkül
2. Adatvesztés-mentes működés — Háttérkötegelés, intelligens újrapróbálkozás és HDD alapú fallback
3. Intelligens entitásfelismerés — URL-ekből automatikus üzleti entitás azonosítás
4. Egyéni események és munkamenetek — Programozható API tetszőleges üzleti események rögzítéséhez
5. Admin felület — Vue 3 alapú dashboard, keresés, tevékenységtípus-kezelés
6. Entity Linking — Utólagos entitás-összerendelés audit trail-lel
7. Egyszerű integráció — NuGet csomag + Docker Compose telepítés

Architektúra

Technológiák

tovább

Automatikus naplózás

A Konalytics.Client NuGet csomag ActivityLoggingMiddleware komponense automatikusan elfogja az összes bejövő HTTP kérést, és a háttérben rögzíti azokat. Semmilyen közvetlen beavatkozás nem szükséges a meglévő controllerekben vagy endpointokban.

Rögzített adatok

Adat	Leírás	Példa
URL pattern	Normalizált URL minta	/api/users/{id}
HTTP metódus	GET, POST, PUT, DELETE, PATCH	GET
Végrehajtási idő	Kérésfeldolgozás ideje (ms)	142 ms
Státuszkód	HTTP válasz kódja	200, 404
Felhasználó ID	JWT claim-ből (konfigurálható)	sub claim
Request payload	POST/PUT/PATCH kérés törzse	Max 16 KB (konfig.)
IP cím	Kliens IP címe	192.168.1.42
Session kulcs	Munkamenet azonosító	Claim vagy ASP.NET Session
Entity type	Felismert entitás típusa	users
Entity ID	Felismert entitás azonosítója	123

Intelligens URL pattern felismerés

A middleware automatikusan felismeri az üzleti entitásokat a REST URL-ekből, konvenció alapján:

Eredeti URL	Pattern	Entity Type	Entity ID
/api/users/123	/api/users/{id}	users	123
/api/projects/5/tasks/42	/api/projects/{id}/tasks/{id}	tasks	42
/api/tasks/by-project/201	/api/tasks/by-project/{id}	project	201
/api/health	/api/health	—	—

Speciális URL-mintákhoz egyéni entity type mapping definiálható az appsettings.json-ben:

{
  "Konalytics": {
    "ExcludedPaths": ["/health", "/metrics", "/swagger"],
    "MaxPayloadSizeKb": 16,
    "UserIdClaimType": "sub",
    "EntityTypeMappings": [
      { "UrlPrefix": "/api/user-profiles", "EntityType": "UserProfile" },
      { "UrlPrefix": "/api/org-units", "EntityType": "OrganizationUnit" }
    ]
  }
}

        vissza tovább

Háttérfeldolgozás és megbízhatóság

A Konalytics v2 úgy lett tervezve, hogy egyetlen tevékenység sem veszhet el, még hálózati hiba, szerverleállás vagy magas terhelés esetén sem. Ezt többszintű biztonsági mechanizmussal éri el.

Háttérkötegelés (Batching)

A BackgroundEventQueue komponens a System.Threading.Channels infrastruktúrára épül, és a háttérben kötegeli a tevékenységeket mielőtt elküldi a service-nek:

Paraméter	Alapérték	Leírás
BatchSize	100	Ennyi elemet gyűjt össze egy kötegben
FlushIntervalSeconds	5	Ennyi másodperc után küldi el a kötegelt adatokat
Csatorna méret	10 000	Maximum ennyi elem vár a csatornában
RetryCount	2	Újrapróbálkozások száma hiba esetén
RetryDelayMs	1000	Alap várakozás újrapróbálkozás előtt

Intelligens újrapróbálkozás

Ha a Service nem elérhető, exponenciális backoff stratégiát alkalmaz:

1. Első próbálkozás sikertelen → 1 másodperc várakozás
2. Második próbálkozás sikertelen → 3 másodperc várakozás
3. Harmadik próbálkozás sikertelen → Disk fallback aktiválódik

Disk Fallback

Ha az összes újrapróbálkozás sikertelen, a tevékenységek automatikusan lemezre íródnak JSON formában, atomi fájlírással (temp fájl → átnevezés minta).

Paraméter	Alapérték	Leírás
EnableFallbackPersistence	true	Disk fallback engedélyezése
FallbackPath	./konalytics-fallback/	Mentés helye
MaxFallbackDiskMb	100	Maximum lemezhasználat (MB)
FallbackRecoveryIntervalSeconds	300	Recovery időintervallum (5 perc)
MaxFallbackFilesPerRecoveryCycle	50	Fájlok száma recovery ciklusonként

Automatikus Recovery

A FallbackRecoveryService háttérfeladat 5 percenként ellenőrzi a fallback mappát, és megpróbálja újraküldeni a mentett tevékenységeket a Service-nek. Sikeres küldés után a fájl törlésre kerül.

Státusz endpoint

A kliens alkalmazásban automatikusan elérhető egy GET /konalytics/status endpoint, amely a következő információkat adja vissza:

{
  "pendingFileCount": 3,
  "oldestFileTimestamp": "2025-01-15T10:30:00Z",
  "totalDiskUsageBytes": 245760,
  "fallbackEnabled": true,
  "fallbackPath": "./konalytics-fallback/"
}

        vissza tovább

Egyéni események és munkamenetek

KonalyticsTracker API

Az automatikus HTTP naplózás mellett az IKonalyticsTracker interfész lehetővé teszi tetszőleges üzleti események programozott rögzítését. A service dependency injection-ön keresztül érhető el:

public class OrderController(IKonalyticsTracker tracker)
{
    public async Task CompleteOrder(int orderId)
    {
        // Üzleti logika...

        // Egyéni esemény rögzítése
        await tracker.TrackEventAsync(
            "OrderCompleted",
            new Dictionary<string, object>
            {
                ["total"] = 15000,
                ["currency"] = "HUF",
                ["itemCount"] = 3
            },
            new List<EntityLinkRequest>
            {
                new() { EntityType = "Order", EntityId = orderId.ToString() }
            }
        );
    }
}

TrackEventAsync paraméterek

Paraméter	Típus	Leírás
eventType	string	Az esemény típusa (pl. „OrderCompleted", „ReportGenerated")
eventData	Dictionary<string, object>?	Tetszőleges adat JSON formában
entityLinks	List<EntityLinkRequest>?	Kapcsolódó entitások (több is megadható)
ct	CancellationToken	Megszakítási token

Munkamenet-kezelés (Session Tracking)

A Konalytics v2 automatikusan kezeli a felhasználói munkameneteket:

• Automatikus session felismerés: A SessionKeyClaimType claim-ből vagy az ASP.NET Session ID-ból
• Lazy session létrehozás: A munkamenet csak az első tevékenység rögzítésekor jön létre, nem előre
• Session upsert: Minden batch feldolgozásnál frissül a munkamenet utolsó aktivitása
• Anonim sessionök: Nem bejelentkezett felhasználók tevékenységei is követhetők

Session konfiguráció az appsettings.json-ben:

{
  "Konalytics": {
    "SessionKeyClaimType": "sid",
    "UserIdClaimType": "sub"
  }
}

        vissza tovább

Admin felület

A Konalytics v2 teljes értékű admin dashboardot biztosít, amelyet Vue 3 + Vuetify 3 technológiával fejlesztettünk. A felület Docker konténerben fut, és a Service REST API-ján keresztül kommunikál.

Irányítópult (Dashboard)

Az irányítópult azonnali áttekintést nyújt a rendszer állapotáról:

• Összes tevékenység — Teljes tevékenységszám
• Mai tevékenységek — Az adott napi forgalom
• Egyedi felhasználók — Különböző felhasználók száma
• Tevékenységtípusok — Regisztrált URL pattern-ek száma
• Forrásalkalmazások — Csatlakozott alkalmazások száma
• Top 10 tevékenység — Leggyakoribb endpointok színkódolt HTTP metódussal

Tevékenységtípusok kezelése

Az összes felismert URL pattern táblázatos formában, inline szerkesztéssel:

Alkalmazás	Metódus	URL Pattern	Megjelenés név	Darab
MyApp	GET	/api/users/{id}	Felhasználó lekérése	1 523
MyApp	POST	/api/tasks	Feladat létrehozása	847
MyApp	PUT	/api/tasks/{id}	Feladat módosítása	632
MyApp	DELETE	/api/tasks/{id}	Feladat törlése	95

Keresés

Teljes értékű kereső felület több szűrő kombinációjával:

• Felhasználó ID alapján
• Forrásalkalmazás szerint
• Entitás típus és ID alapján
• Dátumtartomány (tól-ig)
• Részletes nézet: teljes payload, entity linkek, IP cím, válaszidő

Forrásalkalmazások

A regisztrált kliens alkalmazások kezelése:

• Alkalmazás név és kód
• API kulcs generálás
• Aktív/inaktív állapot
• Fallback státusz monitorozás

        vissza tovább

Entity Linking

Az Entity Linking funkció lehetővé teszi, hogy a rögzített tevékenységeket utólagosan összekössük üzleti entitásokkal. Ez különösen hasznos, ha a tevékenység rögzítésekor még nem áll rendelkezésre az összes szükséges információ (pl. egy entitás megjelenés neve).

Pull-based modell

A Konalytics pull-based megközelítést alkalmaz: a kliens alkalmazás maga kérdezi le a függőben lévő tevékenységeket, és maga végzi az összerendelést. Ez a kliens alkalmazásnak teljes kontrollt biztosít a feldolgozás ütemezéséről.

Működési folyamat

1. A kliens lekérdezi a függőben lévő tevékenységeket:
   GET /api/tracking/pending?limit=100
2. A kliens a saját adatbázisából feloldja az entitás neveket (pl. felhasználónév, projekt név)
3. A kliens visszaküldi az összerendelt adatokat:
   POST /api/tracking/{id}/link

Példa: Entitás összerendelés

// POST /api/tracking/42/link
{
  "entityLinks": [
    {
      "entityType": "User",
      "entityId": "123",
      "displayName": "Kiss János",
      "identifier": "kiss.janos"
    },
    {
      "entityType": "Project",
      "entityId": "5",
      "displayName": "Webáruház fejlesztés",
      "identifier": "SHOP-DEV"
    }
  ]
}

Fontos jellemzők

• Többszörös entitás: Egy tevékenységhez több entitás is rendelhető (pl. felhasználó + projekt + feladat)
• Immutábilis rekordok: Az EntityLink rekordok létrehozás után nem módosíthatók — ez biztosítja a teljes audit trail-t
• DisplayName + Identifier: Minden entitáshoz tárolható mind az emberi olvasható név, mind a rendszerazonosító
• Automatikus jelölés: A feldolgozott tevékenységek NeedsLinkingFl flagje automatikusan false-ra áll

        vissza tovább

Integráció

A Konalytics v2 integrációja rendkívül egyszerű: két NuGet csomag telepítése, néhány sor konfiguráció, és a rendszer készen áll a használatra.

1. NuGet csomagok telepítése

dotnet add package Konalytics.Client
dotnet add package Konalytics.Shared

2. Service regisztráció (Program.cs)

var builder = WebApplication.CreateBuilder(args);

// Konalytics szolgáltatások regisztrálása
builder.Services.AddKonalytics(builder.Configuration);

var app = builder.Build();

// Konalytics middleware aktiválása
app.UseKonalytics();

app.Run();

3. Konfiguráció (appsettings.json)

{
  "Konalytics": {
    "ServiceUrl": "http://konalytics-service:8080",
    "ApiKey": "your-api-key-here",
    "ApplicationCode": "MyApp.BFF",

    "UserIdClaimType": "sub",
    "SessionKeyClaimType": "sid",

    "BatchSize": 100,
    "FlushIntervalSeconds": 5,
    "MaxPayloadSizeKb": 16,

    "RetryCount": 2,
    "RetryDelayMs": 1000,

    "EnableFallbackPersistence": true,
    "FallbackPath": "./konalytics-fallback/",
    "MaxFallbackDiskMb": 100,

    "EnableStatusEndpoint": true,
    "StatusEndpointPath": "/konalytics/status",

    "ExcludedPaths": ["/health", "/metrics", "/swagger"],

    "UseConventionBasedExtraction": true,
    "ApiPathPrefix": "/api/"
  }
}

4. Service telepítés (Docker Compose)

A Konalytics Service három Docker konténerből áll:

services:
  konalytics-postgres:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: konalytics
      POSTGRES_PASSWORD: secure_password
      POSTGRES_DB: konalytics
    ports:
      - "5432:5432"

  konalytics-service:
    image: konalytics-service:latest
    environment:
      ConnectionStrings__Konalytics: "Host=konalytics-postgres;..."
    ports:
      - "8080:8080"
    depends_on:
      konalytics-postgres:
        condition: service_healthy

  konalytics-ui:
    image: konalytics-ui:latest
    ports:
      - "3000:80"
    depends_on:
      konalytics-service:
        condition: service_healthy

5. Endpoint Sync CLI

A Swagger/OpenAPI definícióból automatikusan szinkronizálhatók a tevékenységtípusok megjelenés nevei:

dotnet run --project src/Konalytics.Tools.EndpointSync -- \
  sync \
  --swagger-url http://myapp:8080/swagger/v1/swagger.json \
  --konalytics-url http://konalytics:8080 \
  --source MyApp.BFF

API authentikáció

API	Authentikáció	Rate Limit
Tracking API	X-Konalytics-ApiKey header	300 kérés/perc
Admin API	Keycloak OIDC (JWT Bearer)	300 kérés/perc

API végpontok összefoglaló

Metódus	Útvonal	Leírás
POST	/api/tracking/batch	Kötegelt tevékenység rögzítés
GET	/api/tracking/pending	Függőben lévő tevékenységek
POST	/api/tracking/{id}/link	Entitás összerendelés
POST	/api/tracking/events	Egyéni esemény rögzítés
GET	/api/activities	Tevékenység keresés
GET	/api/activities/{id}	Tevékenység részletek
GET	/api/activity-types	Tevékenységtípusok listázása
PUT	/api/activity-types/{id}	Típus név módosítása
GET	/api/dashboard/stats	Irányítópult statisztika
GET	/api/source-applications	Forrásalkalmazások
POST	/api/admin/activity-types/sync	Endpoint szinkronizálás

        vissza