Platform-logging (sources, env-vars, endpoints)

Feiten over de pino-gebaseerde platform-logging. Voor context en het verschil met reporting, zie Logging vs reporting.

Bron-of-truth: apps/api/src/common/services/loggerService/* en apps/api/src/common/utils/envConfig.ts.

Sources en singletons

Vier bronnen, elk een eigen pino-instance en singleton (apps/api/src/common/services/loggerService/loggerService.ts):

Singleton Source Gebruik
loggerService app Algemene applicatie-/systeemlogs
httpLoggerService http Inkomende requests/responses (via middleware)
bullMqLoggerService bull BullMQ-jobs
errorLoggerService error Errors en fatals

API (LoggerService)

  • withContext(context) — child-logger met samengevoegde context.
  • withBullContext(job) — verrijkt context met een veilige subset van job.data.
  • trace / debug / info / warn / error / fatal — alle niveaus.
  • buildLoggerContext(req) — bouwt context (tenantUuid, requestId, userId, gemaskeerde userEmail, endpoint, method) uit een Express-request.

In HTTP-handlers: gebruik req.logger (gezet door de requestLogger-middleware in apps/api/src/common/middleware/requestLogger/requestLogger.ts). In Bull-processors: gebruik de helper getBullLogger(job) (apps/api/src/common/services/loggerService/getBullLogger.ts).

Env-vars

Alle defaults uit envConfig.ts (productie-default; tussen haakjes afwijkingen):

Env-var Default Betekenis
LOG_LEVEL error Niveau-drempel voor pino stdout/files. Bewust hoog in prod.
LOG_STORE_LEVEL info Apart niveau voor wat in de logStore-buffer landt (zodat de admin-UI info+warn toont terwijl stdout stil blijft).
LOG_STORAGE inmemory inmemory of redis — backend van de unified logStore.
DEFAULT_LOG_PATH /var/log/tapster Map voor dagbestanden (test: /tmp/logs).
DISABLE_FILE_LOGGING false Op true om bestandslogging uit te zetten (stdout blijft).
LOG_BUFFER_TTL_DAYS 7 TTL voor entries in de buffer.
LOG_BUFFER_MAX 10000 Max aantal entries in de ringbuffer (test: 2000).
LOG_REDIS_PREFIX logs Key-prefix bij LOG_STORAGE=redis.
LOG_LIST_DEFAULT_WINDOW_HOURS 168 Default tijdvenster voor GET /logs.
LOG_LIST_MAX_SCAN 5000 Max te scannen entries per query.
LOG_REDACT_KEYS false Comma-separated extra sleutels om te redacten (false = alleen de standaardset).
POD_NAME, POD_NAMESPACE, POD_IP (k8s) Toegevoegd aan context.
APP_VERSION — Versie-string in context.

Redaction en privacy

  • Gevoelige sleutels worden automatisch geredigeerd (o.a. password, token, accessToken, refreshToken, authorization, secret, apiKey, pin); uitbreidbaar via LOG_REDACT_KEYS.
  • userEmail wordt in de buffer gemaskeerd.
  • HTTP-bodies: multipart en binaire content worden nooit gelogd; JSON-bodies boven de drempel of niet-serialiseerbaar worden overgeslagen (alleen meta).

Endpoints

Router: apps/api/src/api/logging/logsRouter.ts. Alle routes vereisen authenticatie en endpoint-autorisatie.

Methode + pad Doel
GET /logs Query de logStore-buffer. Params o.a. q, level, source, tenantUuid, fromTs, toTs, pageSize (max 500), sortBy, sortDir. Response: data.data[] met { ts, level, source, message, data }.
GET /logs/files Lijst beschikbare .log-bestanden (optioneel retentionDays om oude op te ruimen).
GET /logs/files/:name Download een specifiek logbestand (path-traversal beveiligd).

De buffer bevat standaard alleen info+warn (zie LOG_STORE_LEVEL); success/debug staan er niet in. Voor diepere historie zijn de dagbestanden of een externe log-sink nodig.

Frontend

Menu-item “Logging” in Tapster-beheer, route /beheer/tapster/logging.