Skip to main content

🛰️ Alpura Back Java Lib Auditoría y Telemetría v3.1

Librería común para microservicios Java + Spring Boot (com.alpura:back-java-lib-common-telemetry:3.1) que registra auditoría funcional, eventos Pub/Sub y errores técnicos/negocio en una base de datos dedicada a telemetría, completamente aislada de la base principal del microservicio.

✅ Se integra mediante Spring Boot AutoConfiguration (AuditDataSourceAutoConfiguration, AuditJpaRepositoriesAutoConfiguration, AuditAspectAutoConfiguration), registrando de forma automática las entidades y repositorios de telemetría sin requerir configuración extra manual.

🎯 ¿Qué incluye?​

  • 🧾 Persistencia de auditoría (Audit_Log), errores (Error_Log) y eventos personalizados (NonStandardAuditLog).
  • 🧵 Ejecución asíncrona multihilo para no impactar la latencia ni el rendimiento del microservicio.
  • 🏷️ Anotación @IAuditable para registrar entrada, salida y tiempos en métodos REST/Service.
  • 📡 Anotación @IPubSubAuditable para registrar la ejecución de eventos recibidos por suscripciones Pub/Sub.
  • 🛡️ Segunda conexión a base de datos aislada gestionada automáticamente.
  • 🧪 Compatibilidad con PostgreSQL.

📦 Requisitos​

  • ☕ Java: 21 (Temurin LTS)
  • 🍃 Spring Boot: 3.4.4 o superior
  • 🗄️ Base de datos: PostgreSQL
  • 📦 BOM Alpura: 1.0.4

⚙️ Instalación​

Opción A: Heredando versión desde Alpura BOM 1.0.4 (RECOMENDADO)​

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.alpura</groupId>
      <artifactId>bom</artifactId>
      <version>1.0.4</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.alpura</groupId>
    <artifactId>back-java-lib-common-telemetry</artifactId>
  </dependency>
</dependencies>

Opción B: Uso directo (Standalone)​

<dependency>
  <groupId>com.alpura</groupId>
  <artifactId>back-java-lib-common-telemetry</artifactId>
  <version>3.1</version>
</dependency>

Gradle: implementation 'com.alpura:back-java-lib-common-telemetry:3.1'

🛠️ Configuración​

🆔 Identificador de la aplicación (OBLIGATORIO)​

La propiedad app.id identifica de forma única al microservicio dentro de los logs de auditoría (por ejemplo: msa-catalogo, msa-user-service, etc.).

📌 Agrega esto en el application.yml de tu microservicio:

app:
  id: msa_nombre_microservicio  # Requerido

🔌 Conexión y AutoConfiguración de Base de Datos​

La librería registra automáticamente su propio DataSource y EntityManagerFactory para telemetría mediante Spring Boot AutoConfiguration (AuditDataSourceAutoConfiguration). No requiere que el desarrollador declare entidades o repositorios de auditoría manualmente.

En caso de que tu microservicio utilice un escaneo de paquetes cerrado, asegúrate de incluir el paquete de telemetría en @ComponentScan:

@SpringBootApplication
@ComponentScan({
  "com.alpura.telemetry",  // 🛰️ Paquete raíz de telemetría
  "com.alpura.utilities",
  // tus paquetes…
})
public class ExApplication {
  public static void main(String[] args) {
    SpringApplication.run(ExApplication.class, args);
  }
}

🧩 Uso de @IAuditable (Métodos REST / Servicios)​

La auditoría funcional estándar se activa colocando la anotación @IAuditable sobre los métodos deseados.

📌 Según la arquitectura de Alpura, todo método anotado debe:

  • ✅ Recibir un RequestVO<?>
  • ✅ Retornar un SingleResponseVO<?> o ResponseVO<?>
@IAuditable
public SingleResponseVO<String> myMethod(RequestVO<String> request) {
  // Lógica del servicio
}

✅ ¿Qué sucede en la ejecución?​

  • 🟢 Si la ejecución es exitosa, se guarda automáticamente en la tabla Audit_Log.
  • 🔴 Si ocurre un error, se registra en la tabla Error_Log incluyendo el stacktrace.

📡 Uso de @IPubSubAuditable (Eventos Pub/Sub)​

Para auditar el consumo y procesamiento asíncrono de eventos provenientes de Google Cloud Pub/Sub, anota el método escuchador con @IPubSubAuditable:

@EventListener
@IPubSubAuditable
public void handlePubSubMessageEvent(PubSubMessageEvent event) {
  // Lógica de procesamiento de eventos Pub/Sub
}

El aspecto SmartLoggerAspectPS interceptará el evento registrando los metadatos de la suscripción, identificador de mensaje y tiempo de ejecución.

🧾 Estructura de Datos​

📄 Entidad: AuditLog (JSON)​

{
  "userId": "string",
  "token": "string",
  "logLevel": "AUDIT",
  "className": "string",
  "methodName": "string",
  "message": "SUCCESS",
  "eventDate": "datetime",
  "requestDate": "datetime",
  "requestVO": {},
  "logDate": "datetime",
  "stacktrace": "SUCCESS",
  "responseVO": {},
  "idClientInvoke": "string",
  "clientOperationCode": "string",
  "elapsedTime": 120,
  "status": "ok"
}

🧯 Entidad: ErrorLog (JSON)​

{
  "userId": "string",
  "token": "string",
  "logLevel": "ERROR",
  "className": "string",
  "methodName": "string",
  "message": "BUSINESS_ERROR",
  "eventDate": "datetime",
  "requestDate": "datetime",
  "logDate": "datetime",
  "requestVO": {},
  "stackTrace": "string",
  "clientInvokeId": "string",
  "clientOperationCode": "string"
}

⚡ Características principales​

  • ✅ Registro automático de entradas, salidas, tiempos de ejecución y errores.
  • 📡 Soporte nativo para auditoría de eventos Pub/Sub mediante @IPubSubAuditable.
  • ⚙️ AutoConfiguración transparente vía Spring Boot.
  • 🧵 Ejecución asíncrona multihilo aislada.
  • 💾 Persistencia independiente en PostgreSQL.