Codekvast

The Truly Dead Code Detector

Configuration

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

[verse] — 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 — 

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

[verse] — When running in Heroku, serverUrl is specified by the environment variable $CODEKVAST_URL and should not be changed See also configuring Codekvast as a Heroku add-on. — 


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

[verse] — When running in Heroku, licenseKey is specified by the environment variable $CODEKVAST_LICENSE_KEY and should not be changed See also configuring Codekvast as a Heroku add-on. — 


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

[verse] — 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

property

Description

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

Example

appVersion = property version.txt version buildNumber

Result

1.2-4711

Provided that version.txt contains

[verse] —   version = 1.2   buildNumber = 4711 — 

Note

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


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


Updated 18 May 2018