Support (or document how to bundle/use) custom Java Agents

[CAFxX]

We have received internal enquiries about how to bundle and use custom java agents with applications pushed using the Java buildpack.

I went through the docs but could not find anything significant. The only related thing I found is the support in the buildpack for extensions to add their java agents:

java-buildpack/lib/java_buildpack/component/java_opts.rb

Lines 37 to 63 in 233ffe2

	# Adds a +javaagent+ entry to the +JAVA_OPTS+. Prepends +$PWD+ to the path (relative to the droplet root) to
	# ensure that the path is always accurate.
	#
	# @param [Pathname] path the path to the +javaagent+ JAR
	# @return [JavaOpts] +self+ for chaining
	def add_javaagent(path)
	add_preformatted_options "-javaagent:#{qualify_path path}"
	end
	# Adds a +agentpath+ entry to the +JAVA_OPTS+. Prepends +$PWD+ to the path (relative to the droplet root) to
	# ensure that the path is always accurate.
	#
	# @param [Pathname] path the path to the +agentpath+ shared library
	# @param [Properties] props to append to the agentpath entry
	# @return [JavaOpts] +self+ for chaining
	def add_agentpath_with_props(path, props)
	add_preformatted_options "-agentpath:#{qualify_path path}=" + props.map { |k, v| "#{k}=#{v}" }.join(',')
	end
	# Adds an +agentpath+ entry to the +JAVA_OPTS+. Prepends +$PWD+ to the path (relative to the droplet root) to
	# ensure that the path is always accurate.
	#
	# @param [Pathname] path the path to the +native+ +agent+
	# @return [JavaOpts] +self+ for chaining
	def add_agentpath(path)
	add_preformatted_options "-agentpath:#{qualify_path path}"
	end

Ideally, as a user, I would like to be able to say: I have bundled path/to/my_agent.jar in my application.jar, add it to the JVM when starting and (optionally) also set something like the following related JAVA_OPTS: -Dmyagent.config_file=path/to/my_agent.conf, where path/to/myagent.conf contains the configuration that will be used by the agent.

If I missed it and this is already supported, then I think it would be helpful if the buildpack docs or the java tips included an example of how to do this.

edit: Just to clarify, we are not considering the forking mechanism because these agents can't be upstreamed under any circumstance. That means users would need to keep maintaining the fork of the buildpack, and that would basically undermine the value proposition of buildpacks.

[nebhale]

There's nothing built into the buildpack that treats this as a first-class concept. On the other hand, doing a cf set-env <APP> JAVA_OPTS '-javaagent:app/META-INF/myagent.jar -Dmyagent.config_file=app/META-INF/my_agent.conf' would work without any special support from the buildpack.

It's an interesting idea to direct support for this, but what did you have in mind for identifying agents and configuration that isn't setting an environment variable of some kind?

[vijayantony]

In order to use custom java agent, you can maintain your own internal agent repo and point to that custom java agent.
In the manifest.yml file you can point to your internal repo like below.

env:
  JBP_CONFIG_APP_DYNAMICS_AGENT: '{version: "4.2.15_6", repository_root: "http://youdomain:8082/AppDAgentRepo"}'

[nebhale]

@vijayantony But that's only for agents we already support. This question is more about support for any, non-public, agent without forking and adding a new component to support it.

[CAFxX]

@nebhale yes it's exactly as @vijayantony says

[nebhale]

@CAFxX I'm afraid I'm not following. You just want alternate versions of agents we already support, or you want a generic "agent" mechanism?

[CAFxX]

@nebhale the latter. Some of our users have non-public java agents they wish to use with the java buildpack, but without resorting to forking (and the maintaining the fork of) the buildpack.

Just to clarify, in my previous comment I was referring to this part of @vijayantony's comment:

This question is more about support for any, non-public, agent without forking and adding a new component to support it.

[nebhale]

I wrote that 😄, not @vijayantony. Good to see that we're on the same page.

[CAFxX]

That's what I get for commenting first things after waking up. 🤦‍♂️ Sorry.

[CAFxX]

@nebhale any thoughts on this? Was my explanation of the use case enough?

[nebhale]

Sorry, this had fallen off my radar. I think the outstanding question I have is

but what did you have in mind for identifying agents and configuration that isn't setting an environment variable of some kind?

Your suggestion of

Ideally, as a user, I would like to be able to say: I have bundled path/to/my_agent.jar in my application.jar, add it to the JVM when starting and (optionally) also set something like the following related JAVA_OPTS: -Dmyagent.config_file=path/to/my_agent.conf, where path/to/myagent.conf contains the configuration that will be used by the agent.

can already be achieved with cf set-env <APP> JAVA_OPTS '-javaagent:app/META-INF/myagent.jar -Dmyagent.config_file=app/META-INF/my_agent.conf'. If the plan is to pack agents and configuration within each application, this seems to be just as good as something where you'd say cf set-env <APP> JBP_CONFIG_AGENT "{path: 'path/to/my_agent.jar', java_opts: '-Dmyagent.config_file=app/META-INF/my_agent.conf'}"

Thoughts on the pros and cons of what's available today versus what you'd rather do?

[CAFxX]

can already be achieved with cf set-env <APP> JAVA_OPTS '-javaagent:app/META-INF/myagent.jar -Dmyagent.config_file=app/META-INF/my_agent.conf'

Great, if so then we're good. In this case we're in case 2 of my original post:

If I missed it and this is already supported, then I think it would be helpful if the buildpack docs or the java tips included an example of how to do this.

A couple of questions:

• Is this the officially supported way of injecting a user-provided agent? (I guess this would mean something along the lines of "is it covered by an acceptance test?")
• Assuming the answer to the previous question is yes, can we add this to the docs so that users have no doubts on how to go about doing this?

[nebhale]

I’d consider this officially supported as I regularly recommend it. It’s actually a more generalized case that includes things like “how do I include a private KeyStore in my application” as well. The pattern of “stick stuff in META-INF so it can’t be accidentally exposed, and then reference it with JAVA_OPTS” is tested as a general case and I’ll add some documentation about the strategy.

Do you have any recommendation of where in the documentation you’d expect to find this?

[CAFxX]

I would add it to the standard framework section of the README (it already contains a section about java options and about all the builtin agents) and ideally somewhere in https://docs.cloudfoundry.org/buildpacks/java/java-tips.html (e.g. the example in https://docs.cloudfoundry.org/buildpacks/java/java-tips.html#extension seem to imply that "the way" to use an agent is by forking/extending)

[xiaozaiyuji]

I have a confusion in spring native.


In my consideration,I have some question,
1.This is support GraalVM native image?
2.If this is support ,what I will config to use -javaagent ?
3.Does -javaagent is same or differnt with https://docs.spring.io/spring-native/docs/current/reference/htmlsingle/#tracing-agent?
4.What should config in Dmyagent.config_file=app/META-INF/my_agent.conf?

[dmikusa]

1.This is support GraalVM native image?

The CF Java buildpack does not directly support compiling Java native images. Although there is support for using GraalVM as a JVM. For native image on CF, you want to build outside of CF then use the binary-buildpack. See https://docs.cloudfoundry.org/buildpacks/java/java-native-image.html.