Using instrumentation agent to automatically set control points

Java application can be automatically instrumented using Aperture Instrumentation Agent.

Supported technologies:

Framework	Supported versions
Armeria	1.15+
Netty	4.1+

The latest version of the Aperture Instrumentation Agent JAR file can be downloaded here.

 

Running the java agent

To statically load the java agent when running some application jar, use the following command:

java -javaagent:path/to/javaagent.jar -jar path/to/application.jar

Configuring the java agent

Aperture Java Instrumentation Agent can be configured using a properties file, system properties or environment variables:

Property name	Environment variable name	Default value	Description
aperture.javaagent.config.file	APERTURE_JAVAAGENT_CONFIG_FILE		Path to a file containing configuration properties
aperture.agent.hostname	APERTURE_AGENT_HOSTNAME	localhost	Hostname of Aperture Agent to connect to
aperture.agent.port	APERTURE_AGENT_PORT	8089	Port of Aperture Agent to connect to
aperture.control.point.name	APERTURE_CONTROL_POINT_NAME		(Required) Name of the control point this agent represents
aperture.javaagent.enable.fail.open	APERTURE_JAVAAGENT_ENABLE_FAIL_OPEN	true	Sets the fail-open behavior for the client when the Aperture Agent is unreachable. If set to true, all traffic will pass through; if set to false, all traffic will be blocked.
aperture.javaagent.insecure.grpc	APERTURE_JAVAAGENT_INSECURE_GRPC	true	Whether gRPC connection to Aperture Agent should be over plaintext
aperture.javaagent.root.certificate	APERTURE_JAVAAGENT_ROOT_CERTIFICATE		Path to a file containing root certificate to be used (insecure connection must be disabled)
aperture.connection.timeout.millis	APERTURE_CONNECTION_TIMEOUT_MILLIS	1000	Aperture Agent connection timeout in milliseconds
aperture.javaagent.ignored.paths	APERTURE_JAVAAGENT_IGNORED_PATHS		Comma-separated list of paths that should not start a flow
aperture.javaagent.ignored.paths.regex	APERTURE_JAVAAGENT_IGNORED_PATHS_REGEX		Whether the configured ignored paths should be read as regular expressions

info

The priority order for configuration look is system.property > ENV_VARIABLE > properties file.

Using command line properties

Example invocation with commandline-set properties:

java -javaagent:path/to/javaagent.jar \
-Daperture.agent.hostname="some_host" \
-Daperture.agent.port=12345 \
-Daperture.control.point.name="awesomeFeature" \
-Daperture.javaagent.ignored.paths="/health,/connected" \
-jar path/to/application.jar

Using properties file

Example invocation using a properties file:

java -javaagent:path/to/javaagent.jar \
-Daperture.javaagent.config.file="/config.properties" \
-jar path/to/application.jar

The /config.properties file:

aperture.agent.hostname=some_host
aperture.agent.port=12345
aperture.control.point.name=awesomeFeature
aperture.javaagent.ignored.paths=/health,/connected