Add a warning about BaseHTTPMiddleware to Starlette docs (#1735)

* Add a warning about BaseHTTPMiddleware to Starlette docs

Also switch to using get_client() and make the docs simpler for
environment variable configuration.

* CHANGELOG

CHANGELOG.asciidoc

@@ -29,6 +29,19 @@ endif::[]
 //===== Bug fixes
 //
 
+=== Unreleased
+
+// Unreleased changes go here
+// When the next release happens, nest these changes under the "Python Agent version 6.x" heading
+//[float]
+//===== Features
+
+[float]
+===== Bug fixes
+
+* Small fix to underlying Starlette logic to prevent duplicate Client objects {pull}1735[#1735]
+
+
 
 [[release-notes-6.x]]
 === Python Agent version 6.x

docs/starlette.asciidoc

@@ -30,18 +30,23 @@ initialization arguments.
 You can find a list of all available settings in the
 <<configuration, Configuration>> page.
 
-To initialize the agent for your application using environment variables:
+To initialize the agent for your application using environment variables, add
+the ElasticAPM middleware to your Starlette application:
 
 [source,python]
 ----
 from starlette.applications import Starlette
-from elasticapm.contrib.starlette import make_apm_client, ElasticAPM
+from elasticapm.contrib.starlette ElasticAPM
 
-apm = make_apm_client()
 app = Starlette()
-app.add_middleware(ElasticAPM, client=apm)
+app.add_middleware(ElasticAPM)
 ----
 
+WARNING: If you are using any `BaseHTTPMiddleware` middleware, you must add them
+*before* the ElasticAPM middleware. This is because `BaseHTTPMiddleware` breaks
+`contextvar` propagation, as noted
+https://www.starlette.io/middleware/#limitations[here].
+
 To configure the agent using initialization arguments:
 
 [source,python]
@@ -67,11 +72,10 @@ is almost exactly the same as with Starlette:
 [source,python]
 ----
 from fastapi import FastAPI
-from elasticapm.contrib.starlette import make_apm_client, ElasticAPM
+from elasticapm.contrib.starlette ElasticAPM
 
-apm = make_apm_client()
 app = FastAPI()
-app.add_middleware(ElasticAPM, client=apm)
+app.add_middleware(ElasticAPM)
 ----
 
 [float]

elasticapm/contrib/starlette/__init__.py

@@ -42,7 +42,7 @@
 
 import elasticapm
 import elasticapm.instrumentation.control
-from elasticapm.base import Client
+from elasticapm.base import Client, get_client
 from elasticapm.conf import constants
 from elasticapm.contrib.asyncio.traces import set_context
 from elasticapm.contrib.starlette.utils import get_body, get_data_from_request, get_data_from_response
@@ -115,6 +115,8 @@ def __init__(self, app: ASGIApp, client: Optional[Client], **kwargs):
         if client:
             self.client = client
         else:
+            self.client = get_client()
+        if not self.client:
             self.client = make_apm_client(**kwargs)
 
         if self.client.config.instrument and self.client.config.enabled: