Codekvast

The Truly Dead Code Detector

Read more at What is Codekvast? and Why Codekvast?

Config

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
codeBase = $APP_HOME/lib

Look here for a sample codekvast.conf

Codekvast Agent parameters

Mandatory parameters in bold face.

Name:appName
Description:What is my application's name? Used for identifying the application in the Codekvast dashboard.
Format:A string.
Example:MyApp
Default:

Name:appVersion
Description:What is my application's version? Used for tracking dead code evolution.
Format:A string.
Example:filename myapp-(.*).jar
Default:unspecified
See also:About specifying appVersion.

Name:codeBase
Description:Where are my application binaries?
Format:A comma-separated list of file system paths.
Example:codeBase = build/install/myapp/libs
Default:
Note:
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/
Since:Support for Spring Boot executable jars was added in version 0.21.2.

Name:packages
Description:What packages shall be tracked?
Format:A comma-separated list of strings.
Example:packages = com.acme, foo.bar
Default:

Name:excludePackages
Description:What packages shall not be tracked?
Format:A comma-separated list of strings.
Example:excludePackages = com.acme.timecritical, foo.bar.even.more.time.critical
Default:
See also:About excluding packages

Name:environment
Description:In which environment is the application deployed?
Format:An arbitrary string, useful when analysing the collected data.
Example:environment = production
Default:

Name:methodVisibility
Description:Which methods should be tracked?
Format:One of the keywords public, protected, package-private or private.
Example:methodVisibility=protected
Default:protected
See also:About specifying methodVisibility

Name:aspectjOptions
Description:Should Codekvast Agent configure logging for Aspectj Weaver? Useful for trouble shooting.
Format:A string.
Example:aspectjOptions = -verbose -showWeaveInfo
Default:
See also:bridgeAspectjMessagesToJUL, About Bridging AspectJ messages and AspectJ Load-Time Weaver configuration

Name:bridgeAspectjMessagesToJUL
Description:Should aspectjweaver be configured to send AspectJ messages to java.util.logging (JUL)?
Format:true or false.
Example:
Default:false
See also:aspectjOptions and About Bridging AspectJ messages.

Name:serverUrl
Description:Where is the Codekvast Server?
Format:A HTTP or HTTPS URL
Example:http://api.codekvast.io
Default:http://localhost:8080
Note:
When running in Heroku, serverUrl is specified by the environment variable $CODEKVAST_URL and should not be changed

Name:licenseKey
Description:What is my license key for authenticating to the Codekvast Server?
Format:A string obtained when doing heroku addons:create codekvast
Example:
Default:
Note:
When running in Heroku, licenseKey is specified by the environment variable $CODEKVAST_LICENSE_KEY and should not be changed

Name:httpConnectTimeoutSeconds
Description:How long shall codekvast-agent wait for establishing a connection to the server?
Format:A positive integer denoting a number of seconds.
Example:
Default:10

Name:httpReadTimeoutSeconds
Description:How long shall codekvast-agent wait when reading a response from the server?
Format:A positive integer denoting a number of seconds.
Example:
Default:10

Name:httpWriteTimeoutSeconds
Description:How long may a request to codekvastServer take at most?
Format:A positive integer denoting a number of seconds.
Example:
Default:30

Name:httpProxyHost
Description:Do we need to call the Codekvast Server via an HTTP proxy such as Squid?
Format:hostname-or-IP-address
Example:10.57.0.10
Default:

Name:httpProxyPort
Description:Which port at the proxy should we connect to?
Format:A socket port number
Example:
Default:3128

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.


Strategy:manifest
Description: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
Example:
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.

Result:The value of the manifest attribute

Strategy:filename
Description: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.
Example:appVersion = filename myapp-(.*).jar
Result:The part within parenthesis.

Strategy:literal
Description:The value in the configuration file is used as-is.
Example:literal 3.14
Result:3.14

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.

Note
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.

Visibility:public
Result:Track public methods only.
Synonyms:
Overhead:Lowest

Visibility:protected
Result:Track public and protected methods. This is the default.
Synonyms:
Overhead:Lower

Visibility:package-private
Result:Track public, protected and package-private (default) methods.
Synonyms:!private
Overhead:Higher

Visibility:private
Result:Track all methods.
Synonyms:all
Overhead:Highest

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).

See also aspectjOptions, AspectJ Load-Time Weaver configuration.