Document the java agent attacher functionality [tech preview]

simitt commented 2 years ago

The java agent attacher functionality has been reworked and improved to be started under the same user and with the Java installation that the application runs with (with https://github.com/elastic/apm-server/issues/8304).

This feature is in tech preview and not yet documented. The Java agent attacher is customer facing as part of the APM Integration.

The documentation should include:

disclaimer that this is tech preview
mention level of support, see https://github.com/elastic/apm-server/issues/8708#issuecomment-1242961760
how the feature works
brief description of config options and rules

The general outline how this feature works is the following:

An Elastic Agent is installed on an edge machine, and configured to auto instrument any matching java process, that is running on the same host machine where the Elastic Agent is running.

Note: Java agent auto attachment is NOT supported on the Elastic Cloud agent policy, as it would not be beneficial to users to instrument any java processes on the ingest server cloud installation.

To get started with the feature following steps are required:

Create an Elastic Agent policy for the Elastic Agents on the edge machine (default settings).
Add the APM Integration to the previously created Elastic Agent policy (default settings).
Configure the Java Auto Attacher feature on this APM Integration (minimum requirement is to enable it).
Enroll an Elastic Agent to this Elastic Agent policy. For enrolling an Elastic Agent, one needs a centrally set up Fleet Server. The easiest way to achieve this is to spin up an Elastic cloud deployment with Ingest Server enabled and use this centrally run Fleet Server.

Config options and rules

@eyalkoren please provide relevant input on this.

bmorelli25 commented 2 years ago

@eyalkoren are we ready to document this? There are a lot of conversations, issues, and PRs for this one and I'm struggling to follow everything. Should we set up a time to meet and discuss?

eyalkoren commented 2 years ago

Yes @bmorelli25, let's meet, I need to see your lovely smile anyway

eyalkoren commented 2 years ago

@bmorelli25 I don't think we'll have a change to do this synchronously any time soon... Please take a look at my status summary in the tracking issue at the Java agent repo. As long as the mentioned issues remain unresolved, the status would remain the same:

Linux - fully supported
Windows - only supported if the user that runs the Java app is the same user that runs the Elastic agent. I think the latter should only be the Windows Administrator role, but I am not sure. This is not sufficient in order to claim we support Windows, however since this feature is still in technical preview, this has its value as it is good enough for POCs and trial users that want to test and explore functionality.
macOS - not supported

bmorelli25 commented 1 year ago

@AlexanderWert with Eyal out for the foreseeable future, is there anyone else you can recommend to work on this with?

elastic / apm-server