[docs] Documentation restructure (#617)

Author: bmorelli25

CHANGELOG.asciidoc

@@ -0,0 +1 @@
+This is a placeholder file. Release notes are published in CHANGELOG.md

docs/advanced-topics.asciidoc

@@ -4,10 +4,9 @@
 * <<instrumenting-custom-code>>
 * <<sanitizing-data>>
 * <<run-tests-locally>>
-* <<logging-integrations>>
-* <<log-correlation>>
 
 include::./custom-instrumentation.asciidoc[Custom Instrumentation]
 include::./sanitizing-data.asciidoc[Sanitizing Data]
+include::./how-the-agent-works.asciidoc[How the Agent works]
 include::./run-tests-locally.asciidoc[Run Tests Locally]
-include::./logging.asciidoc[Logging Integrations]
+

docs/api.asciidoc

@@ -1,5 +1,5 @@
 [[api]]
-== Public API
+== API reference
 
 The Elastic APM Python agent has several public APIs.
 Most of the public API functionality is not needed when using one of our <<framework-support, supported frameworks>>,

docs/configuration.asciidoc

@@ -135,11 +135,11 @@ Note however that this can have adverse effects on performance.
 The name of the environment this service is deployed in,
 e.g. "production" or "staging".
 
-Environments allow you to easily filter data on a global level in the APM UI.
+Environments allow you to easily filter data on a global level in the APM app.
 It's important to be consistent when naming environments across agents.
-See {kibana-ref}/filters.html#environment-selector[environment selector] in the Kibana UI for more information.
+See {apm-app-ref}/filters.html#environment-selector[environment selector] in the APM app for more information.
 
-NOTE: This feature is fully supported in the APM UI in Kibana versions >= 7.2.
+NOTE: This feature is fully supported in the APM app in Kibana versions >= 7.2.
 You must use the query bar to filter for a specific environment in versions prior to 7.2.
 
 [float]
@@ -678,7 +678,7 @@ NOTE: This feature requires APM Server and Kibana >= 7.3.
 
 When enabled, the agent will make periodic requests to the APM Server to fetch updated configuration.
 
-See {kibana-ref}/agent-configuration.html#agent-configuration[APM Agent Configuration] for more documentation on central agent configuration.
+See {apm-app-ref}/agent-configuration.html#agent-configuration[APM Agent Configuration] for more documentation on central agent configuration.
 
 NOTE: This feature requires APM Server and Kibana >= 7.3.
 

docs/django.asciidoc

@@ -1,11 +1,11 @@
 [[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.
 
 [float]
 [[django-installation]]
-=== Installation
+==== Installation
 
 Install the Elastic APM agent using pip:
 
@@ -25,7 +25,7 @@ threads].
 
 [float]
 [[django-setup]]
-=== Setup
+==== Setup
 
 Set up the Elastic APM agent in Django with these two steps:
 
@@ -77,7 +77,7 @@ ELASTIC_APM = {
 
 [float]
 [[django-performance-metrics]]
-=== Performance Metrics
+==== Performance metrics
 
 In order to collect performance metrics,
 the agent automatically inserts a middleware at the top of your middleware list
@@ -95,14 +95,14 @@ You can find more information on what we instrument in the <<automatic-instrumen
 
 [float]
 [[django-instrumenting-custom-python-code]]
-==== Instrumenting custom Python code
+===== Instrumenting custom Python code
 
 To gain further insights into the performance of your code, please see
 <<instrumenting-custom-code, instrumenting custom code>>.
 
 [float]
 [[django-ignoring-specific-views]]
-==== Ignoring specific views
+===== Ignoring specific views
 
 You can use the `TRANSACTIONS_IGNORE_PATTERNS` configuration option to ignore specific views.
 The list given should be a list of regular expressions which are matched against the transaction name as seen in the Elastic APM user interface:
@@ -116,7 +116,7 @@ This example ignores any requests using the `OPTIONS` method and any requests co
 
 [float]
 [[django-transaction-name-route]]
-==== Using the route as transaction name
+===== Using the route as transaction name
 
 By default, we use the function or class name of the view as the transaction name.
 Starting with Django 2.2, Django makes the route (e.g. `users/<int:user_id>/`) available on the `request.resolver_match` object.
@@ -131,7 +131,7 @@ NOTE: in versions previous to Django 2.2, changing this setting will have no eff
 
 [float]
 [[django-integrating-with-the-rum-agent]]
-==== Integrating with the RUM agent
+===== Integrating with the RUM Agent
 
 To correlate performance measurement in the browser with measurements in your Django app,
 you can help the RUM (Real User Monitoring) agent by configuring it with the Trace ID and Span ID of the backend request.
@@ -173,7 +173,7 @@ See the {apm-rum-ref}[JavaScript RUM agent documentation] for more information.
 
 [float]
 [[django-enabling-and-disabling-the-agent]]
-=== Enabling and disabling the agent
+==== Enabling and disabling the agent
 
 The easiest way to disable the agent is to set Django’s `DEBUG` option to `True` in your development configuration.
 No errors or metrics will be logged to Elastic APM.
@@ -191,7 +191,7 @@ ELASTIC_APM = {
 
 [float]
 [[django-logging]]
-=== Integrating with Python logging
+==== Integrating with Python logging
 
 To easily send Python `logging` messages as "error" objects to Elasticsearch,
 we provide a `LoggingHandler` which you can use in your logging setup.
@@ -270,7 +270,7 @@ Without it, only the message is sent.
 
 [float]
 [[django-extra-data]]
-==== Extra data
+===== Extra data
 
 If you want to send more data  than what you get with the agent by default, logging can be done like so:
 
@@ -293,7 +293,7 @@ except MyModel.DoesNotExist:
 
 [float]
 [[django-celery-integration]]
-=== Celery Integration
+==== Celery integration
 
 For a general guide on how to set up Django with Celery, head over to
 Celery's http://celery.readthedocs.org/en/latest/django/first-steps-with-django.html#django-first-steps[Django
@@ -303,7 +303,7 @@ Elastic APM will automatically log errors from your celery tasks, and record per
 
 [float]
 [[django-logging-http-404-not-found-errors]]
-=== Logging "HTTP 404 Not Found" Errors
+==== Logging "HTTP 404 Not Found" errors
 
 By default, Elastic APM does not log HTTP 404 errors. If you wish to log
 these errors, add
@@ -325,7 +325,7 @@ setting.
 
 [float]
 [[django-disable-agent-during-tests]]
-=== Disable the agent during tests
+==== Disable the agent during tests
 
 To prevent the agent from sending any data to the APM Server during tests, set the `ELASTIC_APM_DISABLE_SEND` environment variable to `true`, e.g.:
 
@@ -336,7 +336,7 @@ ELASTIC_APM_DISABLE_SEND=true python manage.py test
 
 [float]
 [[django-troubleshooting]]
-=== Troubleshooting
+==== Troubleshooting
 
 Elastic APM comes with a Django command that helps troubleshooting your setup. To check your configuration, run
 
@@ -369,6 +369,6 @@ Success! We tracked the error successfully! You should be able to see it in a fe
 
 [float]
 [[supported-django-and-python-versions]]
-=== 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.  

docs/flask.asciidoc

@@ -1,12 +1,12 @@
 [[flask-support]]
-== Flask support
+=== Flask support
 
 Getting Elastic APM set up for your Flask project is easy,
 and there are various ways you can tweak it to fit to your needs.
 
 [float]
 [[flask-installation]]
-=== Installation
+==== Installation
 
 Install the Elastic APM agent using pip:
 
@@ -25,7 +25,7 @@ threads].
 
 [float]
 [[flask-setup]]
-=== Setup
+==== Setup
 
 To set up the agent, you need to initialize it with appropriate settings.
 
@@ -69,7 +69,7 @@ apm = ElasticAPM(app, service_name='<APP-ID>', secret_token='<SECRET-TOKEN>')
 
 [float]
 [[flask-debug-mode]]
-==== Debug Mode
+===== Debug mode
 
 Please note that errors and transactions will only be sent to the APM Server if your app is *not* in
 http://flask.pocoo.org/docs/0.12/quickstart/#debug-mode[debug mode].
@@ -88,7 +88,7 @@ app.config['ELASTIC_APM'] = {
 
 [float]
 [[flask-building-applications-on-the-fly]]
-==== Building applications on the fly?
+===== Building applications on the fly?
 
 You can use the agent's `init_app` hook for adding the application on the fly:
 
@@ -105,7 +105,7 @@ def create_app():
 
 [float]
 [[flask-usage]]
-=== Usage
+==== Usage
 
 Once you have configured the agent,
 it will automatically track transactions and capture uncaught exceptions within Flask.
@@ -132,7 +132,7 @@ apm.capture_message('hello, world!')
 
 [float]
 [[flask-logging]]
-=== Logging
+==== Logging
 
 Passing `logging=LEVEL` to the ElasticAPM constructor will make the agent automatically log all log messages from Python's built-in `logging` module,
 with the given level or higher.
@@ -198,7 +198,7 @@ Without it, only the message is sent.
 
 [float]
 [[flask-extra-data]]
-==== Extra data
+===== Extra data
 
 In addition to what the agents log by default, you can send extra information:
 
@@ -220,20 +220,20 @@ def bar():
 
 [float]
 [[flask-celery-tasks]]
-==== Celery tasks
+===== Celery tasks
 
 The Elastic APM agent will automatically send errors and performance data from your Celery tasks to the APM Server.
 
 [float]
 [[flask-performance-metrics]]
-=== Performance Metrics
+==== Performance metrics
 
 If you've followed the instructions above, the agent has already hooked
 into the right signals and should be reporting performance metrics.
 
 [float]
 [[flask-ignoring-specific-views]]
-==== Ignoring specific routes
+===== Ignoring specific routes
 
 You can use the `TRANSACTIONS_IGNORE_PATTERNS` configuration option to ignore specific routes.
 The list given should be a list of regular expressions which are matched against the transaction name:
@@ -253,7 +253,7 @@ and any requests containing `/api/`.
 
 [float]
 [[flask-integrating-with-the-rum-agent]]
-==== Integrating with the RUM agent
+===== Integrating with the RUM Agent
 
 To correlate performance measurement in the browser with measurements in your Flask app,
 you can help the RUM (Real User Monitoring) agent by configuring it with the Trace ID and Span ID of the backend request.
@@ -277,6 +277,6 @@ See the {apm-rum-ref}[JavaScript RUM agent documentation] for more information.
 
 [float]
 [[supported-flask-and-python-versions]]
-=== 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.  

docs/getting-started.asciidoc

@@ -1,30 +1,31 @@
 [[getting-started]]
+== Introduction
 
-ifdef::env-github[]
-NOTE: For the best reading experience,
-please view this documentation at https://www.elastic.co/guide/en/apm/agent/python/current/getting-started.html[elastic.co]
-endif::[]
+The Elastic APM Python agent sends performance metrics and error logs to the APM Server.
+It has built-in support for Django and Flask performance metrics and error logging, as well as generic support of other WSGI frameworks for error logging.
+
+[float]
+[[how-it-works]]
+=== How does the Agent work?
 
-== Getting started
+The Python Agent instruments your application to collect APM events in a few different ways:
 
-Welcome to the APM Python agent docs.
+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.
 
-The Elastic APM Python agent sends performance metrics and error logs to the APM Server.
-It has built-in support for Django and Flask performance metrics and error logging, as well as generic support of other WSGI frameworks for error logging.
+To collect data from database drivers, HTTP libraries etc.,
+we instrument certain functions and methods in these libraries.
+Instrumentations are set up automatically and do not require any code changes.
+
+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>>.
 
 [float]
 [[additional-components]]
-=== Additional Components
+=== Additional components
 
 APM Agents work in conjunction with the {apm-server-ref-v}/index.html[APM Server], {ref}/index.html[Elasticsearch], and {kibana-ref}/index.html[Kibana].
 Please view the {apm-overview-ref-v}/index.html[APM Overview] for details on how these components work together.
-
-[[framework-support]]
-The Elastic APM Python Agent comes with support for the following frameworks:
-
- * <<django-support,Django>> 1.8 - 2.1
- * <<flask-support,Flask>> 0.10+
- 
-For other frameworks and custom Python code, the agent exposes a set of <<api,APIs>> for integration.
-
-NOTE: The Elastic APM Python agent does currently not support asynchronous frameworks like Twisted or Tornado.