Skip to main content

🛰️ Alpura Back Java Lib Auditoría 2.0

Librería común para microservicios Java + Spring Boot que registra auditoría funcional y errores técnicos/negocio en una segunda base de datos dedicada a telemetría, completamente aislada del resto de la aplicación.

✅ Se integra vía Spring Boot AutoConfiguration, sin necesidad de agregar configuraciones extra (salvo propiedades mínimas como app.id).

🎯 ¿Qué incluye?​

  • 🧾 Persistencia de auditoría y errores (Audit_Log, Error_Log)
  • 🧵 Ejecución asíncrona para no impactar el rendimiento del microservicio
  • 🏷️ Anotación @IAuditable para registrar entrada, salida y tiempos
  • 🛡️ Segunda conexión a base de datos aislada del resto de la app
  • 🧪 Compatibilidad con PostgreSQL

📦 Requisitos​

  • ☕ Java: 21 (Temurin LTS)
  • 🍃 Spring Boot: 3.4.4 o superior
  • 🗄️ Base de datos: PostgreSQL
  • 📦 Build: Maven o Gradle

⚙️ Instalación​

Maven​

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

Gradle​

implementation 'com.alpura:alpura-back-java-lib-telemetry:2.0'

🛠️ 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 del microservicio consumidor:

app:
  id: msa_nombre_microservicio  # Requerido

🔌 Conexión a Base de Datos (Telemetría)​

La librería gestiona su propia conexión a base de datos (telemetría), sin interferir con la base principal del microservicio.

En general, no necesitas configurar nada adicional aquí (según el arquetipo/estándar del proyecto).

🧭 Escaneo de Componentes / JPA (✅ OBLIGATORIO en esta arquitectura)​

Esto es “sí o sí”.
Aunque las clases estén en el mismo proyecto, si tu aplicación usa escaneo “cerrado” (por paquetes), Spring no detectará automáticamente entidades/repositorios fuera de los paquetes definidos.

Por eso, debes declarar explícitamente:

  • 🗃️ Repositorios JPA que ocupará el servicio (@EnableJpaRepositories)
  • 🧩 Entidades JPA que ocupará el servicio (@EntityScan)

📌 Importante: aquí se incluyen solo los paquetes que el servicio realmente necesita escanear.

@EnableJpaRepositories(
    basePackages = {
        "com.alpura.java.arch.persistence" // 🗃️ Repositorios JPA que ocupará el servicio
    }
)
@EntityScan(
    basePackages = {
        "com.alpura.model.entity",         // 🧩 Entidades de dominio que ocupará el servicio
        "com.alpura.java.arch.model"       // 🧩 Entidades/modelos de la arquitectura que ocupará el servicio
    }
)
public class ExApplication { }

Si además usas @ComponentScan de forma restrictiva, asegúrate de incluir los paquetes necesarios para el servicio:

@SpringBootApplication
@PropertySource("classpath:message.properties")
@ComponentScan({
  "com.alpura.java.arch",
  "com.alpura.utilities.web",
  "com.alpura.utilities.util",
  "com.alpura.utilities.annotation.aspectj",
  "com.alpura.utilities.mapper",
  "com.alpura.security.*",
  "com.alpura.cache"
})
@EnableJpaRepositories(basePackages = "com.alpura.java.arch.persistence") // repositorios que ocupará el servicio
@EntityScan(basePackages = {"com.alpura.model.entity", "com.alpura.java.arch.model"}) // entidades que ocupará el servicio
public class ExApplication {

  public static void main(String[] args) {
    SpringApplication.run(ExApplication.class, args);
  }
}

🧩 Uso de @IAuditable​

La auditoría se activa automáticamente al usar la anotación @IAuditable.

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

  • ✅ Recibir un RequestVO<?>
  • ✅ Retornar un SingleResponseVO<?> o ResponseVO<?>

Puedes consultar RequestVO<?>, SingleResponseVO<?> y ResponseVO<?> en la librería alpura-back-java-lib-common-utilities.

Ejemplo:

@IAuditable
public SingleResponseVO<String> myMethod(RequestVO<String> request) {
  // lógica del método
}

✅ ¿Qué pasa cuando se ejecuta?​

  • 🟢 Si la ejecución es exitosa, se guarda en Audit_Log
  • 🔴 Si ocurre un error, se registra en Error_Log

🧾 Estructura de Datos​

📄 Entidad: AuditLog (ejemplo 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": "long",
  "status": "ok"
}

🧯 Entidad: ErrorLog (ejemplo 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:

  • 📥 Parámetros de entrada (request)
  • 📤 Salida del método (response)
  • ⏱️ Tiempos de ejecución
  • 📅 Fecha/hora del evento
  • 🧷 Identificadores del cliente (si aplican)

🧱 Manejo de errores integrado
🧵 Ejecución asíncrona (multihilo)
⚙️ Configuración simple por YAML
💾 Persistencia en PostgreSQL

📌 Notas finales​

  • ⭐ app.id es obligatoria y debe configurarse en el application.yml del microservicio consumidor.