elastic · colleenmcginnis · Jul 15, 2025
diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
@@ -29,7 +29,7 @@ endif::[]
 //===== Bug fixes
 //
 
-[[release-notes-6.x]]
+[[_release-notes-6.x]]
 === Python Agent version 6.x
 
 [[release-notes-6.23.0]]
@@ -740,7 +740,7 @@ s3-prefix).
 
 * Fix for GraphQL span spamming from scalar fields with required flag {pull}1015[#1015]
 
-[[release-notes-5.x]]
+[[_release-notes-5.x]]
 === Python Agent version 5.x
 
 
@@ -1130,7 +1130,7 @@ https://github.com/elastic/apm-agent-python/compare/v4.2.2\...v5.0.0[Check the d
 * Fixed an issue with certificate pinning {pull}497[#497]
 * Lowered log level of transport success messages {pull}527[#527], {pull}531[#531]
 
-[[release-notes-4.x]]
+[[_release-notes-4.x]]
 === Python Agent version 4.x
 
 [[release-notes-4.2.2]]
@@ -1225,7 +1225,7 @@ Other changes:
 * on Python 3.7, use https://docs.python.org/3/library/contextvars.html[contextvars] instead of threadlocals for storing
 current transaction and span. This is a necessary precursor for full asyncio support. {pull}291[#291]
 
-[[release-notes-3.x]]
+[[_release-notes-3.x]]
 === Python Agent version 3.x
 
 [[release-notes-3.0.2]]
@@ -1263,7 +1263,7 @@ from `-1` (always collect) to `5` (only collect for spans longer than 5 ms) {pul
 - added instrumentation for pymssql {pull}241[#241]
 - added instrumentation for pyodbc {pull}238[#238]
 
-[[release-notes-2.x]]
+[[_release-notes-2.x]]
 === Python Agent version 2.x
 
 [[release-notes-2.2.1]]
@@ -1354,7 +1354,7 @@ https://github.com/elastic/apm-agent-python/compare/v1.0.0\...v2.0.0[Check the d
     - `max_event_queue_length` became `max_queue_size`
     - `timeout` became `server_timeout`
 
-[[release-notes-1.x]]
+[[_release-notes-1.x]]
 === Python Agent version 1.x
 
 [[release-notes-1.0.0]]

diff --git a/docs/advanced-topics.asciidoc b/docs/advanced-topics.asciidoc
@@ -1,10 +1,10 @@
-[[advanced-topics]]
+[[_advanced-topics]]
 == Advanced Topics
 
-* <<instrumenting-custom-code>>
-* <<sanitizing-data>>
-* <<how-the-agent-works>>
-* <<run-tests-locally>>
+* <<_instrumenting-custom-code>>
+* <<_sanitizing-data>>
+* <<_how-the-agent-works>>
+* <<_run-tests-locally>>
 
 include::./custom-instrumentation.asciidoc[Custom Instrumentation]
 include::./sanitizing-data.asciidoc[Sanitizing Data]

diff --git a/docs/aiohttp-server.asciidoc b/docs/aiohttp-server.asciidoc
@@ -1,4 +1,4 @@
-[[aiohttp-server-support]]
+[[_aiohttp-server-support]]
 === Aiohttp Server support
 
 Getting Elastic APM set up for your Aiohttp Server project is easy,
@@ -27,7 +27,7 @@ To set up the agent, you need to initialize it with appropriate settings.
 The settings are configured either via environment variables,
 the application's settings, or as initialization arguments.
 
-You can find a list of all available settings in the <<configuration, Configuration>> page.
+You can find a list of all available settings in the <<_configuration, Configuration>> page.
 
 To initialize the agent for your application using environment variables:
 
@@ -119,6 +119,6 @@ and any requests containing `/api/`.
 [[supported-aiohttp-and-python-versions]]
 ==== Supported aiohttp and Python versions
 
-A list of supported <<supported-aiohttp,aiohttp>> and <<supported-python,Python>> versions can be found on our <<supported-technologies,Supported Technologies>> page.  
+A list of supported <<supported-aiohttp,aiohttp>> and <<supported-python,Python>> versions can be found on our <<_supported-technologies,Supported Technologies>> page.
 
-NOTE: Elastic APM only supports `asyncio` when using Python 3.7+ 
+NOTE: Elastic APM only supports `asyncio` when using Python 3.7+
diff --git a/docs/api.asciidoc b/docs/api.asciidoc
@@ -1,4 +1,4 @@
-[[api]]
+[[_api]]
 == API reference
 
 The Elastic APM Python agent has several public APIs.
@@ -28,10 +28,10 @@ from elasticapm import Client
 client = Client({'SERVICE_NAME': 'example'}, **defaults)
 ----
 
- * `config`: A dictionary, with key/value configuration. For the possible configuration keys, see <<configuration, Configuration>>.
+ * `config`: A dictionary, with key/value configuration. For the possible configuration keys, see <<_configuration, Configuration>>.
  * `**defaults`: default values for configuration. These can be omitted in most cases, and take the least precedence.
 
-NOTE: framework integrations like <<django-support, Django>> and <<flask-support, Flask>>
+NOTE: framework integrations like <<_django-support, Django>> and <<_flask-support, Flask>>
 instantiate the client automatically.
 
 [float]

diff --git a/docs/asgi-middleware.asciidoc b/docs/asgi-middleware.asciidoc
@@ -1,4 +1,4 @@
-[[asgi-middleware]]
+[[_asgi-middleware]]
 === ASGI Middleware
 
 experimental::[]
@@ -7,7 +7,7 @@ Incorporating Elastic APM into your ASGI-based project only requires a few easy
 steps.
 
 NOTE: Several ASGI frameworks are supported natively.
-Please check <<supported-technologies,Supported Technologies>> for more information
+Please check <<_supported-technologies,Supported Technologies>> for more information
 
 [float]
 [[asgi-installation]]
@@ -33,7 +33,7 @@ The settings are configured either via environment variables, or as
 initialization arguments.
 
 You can find a list of all available settings in the
-<<configuration, Configuration>> page.
+<<_configuration, Configuration>> page.
 
 To set up the APM agent, wrap your ASGI app with the `ASGITracingMiddleware`:
 
@@ -49,13 +49,13 @@ app = ASGITracingMiddleware(app)
 
 Make sure to call <<api-set-transaction-name, `elasticapm.set_transaction_name()`>> with an appropriate transaction name in all your routes.
 
-NOTE: Currently, the agent doesn't support automatic capturing of exceptions. 
+NOTE: Currently, the agent doesn't support automatic capturing of exceptions.
 You can follow progress on this issue on https://github.com/elastic/apm-agent-python/issues/1548[Github].
 
 [float]
 [[supported-python-versions]]
 ==== Supported Python versions
 
-A list of supported <<supported-python,Python>> versions can be found on our <<supported-technologies,Supported Technologies>> page.
+A list of supported <<supported-python,Python>> versions can be found on our <<_supported-technologies,Supported Technologies>> page.
 
 NOTE: Elastic APM only supports `asyncio` when using Python 3.7+
diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc
@@ -1,4 +1,4 @@
-[[configuration]]
+[[_configuration]]
 == Configuration
 
 To adapt the Elastic APM agent to your needs, configure it using environment variables or framework-specific
@@ -115,7 +115,7 @@ or whitespace-only.
 
 The URL for your APM Server.
 The URL must be fully qualified, including protocol (`http` or `https`) and port.
-Note: Do not set this if you are using APM in an AWS lambda function. APM Agents are designed to proxy their calls to the APM Server through the lambda extension. Instead, set `ELASTIC_APM_LAMBDA_APM_SERVER`. For more info, see <<lambda-support,AWS Lambda>>.
+Note: Do not set this if you are using APM in an AWS lambda function. APM Agents are designed to proxy their calls to the APM Server through the lambda extension. Instead, set `ELASTIC_APM_LAMBDA_APM_SERVER`. For more info, see <<_lambda-support,AWS Lambda>>.
 
 [float]
 [[config-enabled]]
@@ -637,7 +637,7 @@ the Python agent can optionally capture the request and response headers.
 Possible values: `true`, `false`
 
 WARNING: Request headers often contain sensitive values like session IDs and cookies.
-See <<sanitizing-data,sanitizing data>> for more information on how to filter out sensitive data.
+See <<_sanitizing-data,sanitizing data>> for more information on how to filter out sensitive data.
 
 [float]
 [[config-transaction-max-spans]]
@@ -859,7 +859,7 @@ to avoid stampedes of instances that start at the same time.
 |============
 
 A list of processors to process transactions and errors.
-For more information, see <<sanitizing-data, Sanitizing Data>>.
+For more information, see <<_sanitizing-data, Sanitizing Data>>.
 
 WARNING: We recommend always including the default set of validators if you customize this setting.
 
@@ -887,7 +887,7 @@ WARNING: We recommend always including the default set of validators if you cust
 |============
 
 A list of glob-matched field names to match and mask when using processors.
-For more information, see <<sanitizing-data, Sanitizing Data>>.
+For more information, see <<_sanitizing-data, Sanitizing Data>>.
 
 WARNING: We recommend always including the default set of field name matches
 if you customize this setting.

diff --git a/docs/custom-instrumentation.asciidoc b/docs/custom-instrumentation.asciidoc
@@ -1,4 +1,4 @@
-[[instrumenting-custom-code]]
+[[_instrumenting-custom-code]]
 === Instrumenting custom code
 
 [float]
@@ -9,7 +9,7 @@ Elastic APM instruments a variety of libraries out of the box, but sometimes you
 need to know how long a specific function took or how often it gets
 called.
 
-Assuming you're using one of our <<set-up, supported frameworks>>, you can
+Assuming you're using one of our <<_set-up, supported frameworks>>, you can
 apply the `@elasticapm.capture_span()` decorator to achieve exactly that. If
 you're not using a supported framework, see
 <<instrumenting-custom-code-transactions, Creating New Transactions>>.
@@ -64,7 +64,7 @@ See <<api-capture-span, the API docs>> for more information on `capture_span`.
 ==== Creating New Transactions
 
 It's important to note that `elasticapm.capture_span` only works if there is
-an existing transaction. If you're not using one of our <<set-up, supported
+an existing transaction. If you're not using one of our <<_set-up, supported
 frameworks>>, you need to create a `Client` object and begin and end the
 transactions yourself. You can even utilize the agent's
 <<automatic-instrumentation,automatic instrumentation>>!

diff --git a/docs/django.asciidoc b/docs/django.asciidoc
@@ -1,4 +1,4 @@
-[[django-support]]
+[[_django-support]]
 === Django support
 
 Getting Elastic APM set up for your Django project is easy, and there are various ways you can tweak it to fit to your needs.
@@ -59,7 +59,7 @@ ELASTIC_APM_SECRET_TOKEN=<SECRET-TOKEN>
 
 You now have basic error logging set up, and everything resulting in a 500 HTTP status code will be reported to the APM Server.
 
-You can find a list of all available settings in the <<configuration, Configuration>> page.
+You can find a list of all available settings in the <<_configuration, Configuration>> page.
 
 [NOTE]
 ====
@@ -98,7 +98,7 @@ You can find more information on what we instrument in the <<automatic-instrumen
 ===== Instrumenting custom Python code
 
 To gain further insights into the performance of your code, please see
-<<instrumenting-custom-code, instrumenting custom code>>.
+<<_instrumenting-custom-code, instrumenting custom code>>.
 
 [float]
 [[django-ignoring-specific-views]]
@@ -372,4 +372,4 @@ Success! We tracked the error successfully! You should be able to see it in a fe
 [[supported-django-and-python-versions]]
 ==== Supported Django and Python versions
 
-A list of supported <<supported-django,Django>> and <<supported-python,Python>> versions can be found on our <<supported-technologies,Supported Technologies>> page.
+A list of supported <<supported-django,Django>> and <<supported-python,Python>> versions can be found on our <<_supported-technologies,Supported Technologies>> page.
diff --git a/docs/flask.asciidoc b/docs/flask.asciidoc
@@ -1,4 +1,4 @@
-[[flask-support]]
+[[_flask-support]]
 === Flask support
 
 Getting Elastic APM set up for your Flask project is easy,
@@ -36,7 +36,7 @@ To set up the agent, you need to initialize it with appropriate settings.
 The settings are configured either via environment variables,
 the application's settings, or as initialization arguments.
 
-You can find a list of all available settings in the <<configuration, Configuration>> page.
+You can find a list of all available settings in the <<_configuration, Configuration>> page.
 
 To initialize the agent for your application using environment variables:
 
@@ -140,7 +140,7 @@ apm.capture_message('hello, world!')
 
 This feature has been deprecated and will be removed in a future version.
 
-Please see our <<logs,Logging>> documentation for other supported ways to ship
+Please see our <<_logs,Logging>> documentation for other supported ways to ship
 logs to Elasticsearch.
 
 Note that you can always send exceptions and messages to the APM Server with
@@ -242,4 +242,4 @@ See the {apm-rum-ref}[JavaScript RUM agent documentation] for more information.
 [[supported-flask-and-python-versions]]
 ==== Supported Flask and Python versions
 
-A list of supported <<supported-flask,Flask>> and <<supported-python,Python>> versions can be found on our <<supported-technologies,Supported Technologies>> page.
+A list of supported <<supported-flask,Flask>> and <<supported-python,Python>> versions can be found on our <<_supported-technologies,Supported Technologies>> page.
diff --git a/docs/getting-started.asciidoc b/docs/getting-started.asciidoc
@@ -1,4 +1,4 @@
-[[getting-started]]
+[[_getting-started]]
 == Introduction
 
 The Elastic APM Python agent sends performance metrics and error logs to the APM Server.
@@ -10,7 +10,7 @@ It has built-in support for Django and Flask performance metrics and error loggi
 
 The Python Agent instruments your application to collect APM events in a few different ways:
 
-To collect data about incoming requests and background tasks, the Agent integrates with <<supported-technologies,supported technologies>> to make use of hooks and signals provided by the framework.
+To collect data about incoming requests and background tasks, the Agent integrates with <<_supported-technologies,supported technologies>> to make use of hooks and signals provided by the framework.
 These framework integrations require limited code changes in your application.
 
 To collect data from database drivers, HTTP libraries etc.,
@@ -21,7 +21,7 @@ In addition to APM and error data,
 the Python agent also collects system and application metrics in regular intervals.
 This collection happens in a background thread that is started by the agent.
 
-More detailed information on how the Agent works can be found in the <<how-the-agent-works,advanced topics>>.
+More detailed information on how the Agent works can be found in the <<_how-the-agent-works,advanced topics>>.
 
 [float]
 [[additional-components]]

diff --git a/docs/grpc.asciidoc b/docs/grpc.asciidoc
@@ -45,7 +45,7 @@ The settings are configured either via environment variables, or as
 initialization arguments.
 
 You can find a list of all available settings in the
-<<configuration, Configuration>> page.
+<<_configuration, Configuration>> page.
 
 To initialize the agent for your application using environment variables:
 

diff --git a/docs/how-the-agent-works.asciidoc b/docs/how-the-agent-works.asciidoc
@@ -1,4 +1,4 @@
-[[how-the-agent-works]]
+[[_how-the-agent-works]]
 === How the Agent works
 
 To gather APM events (called transactions and spans), errors and metrics,
@@ -15,7 +15,7 @@ framework integration, instrumentation, and background collection.
 ==== Framework integration
 
 To collect data about incoming requests and background tasks,
-we integrate with frameworks like <<django-support,Django>>, <<flask-support,Flask>> and Celery.
+we integrate with frameworks like <<_django-support,Django>>, <<_flask-support,Flask>> and Celery.
 Whenever possible, framework integrations make use of hooks and signals provided by the framework.
 Examples of this are:
 
@@ -32,7 +32,7 @@ E.g. for Django, you need to add `elasticapm.contrib.django` to `INSTALLED_APPS`
 
 If you're not using a supported framework, for example, a simple Python script, you can still
 leverage the agent's <<automatic-instrumentation,automatic instrumentation>>. Check out
-our docs on <<instrumenting-custom-code, instrumenting custom code>>.
+our docs on <<_instrumenting-custom-code, instrumenting custom code>>.
 
 [float]
 [[how-it-works-instrumentation]]

diff --git a/docs/logging.asciidoc b/docs/logging.asciidoc
@@ -1,4 +1,4 @@
-[[logs]]
+[[_logs]]
 == Logs
 
 Elastic Python APM Agent provides the following log features:

diff --git a/docs/metrics.asciidoc b/docs/metrics.asciidoc
@@ -1,4 +1,4 @@
-[[metrics]]
+[[_metrics]]
 == Metrics
 
 With Elastic APM, you can capture system and process metrics.

diff --git a/docs/opentelemetry.asciidoc b/docs/opentelemetry.asciidoc
@@ -1,4 +1,4 @@
-[[opentelemetry-bridge]]
+[[_opentelemetry-bridge]]
 == OpenTelemetry API Bridge
 
 The Elastic APM OpenTelemetry bridge allows you to create Elastic APM `Transactions` and `Spans`,
@@ -57,7 +57,7 @@ with tracer.start_as_current_span("test"):
 
   * `elasticapm_client`: an already instantiated Elastic APM client
   * `config`: a configuration dictionary, which will be used to instantiate a new Elastic APM client,
-     e.g. `{"SERVER_URL": "https://example.org"}`. See <<configuration, configuration>> for more information.
+     e.g. `{"SERVER_URL": "https://example.org"}`. See <<_configuration, configuration>> for more information.
 
 The `Tracer` object mirrors the upstream interface on the
 https://opentelemetry-python.readthedocs.io/en/latest/api/trace.html#opentelemetry.trace.Tracer[OpenTelemetry `Tracer` object.]