Skip to content

Getting started with Activity Log

This guide explains the minimal steps to integrate Activity Log in a new application.

Prepare the Application

A new application created on start.vaadin.com can be used as a starting point for this tutorial. Open the site, select an empty project, choose Spring Boot as the framework, and download the generated archive. Extract it, import it into your IDE of choice, and verify the application starts correctly by running the main class.

Add the AppJars Repository

AppJars artifacts are published to the public AppJars Maven repository. Add it to your pom.xml so that Maven can resolve the AppJars dependencies:

<repositories>
    <repository>
        <id>appjars</id>
        <name>AppJars Public Repository</name>
        <url>https://maven.appjars.com</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Add the Dependencies

Given that it is a monolithic application, the following dependencies representing the three layers of the appjar must be added:

<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-activity-log-flow</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-activity-log-data-impl</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-activity-log-business-impl</artifactId>
</dependency>

Activity Log captures log events through a Log4j2 appender. Spring Boot uses Logback by default, so the logging starter must be replaced with the Log4j2 one. Exclude the default logging starter and add the Log4j2 alternative:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

Every starter needs its own exclusion

spring-boot-starter-logging is a transitive dependency of every Spring Boot starter. If the application declares more starters (spring-boot-starter-web, spring-boot-starter-actuator, ...), the exclusion must be repeated on each of them — a single missed starter silently breaks log capture. Since 2.0.0 a broken logging classpath fails the application startup with a message naming the fix. See Logging Requirements for the full explanation, a build-time enforcement recipe, and troubleshooting.

After adding them, build the application to confirm that the dependencies are resolved correctly.

Configure Log4j2

Activity Log captures log events by registering a custom Log4j2 appender. Create a log4j2.xml file in src/main/resources with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration packages="com.appjars.activitylog.business.service" status="WARN">
  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
    </Console>
    <ActivityLogAppender name="ActivityLogAppender"/>
  </Appenders>
  <Loggers>
    <Root level="trace" additivity="false">
      <AppenderRef ref="Console" level="info"/>
      <AppenderRef ref="ActivityLogAppender" level="trace"/>
    </Root>
  </Loggers>
</Configuration>

The packages attribute in <Configuration> is required so that Log4j2 can discover the ActivityLogAppender plugin provided by the appjar. The appender intercepts log events and forwards them to Activity Log for storage. Extractors configured in the UI then control which of those events are actually persisted.

Note

The appender captures events emitted during application startup, before the Spring context is ready, by holding them in a bounded buffer and draining them once Activity Log becomes active. The buffer can be tuned with the optional bufferCapacity and bufferLevel attributes on the <ActivityLogAppender> element. If the appender is not declared in the logging configuration, a fallback appender is registered automatically on the root logger when Activity Log activates — capture still works, but startup events are not buffered. See Logging Requirements and the Developer Guide for details.

Configure the Router Layout

Inject the RouteConfigurer provided by Activity Log and configure the router layout in a @PostConstruct method so that the appjar views share the same layout as the rest of the application:

@Autowired
@Qualifier("ActivityLogRouteConfigurer")
RouteConfigurer routeConfigurer;

@PostConstruct
public void configure() {
    routeConfigurer.setViewsRouterLayout(MainLayout.class);
}

The import for RouteConfigurer is com.appjars.activitylog.flow.util.RouteConfigurer.

Add the Views to the Navigation

Activity Log provides four main views. Add them to the application's navigation menu by inserting the following snippet at the end of the method createNavigation() in MainLayout, before returning nav:

if (accessChecker.hasAccess(ActivityLogView.class)) {
    nav.addItem(new SideNavItem("Activity Log", ActivityLogView.class, LineAwesomeIcon.LIST_ALT_SOLID.create()));
}
if (accessChecker.hasAccess(ExtractorsListView.class)) {
    nav.addItem(new SideNavItem("Extractors", ExtractorsListView.class, LineAwesomeIcon.FILTER_SOLID.create()));
}
if (accessChecker.hasAccess(RemoversListView.class)) {
    nav.addItem(new SideNavItem("Removers", RemoversListView.class, LineAwesomeIcon.TRASH_ALT_SOLID.create()));
}
if (accessChecker.hasAccess(LogViewerListView.class)) {
    nav.addItem(new SideNavItem("Log Viewers", LogViewerListView.class, LineAwesomeIcon.EYE_SOLID.create()));
}

The imports for the view classes are:

  • com.appjars.activitylog.flow.view.ActivityLogView
  • com.appjars.activitylog.flow.view.ExtractorsListView
  • com.appjars.activitylog.flow.view.RemoversListView
  • com.appjars.activitylog.flow.view.LogViewerListView

All four views are accessible to any authenticated user. Restricting access to specific roles (for example, limiting the Activity Log view to administrators) is left to the host application through its own security configuration.

Configure Application Properties

Add the following properties to application.properties:

spring.jpa.hibernate.ddl-auto=update
spring.jpa.generate-ddl=true
spring.aop.proxy-target-class=false
vaadin.i18n.provider=com.appjars.utils.i18n.AppjarsI18nProvider

The spring.aop.proxy-target-class=false property is required for the appjar to function correctly.

Finally, add com.flowingcode and com.appjars to the list of whitelisted packages in application.properties:

vaadin.allowed-packages = com.vaadin,org.vaadin,dev.hilla,com.example.application,com.flowingcode,com.appjars

Testing the Application

Start the application by running the main Spring Boot class. Log in with an administrator account and navigate to Extractors in the menu. Create an extractor to define which loggers and levels should be captured and stored.

Once an extractor is active, any log statement in the application that matches its criteria will be persisted automatically. Navigate to Activity Log to browse the stored entries.