diff --git a/docs/setup-attach-api.asciidoc b/docs/setup-attach-api.asciidoc
index 180992cdb9..ae46971a04 100644
--- a/docs/setup-attach-api.asciidoc
+++ b/docs/setup-attach-api.asciidoc
@@ -20,6 +20,12 @@ which is part of the JDK distribution and does not typically come with the JRE d
 Currently, this does not work in combination with OSGi containers (which includes most application servers).
 The symptom is that there will be a lot of exceptions like this: `java.lang.NoClassDefFoundError: co/elastic/apm/agent/servlet/ServletApiAdvice`.
 
+There can only be one agent instance with one configuration per JVM.
+So if you deploy multiple web applications to the same application server and call `ElasticApmAttacher.attach()` in each application,
+the first `attach()` wins and the second one will be ignored.
+That also means that if you are configuring the agent with `elasticapm.properties`,
+the application which attaches first gets to decide the configuration.
+See the default value description of the <<config-service-name>> configuration option for ways to have different `service.name`s for each deployment.
 
 [float]
 [[setup-attach-api-usage]]