Skip to main content
Version: 2.6.0

Using instrumentation agent to automatically set control points

Java application can be automatically instrumented using Aperture Instrumentation Agent.

Supported technologies:

FrameworkSupported versions
Armeria1.15+
Netty4.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 nameEnvironment variable nameDefault valueDescription
aperture.javaagent.config.fileAPERTURE_JAVAAGENT_CONFIG_FILEPath to a file containing configuration properties
aperture.agent.hostnameAPERTURE_AGENT_HOSTNAMElocalhostHostname of Aperture Agent to connect to
aperture.agent.portAPERTURE_AGENT_PORT8089Port of Aperture Agent to connect to
aperture.control.point.nameAPERTURE_CONTROL_POINT_NAME(Required) Name of the control point this agent represents
aperture.javaagent.enable.fail.openAPERTURE_JAVAAGENT_ENABLE_FAIL_OPENtrueSets 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.grpcAPERTURE_JAVAAGENT_INSECURE_GRPCtrueWhether gRPC connection to Aperture Agent should be over plaintext
aperture.javaagent.root.certificateAPERTURE_JAVAAGENT_ROOT_CERTIFICATEPath to a file containing root certificate to be used
(insecure connection must be disabled)
aperture.connection.timeout.millisAPERTURE_CONNECTION_TIMEOUT_MILLIS1000Aperture Agent connection timeout in milliseconds
aperture.javaagent.ignored.pathsAPERTURE_JAVAAGENT_IGNORED_PATHSComma-separated list of paths that should not start a flow
aperture.javaagent.ignored.paths.regexAPERTURE_JAVAAGENT_IGNORED_PATHS_REGEXWhether 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