TT Log and Error management

[codastream]

User Story

AS A DevOps/Backend Developer

I WANT a unified logging and error handling strategy across all microservices

SO THAT I can

• effectively trace issues using ELK
• ensure consistent API error responses for the frontend
• maintain system reliability.

Parts of project targeted

• shared/core
• gateway
• other services (on a per-codeowner basis)

Details

should be done for gateway as a part of #36

Logger config

• consistent casing : camelCase
• add req.headers.cookie
• remove hostname (random in Docker)
• add user id in serialized request
• add event and reason in serialized error

Logger catalog

check if we can have helper methods by event, that can provide consistent context through event catalog as in ERR_DEFS

should be used in auth controller as

logEvent(req.log, LOG_EVENTS.AUTH.LOGIN.SUCCESS, { userId: user.id, method: '2FA' })

// or if AsyncLocalStorage - good idea ?

logEvent(LOG_EVENTS.AUTH.LOGIN.SUCCESS, { userId: user.id, method: '2FA' })

for gateway, check if we should / can refactor helpers (logAuth, logRequest, ..) leveraging on req.log.child, while maintaining a constant catalog

logEvent(proxyLog, EVENT_CATALOG.GATEWAY.PROXY_REQ);

default Fastify log fields

{
  // --- Standard Pino/Fastify Fields (Metadata) ---
  "level": 30,                       //  "info" converted to number
  "time": "2025-12-04T10:00:00.000Z", // 2. ISO timestamp
  "pid": 1234,                       // Process ID
  "reqId": "req-1",                  // From request.log binding (or traceId)

  // --- Shared Core Config (Base) ---
  "service": "auth-service",
  "env": "production", 

  // --- `logEvent` Payload ---
  "event": "auth.login.success",     // 8. From EVENT_CATALOG
  "msg": "User logged in successfully", // 9. From EVENT_CATALOG message
  "userId": 1,  
  "method": "2FA", 
  
  // --- Potential Extras ---
  "traceId": "..."
}

Details typing

• flatline details (avoid nesting)
  export interfaces for
• Validation : field, issue, received
• Dependency : latency, status, endpoint
• Auth : attempts

Important

redact PII in details fields (received)

Explore if logging can be efficiently automated with decorators

Requires class

Acceptance criteria

cf Wiki

• no console.log in services
• logs are sanitized everywhere
• proper usage of log level (trace, ...)
• have static events messages to easily filter in Kibana

Subtasks

• export interface to standardize details fields (ie for Fastify schema validation errors)
• refactor export as log instead of logger : more convenient
• improved and generic logger config in shared/core
• try to have a LOG_DEFS catalog and helper methods - AsyncLocalStorage for req.log
• update ERR_DEFS catalog so that it contains errors for gateway and auth