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 (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, foo.bar
#
# Mandatory.
# packages =

# What packages shall be _not_ be tracked?
# A comma-separated list of strings.
#
# Example:
# excludePackages = com.acme.timecritical, foo.bar.even.more.time.critical (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 java.net.InetAddress.getLocalHost().getHostName().
#
# hostname =

1	See also About specifying appVersion.
2	See also About specifying codeBase.
3	See also About excluding packages.

Table 1. Table Codekvast Agent parameters
Name	Description	Format	Example	Default	Notes
enabled	Should codekvast-agent be enabled?	true or false.		true	If codekvast-agent is disabled, the AspectJ Weaver is not engaged and no attempt to contact the Codekvast server is made.
methodVisibility	Which methods should be tracked?	One of the keywords public, protected, package-private or private.	methodVisibility=protected	protected	See About specifying methodVisibility.
aspectjOptions	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
bridgeAspectjMessagesToJUL	Should aspectjweaver be configured to send AspectJ messages to `java.util.logging` (JUL)?	true or false.		false	See also About AspectJ options and About Bridging AspectJ messages.
serverUrl	Where is the Codekvast Server?	A URL obtained when signing up for Codekvast.	https://api.codekvast.io	http://localhost:8080	See also Running Codekvast as a Heroku add-on.
licenseKey	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.
httpConnectTimeoutSeconds	How long shall `codekvast-agent` wait for establishing a connection to the server?	A positive integer denoting a number of seconds.		10
httpReadTimeoutSeconds	How long shall `codekvast-agent` wait when reading a response from the server?	A positive integer denoting a number of seconds.		10
httpWriteTimeoutSeconds	How long may a request to codekvastServer take at most?	A positive integer denoting a number of seconds.		30
httpProxyHost	Do we need to call the Codekvast Server via an HTTP proxy such as Squid?	hostname-or-IP-address	10.57.0.10
httpProxyPort	Which port at the proxy should we connect to?	A socket port number		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.

Table 2. Table appVersion strategies
Strategy	Description	Example	Result	Notes
manifest	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
filename	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.
property	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`	1.2-4711	Provided that `version.txt` contains `version = 1.2` `buildNumber = 4711` Note: The file is loaded into a `java.util.Properties` object.
literal	The value in the configuration file is used as-is.	`literal 3.14`	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.

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.

Table 3. Table methodVisibility
Visibility	Result	Synonyms	Overhead
public	Track public methods only.		Lowest
protected	Track public and protected methods. This is the default.		Lower
package-private	Track public, protected and package-private (default) methods.	!private	Higher
private	Track all methods.	all	Highest

About AspectJ options

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

See AspectJ Load-Time Weaver configuration.

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
licenseKey = $CODEKVAST_LICENSE_KEY

Updated 18 May 2018