feat(observability): implement correlated logs and AOP-based auditing (#12)

* chore(deps): add logstash-logback-encoder dependency

* feat(logging): implement structured, correlated JSON logging

* feat(observability): add Loki and Alloy for centralized log collection

* feat(otel): route distributed traces via grafana alloy

* feat(observability): implement trace-to-log correlation

* feat(security): implement AOP-based audit logging module

* feat(security): apply AOP-based auditing to services

* docs(readme): update main README for phase 5 completion

Author: apenlor

.dockerignore

@@ -0,0 +1,16 @@
+# Ignore Maven build output directories
+**/target
+
+# Ignore IDE-specific files
+.idea/
+*.iml
+
+# Ignore build log files
+build.log
+
+# Ignore git repository files
+.git/
+.gitignore
+
+# Ignore local environment files (the real one should never be in the image)
+.env

README.md

@@ -0,0 +1,63 @@
+// ===================================================================
+// Grafana Alloy Configuration
+// ===================================================================
+
+// --- LOGS PIPELINE ---
+
+// Responsible for sending logs to the Loki backend.
+loki.write "default" {
+  endpoint {
+    url = "http://loki:3100/loki/api/v1/push"
+  }
+}
+
+// Connects to the Docker API and discovers ALL running containers.
+discovery.docker "all_containers" {
+  host = "unix:///var/run/docker.sock"
+}
+
+// Processes the list of discovered containers to filter them and
+// add a clean 'container_name' label.
+discovery.relabel "filtered_containers" {
+  targets = discovery.docker.all_containers.targets
+  rule {
+    source_labels = ["__meta_docker_network_name"]
+    action        = "keep"
+    regex         = "spring-boot-security-observability-lab_lab-net"
+  }
+  rule {
+    source_labels = ["__meta_docker_container_name"]
+    regex         = "/(.*)"
+    target_label  = "container_name"
+  }
+}
+
+// Scrapes raw log lines from the filtered list of containers and
+// forwards them directly to the exporter.
+loki.source.docker "default" {
+  host       = "unix:///var/run/docker.sock"
+  targets    = discovery.relabel.filtered_containers.output
+  forward_to = [loki.write.default.receiver]
+}
+
+// --- TRACES PIPELINE ---
+
+// Listens for incoming OpenTelemetry traces on the standard gRPC port.
+otelcol.receiver.otlp "default" {
+  grpc {
+    endpoint = "0.0.0.0:4317"
+  }
+  output {
+    traces = [otelcol.exporter.otlp.tempo.input]
+  }
+}
+
+// Forwards the received traces to the Tempo backend.
+otelcol.exporter.otlp "tempo" {
+  client {
+    endpoint = "tempo:4317"
+    tls {
+      insecure = true // We are on a trusted Docker network.
+    }
+  }
+}

config/alloy/alloy-config.river

@@ -0,0 +1,36 @@
+apiVersion: 1
+
+datasources:
+  - name: Prometheus
+    uid: prometheus-lab-uid
+    type: prometheus
+    url: http://prometheus:9090
+    # The access mode ("proxy" means the Grafana backend makes the requests)
+    access: proxy
+    isDefault: true
+    editable: true
+
+  - name: Tempo
+    uid: tempo-lab-uid
+    type: tempo
+    url: http://tempo:3200
+    access: proxy
+    editable: true
+    # This section links this Tempo data source to our other observability pillars
+    jsonData:
+      # Enables the graph
+      serviceMap:
+        datasourceUid: 'prometheus-lab-uid'
+      # Enables one-click navigation from a trace span directly to the logs for that trace
+      tracesToLogs:
+        datasourceUid: 'loki-lab-uid'
+        mappedTags:
+          - { key: 'service.name', value: 'container_name' }
+        filterByTraceID: true
+
+  - name: Loki
+    uid: loki-lab-uid
+    type: loki
+    url: http://loki:3100
+    access: proxy
+    editable: true

config/grafana/provisioning/datasources/datasources.yml

@@ -0,0 +1,40 @@
+# ===================================================================
+# Loki Configuration for Local Development (Loki v3.x Syntax)
+# ===================================================================
+server:
+  http_listen_port: 3100 # The port Loki listens on for log ingestion and API queries
+  grpc_listen_port: 0    # Disables the gRPC port, as we are only using HTTP
+
+common:
+  # The path prefix for Loki's internal data directories
+  path_prefix: /loki
+  # Defines the storage backend for both index and log chunks
+  storage:
+    filesystem:
+      chunks_directory: /loki/chunks
+      rules_directory: /loki/rules
+  # For a single-node setup, the replication factor is always 1
+  replication_factor: 1
+  # For our single instance, we use a simple in-memory store
+  ring:
+    instance_addr: 127.0.0.1
+    kvstore:
+      store: inmemory
+
+# Configures how Loki indexes logs, allowing for fast retrieval
+schema_config:
+  configs:
+    - from: 2020-10-24 # A past date ensures this schema is always active
+      # tsdb is the recommended index store for single-node deployments
+      # It writes index files to the local filesystem
+      store: tsdb
+      object_store: filesystem
+      schema: v13
+      index:
+        prefix: index_
+        period: 24h
+
+# While we are not defining alerts in this phase, the block must be present
+ruler:
+  # In a full setup, this would point to our Alertmanager service
+  alertmanager_url: http://localhost:9093

config/grafana/provisioning/datasources/prometheus-datasource.yml

@@ -17,7 +17,7 @@ services:
       # OpenTelemetry Agent Configuration
       - JAVA_TOOL_OPTIONS=-javaagent:/app/opentelemetry-javaagent.jar
       - OTEL_SERVICE_NAME=resource-server
-      - OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317
+      - OTEL_EXPORTER_OTLP_ENDPOINT=http://alloy:4317
       - OTEL_EXPORTER_OTLP_PROTOCOL=grpc
       - OTEL_METRICS_EXPORTER=none
       - OTEL_LOGS_EXPORTER=none
@@ -32,6 +32,8 @@ services:
     depends_on:
       keycloak:
         condition: service_healthy
+      alloy:
+        condition: service_started
     networks:
       - lab-net
 
@@ -51,7 +53,7 @@ services:
       # OpenTelemetry Agent Configuration
       - JAVA_TOOL_OPTIONS=-javaagent:/app/opentelemetry-javaagent.jar
       - OTEL_SERVICE_NAME=web-client
-      - OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317
+      - OTEL_EXPORTER_OTLP_ENDPOINT=http://alloy:4317
       - OTEL_EXPORTER_OTLP_PROTOCOL=grpc
       - OTEL_METRICS_EXPORTER=none
       - OTEL_LOGS_EXPORTER=none
@@ -63,6 +65,8 @@ services:
         condition: service_healthy
       resource-server:
         condition: service_healthy
+      alloy:
+        condition: service_started
     networks:
       - lab-net
 
@@ -174,6 +178,43 @@ services:
     networks:
       - lab-net
 
+  # --------------------------------------------------------------------------
+  # Grafana Loki Service: For centralized log aggregation.
+  # --------------------------------------------------------------------------
+  loki:
+    image: grafana/loki:3.5.3
+    container_name: loki
+    # The auth flag is the way to run Loki in single-tenant mode
+    command: "-config.file=/etc/loki/loki-config.yml -auth.enabled=false"
+    volumes:
+      - ./config/loki/loki-config.yml:/etc/loki/loki-config.yml:ro
+      - loki-data:/loki/data
+    networks:
+      - lab-net
+
+  # --------------------------------------------------------------------------
+  # Grafana Alloy Service: The unified observability agent.
+  # --------------------------------------------------------------------------
+  alloy:
+    image: grafana/alloy:v1.10.2
+    container_name: alloy
+    volumes:
+      # =============================== SECURITY DISCLAIMER ===============================
+      # The read-only mount of the Docker socket is a privileged operation.
+      # For this lab, we accept this risk to enable a portable & simplified experience with automatic
+      # service discovery. For production environments, a non-socket-based approach like
+      # using a native Docker logging driver, or sidecar would be a more secure alternative.
+      # ===================================================================================
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./config/alloy/alloy-config.river:/etc/alloy/config.river:ro
+    command: "run /etc/alloy/config.river"
+    depends_on:
+      - loki
+      - tempo
+    networks:
+      - lab-net
+
+
   # --------------------------------------------------------------------------
   # Grafana Service: For metrics visualization.
   # --------------------------------------------------------------------------
@@ -184,14 +225,16 @@ services:
       - "3000:3000"
     volumes:
       - grafana-data:/var/lib/grafana
-      - ./config/grafana/provisioning/datasources:/etc/grafana/provisioning/datasources
+      - ./config/grafana/provisioning/datasources/datasources.yml:/etc/grafana/provisioning/datasources/datasources.yml
       - ./config/grafana/provisioning/dashboards:/etc/grafana/provisioning/dashboards
       - ./config/grafana/dashboards:/var/lib/grafana/dashboards
     depends_on:
       prometheus:
         condition: service_started
       tempo:
         condition: service_started
+      loki:
+        condition: service_started
     networks:
       - lab-net
 
@@ -204,7 +247,8 @@ secrets:
 volumes:
   grafana-data:
   keycloak-db-data:
-  tempo-data: # New volume for Tempo's trace data
+  tempo-data:
+  loki-data:
 
 networks:
   lab-net:

config/grafana/provisioning/datasources/tempo-datasource.yml

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>com.apenlor.lab</groupId>
+        <artifactId>security-observability-lab</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>lab-aspects</artifactId>
+    <name>lab-aspects</name>
+    <description>Shared library for common utilities, aspects, and DTOs.</description>
+
+    <dependencies>
+        <!-- Spring Libraries -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-aop</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-security</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <!-- Metrics & Observability -->
+        <dependency>
+            <groupId>io.micrometer</groupId>
+            <artifactId>micrometer-core</artifactId>
+        </dependency>
+
+        <!-- Utils -->
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+        </dependency>
+
+        <!-- Test Dependencies -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.security</groupId>
+            <artifactId>spring-security-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>net.logstash.logback</groupId>
+            <artifactId>logstash-logback-encoder</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>