The Truly Dead Code Detector


This page contains documentation of how to configure the Codekvast agent.

The Codekvast agent is configured by means of the file codekvast.conf located in the root of your Java app (i.e., next to pom.xml or build.gradle).

Parameters can also be specified by environment variables. An environment variable named e.g., CODEKVAST_XXX_YYY will override a parameter named xxxYyy in codekvast.conf.

The format of the file is a standard Java Properties file, that is, key: value or key = value. Long lines can be continued by ending the line with a backslash ('\') and indenting the continuation line with at least one space.

The right-hand side may contain references to environment variables and Java system properties. Example:

codeBase = ${app.home}/lib (1)
codeBase = $APP_HOME/lib (2)
1 A Java system property specified by -Dapp.home=xxx
2 The environment variable APP_HOME

Look here for a sample codekvast.conf

Description of parameters

The following is an annotated codekvast.conf that describes all parameters and their default values.

# What is my application's name?
# Identifies the application's data in the Codekvast server.
# Example:
# appName = MyAppName
# Mandatory.
# appName =

# What is my app's version?
# The value of this parameter is a strategy for obtaining the actual version from the running application.
# Strategies: filename, manifest, property, literal (1)
# Example:
# appVersion = filename myApp-(.*).jar
# Default value:
# appVersion = literal unspecified

# Where are my application binaries?
# A comma-separated list of file system paths.
# Example:
# codeBase = build/install/myapp/libs (2)
# Mandatory.
# codeBase =

# What packages shall be tracked?
# A comma-separated list of package prefixes.
# Example:
# packages = com.acme,
# Mandatory.
# packages =

# What packages shall be _not_ be tracked?
# A comma-separated list of strings.
# Example:
# excludePackages = com.acme.timecritical, (3)
# Default value: An empty list.
# excludePackages =

# In which environment is the application deployed?
# An arbitrary string, useful when analysing the collected data.
# Example:
# environment = prod
# Default value:
# environment = <default>

# In which host is the application deployed?
# An arbitrary string, useful when analysing the collected data.
# Example:
# host = prod-1
# Default value: The value returned from
# hostname =
Table 1. Table Codekvast Agent parameters
Name Description Format Example Default Notes


Should codekvast-agent be enabled?

true or false.


If codekvast-agent is disabled, the AspectJ Weaver is not engaged and no attempt to contact the Codekvast server is made.


Which methods should be tracked?

One of the keywords public, protected, package-private or private.



See About specifying methodVisibility.


Should Codekvast Agent configure logging for Aspectj Weaver? Useful for trouble shooting.

A string.

aspectjOptions = -verbose -showWeaveInfo

See About Bridging AspectJ messages and AspectJ Load-Time Weaver configuration


Should aspectjweaver be configured to send AspectJ messages to java.util.logging (JUL)?

true or false.


See also About AspectJ options and About Bridging AspectJ messages.


Where is the Codekvast Server?

A URL obtained when signing up for Codekvast.


See also Running Codekvast as a Heroku add-on.


What is my license key for authenticating to the Codekvast Server?

A string obtained when signing up for Codekvast.

See also Running Codekvast as a Heroku add-on.


How long shall codekvast-agent wait for establishing a connection to the server?

A positive integer denoting a number of seconds.



How long shall codekvast-agent wait when reading a response from the server?

A positive integer denoting a number of seconds.



How long may a request to codekvastServer take at most?

A positive integer denoting a number of seconds.



Do we need to call the Codekvast Server via an HTTP proxy such as Squid?



Which port at the proxy should we connect to?

A socket port number


About specifying appVersion

Codekvast has some strategies for automatically finding the deployed application’s version.

This means that you can deploy new versions of your application without updating the appVersion field in codekvast.conf. Instead, Codekvast will use the configured strategy for extracting the application’s version.

Table 2. Table appVersion strategies
Strategy Description Example Result Notes


Locates a certain jar file within the codeBase with a well-known name and extracts the version from the jar file’s META-INF/MANIFEST.MF

appVersion = manifest myapp.jar

appVersion = manifest myapp.jar Implementation-Version

appVersion = manifest myapp.jar My-Custom-Version-Attribute

Example 1 and 2 yields the same result.

The value of the manifest attribute


Locates a jar file within the codeBase with a name that matches a regular expression and extracts the version from the part within parenthesis in the found file name.

appVersion = filename myapp-(.*).jar

The part within parenthesis.


Locates a text file within the codeBase with a specific name and extracts the version from within the file. If more than one parameter is specified, then the values are separated with a dash ('-').

appVersion = property version.txt version buildNumber


Provided that version.txt contains

version = 1.2 buildNumber = 4711

Note: The file is loaded into a java.util.Properties object.


The value in the configuration file is used as-is.

literal 3.14


About specifying codeBase

If the app is packaged as an executable jar, codeBase should be set to either a directory containing only the executable jar file or to the executable jar file itself.

If using Gradle, specify codeBase as build/libs/.

If using Maven, specify codeBase as target/.

If the app is packaged as a web archive (war), specify codeBase as path/to/WEB-INF

About excluding packages

Codekvast Agent is extremely efficient, and each tracked method only incurs a runtime cost of approximately 15 nanoseconds. If you have code that execute in tight loops even this low overhead could be too much.

In such situations you can exclude code from Codekvast.

About specifying methodVisibility

There is a certain overhead associated with tracking method calls, both in terms of CPU cycles and memory consumption. By specifying which methods shall be tracked, you can control the overhead.


Modern IDEs like IntelliJ are capable of suggesting deletion of dead methods as long as the method visibility is package private or private. They cannot suggest deletion of public or protected method is dead, since they cannot know what other clients to the method that exist.

Table 3. Table methodVisibility
Visibility Result Synonyms Overhead


Track public methods only.



Track public and protected methods. This is the default.



Track public, protected and package-private (default) methods.




Track all methods.



About AspectJ options

codekvast-agent can optionally set options for the AspectJ weaver, to facilitate debugging.

About Bridging AspectJ messages

codekvast-agent can optionally install an AspectJ IMessageHandler that acts as a bridge between aspectjweaver and java.util.logging (JUL).

This bridge is by default disabled, which means that AspectJ will log on standard output (if logging at all, depending on [aspectjOptions]).

Running Codekvast as a Heroku add-on

You attach Codekvast to you Heroku app by doing heroku addons:create codekvast. This will set a couple of environment parameters that should be used by codekvast.conf:

  • serverUrl = $CODEKVAST_URL


Updated 18 May 2018