NewSun — Logging Standards

Structured JSON

Trace context

Span → DB linkage

PII-safe

Why logging is critical

Customer trust: precise logs explain outages and speed recovery.
Compliance: audit trails show who did what and when—required for regulators.
Performance: slow transactions surface via span timing without attaching debuggers.
Security: anomalies (unexpected IP, auth failures) are detectable only with fine-grained logs.
On-call: clean logs reduce MTTR and prevent “cannot reproduce” at 2 a.m.

Logging is a feature, not an afterthought. Stories are incomplete until logging and tracing are covered in the ACs.

Log taxonomy & severity

Level	When to use
TRACE	Deep debugging, disabled in prod by default.
DEBUG	Detailed module flows; may be enabled temporarily.
INFO	Business milestones (module toggled, batch complete).
WARN	Recoverable issues (retry succeeded, fallback engaged).
ERROR	Customer-impacting failures; must include correlation ID.

End-to-end request tracking

Every inbound HTTP request receives a traceId (W3C Trace Context). The UI propagates it as traceparent header, the backend attaches spanId, and JDBC interceptors log the same identifiers when hitting the database. This lets us replay a request chronologically:

UI logs button clicks + APIs called with traceId.
API gateway / Backend logs controllers, services, and downstream calls with traceId/spanId.
Persistence layer logs SQL latency + table names + traceId.
Observability (OTel) exports the same trace to Grafana Tempo; Kibana dashboards correlate logs via field search.

The rule: no log = it didn’t happen. Requests without traceId are automatically rejected in CI tests.

Implementation blueprint

<!-- logback-spring.xml -->
<appender name="JSON" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
  <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder"/>
</appender>
<logger name="com.newsun" level="INFO" additivity="false">
  <appender-ref ref="JSON"/>
</logger>
<root level="WARN">
  <appender-ref ref="JSON"/>
</root>

// Example usage
@Slf4j
@RestController
class AuditController {
  @GetMapping("/api/v1/audit/{id}")
  AuditDto fetch(@PathVariable UUID id) {
    log.info("audit.fetch", kv("auditId", id));
    ...
  }
}

Helper kv() produces structured key/value pairs so logs stay machine searchable.

Operational guardrails

PII is masked at source; log entries are scrubbed via Logback value filters.
Retention: 30 days hot (OpenSearch), 365 days cold (object storage) for audit events.
On-call runbooks document Kibana/Grafana queries by module and correlation ID.
CI automatically fails if new endpoints lack traceId propagation tests.
Weekly “log review” ensures critical paths emit INFO/WARN/ERROR with actionable fields.