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/
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: | 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: | 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: | 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: | |
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).
See also aspectjOptions, AspectJ Load-Time Weaver configuration.