Skip to content

Download

LogAperture is two pieces: the agent, a jar the JVM loads with -javaagent, and logctl, the command-line tool. Both are in the release zip, and both are on Maven Central.

Open source under the Apache License 2.0.

The release zip

Download logaperture-1.0.0.zip from GitHub. It is everything you need on one machine, and what the install pages start from:

Path
bin/logctl, bin/logctl.cmd logctl, for Linux and macOS, and for Windows; an optional conf file next to them sets the Java it uses
lib/logaperture-agent.jar the agent
lib/logaperture-cli.jar the jar logctl runs
docs/index.html this guide, for reading without a network
LICENSE the Apache License 2.0

Check the download

Next to the zip on the release page are logaperture-1.0.0.zip.sha256, its SHA-256 checksum, and logaperture-1.0.0.zip.asc, its GPG signature. Download them into the same directory as the zip.

To check that the zip arrived intact:

sha256sum -c logaperture-1.0.0.zip.sha256

On macOS, use shasum -a 256 -c instead. It prints logaperture-1.0.0.zip: OK.

To check that the zip is the one the project released, verify the signature. Releases are signed with the key 7405 3993 02DB FD10 0BB7 C2C6 70F9 EFA2 295F D26E, which is on keyserver.ubuntu.com:

gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 7405399302DBFD100BB7C2C670F9EFA2295FD26E
gpg --verify logaperture-1.0.0.zip.asc logaperture-1.0.0.zip
gpg:                using RSA key 7405399302DBFD100BB7C2C670F9EFA2295FD26E
gpg: Good signature from "Logaperture Release (org.logaperture release artifact signing key) <releases@logaperture.org>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 7405 3993 02DB FD10 0BB7  C2C6 70F9 EFA2 295F D26E

What matters is Good signature and a primary key fingerprint that matches the one above. The warning only means you haven't certified the key yourself. The files on Maven Central are signed with the same key.

Next: install it on WildFly or on a plain JVM.

Maven Central

From 1.0.0-beta.1, each release is on Maven Central with the group org.logaperture and the version 1.0.0:

Artifact Type What it is
logaperture-agent jar the agent
logaperture-cli jar logctl's jar: run it with java -jar, which is all bin/logctl does
logaperture zip the release zip, the same file as on GitHub

Every file has a .asc GPG signature and checksums next to it.

The agent is not a dependency

No application code compiles against LogAperture, and the agent must not be on your application's class path. The JVM loads it from the -javaagent: line. So a build doesn't declare it as a dependency: it copies the jar somewhere, for example into a container image, and the -javaagent: line points there. The examples below do that.

Command line

To fetch the agent into a directory, for example while building a container image:

mvn dependency:copy -Dartifact=org.logaperture:logaperture-agent:1.0.0 \
    -DoutputDirectory=/opt/logaperture/lib -Dmdep.stripVersion=true

-Dmdep.stripVersion=true names it logaperture-agent.jar, as in the zip.

Maven

In your build's pom.xml, this copies the agent to target/agent/logaperture-agent.jar when the project is packaged:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <version>3.8.1</version>
  <executions>
    <execution>
      <id>copy-logaperture-agent</id>
      <phase>package</phase>
      <goals>
        <goal>copy</goal>
      </goals>
      <configuration>
        <artifactItems>
          <artifactItem>
            <groupId>org.logaperture</groupId>
            <artifactId>logaperture-agent</artifactId>
            <version>1.0.0</version>
          </artifactItem>
        </artifactItems>
        <outputDirectory>${project.build.directory}/agent</outputDirectory>
        <stripVersion>true</stripVersion>
      </configuration>
    </execution>
  </executions>
</plugin>

Gradle

This adds a copyLogapertureAgent task that copies the agent to build/agent/logaperture-agent.jar, and runs it as part of assemble. The project needs mavenCentral() in its repositories.

val logapertureAgent by configurations.creating {
    isTransitive = false
}

dependencies {
    logapertureAgent("org.logaperture:logaperture-agent:1.0.0")
}

val copyLogapertureAgent by tasks.registering(Copy::class) {
    from(logapertureAgent)
    into(layout.buildDirectory.dir("agent"))
    rename { "logaperture-agent.jar" }
}

tasks.named("assemble") {
    dependsOn(copyLogapertureAgent)
}
configurations {
    logapertureAgent {
        transitive = false
    }
}

dependencies {
    logapertureAgent 'org.logaperture:logaperture-agent:1.0.0'
}

def copyLogapertureAgent = tasks.register('copyLogapertureAgent', Copy) {
    from configurations.logapertureAgent
    into layout.buildDirectory.dir('agent')
    rename { 'logaperture-agent.jar' }
}

tasks.named('assemble') {
    dependsOn copyLogapertureAgent
}

Then

Point the JVM at the copied jar. In a container image built from your project, for example:

COPY target/agent/logaperture-agent.jar /opt/logaperture/lib/logaperture-agent.jar
ENV JAVA_TOOL_OPTIONS="-javaagent:/opt/logaperture/lib/logaperture-agent.jar -Dlogaperture.home=/tmp/logaperture"

-Dlogaperture.home names a directory the application's user can write, for LogAperture's state file, since a container's user often has no writable home directory. Use a volume instead of /tmp if sticky changes should survive the container being replaced.

On WildFly the -javaagent: line goes in the server's startup configuration instead: see Install on WildFly. logctl must run on the same machine, or in the same container, as the JVM: see Install on a plain JVM.