Merge branch 'master' into transaction-outcome

Author: beniwohli

.ci/.jenkins_framework.yml

@@ -28,7 +28,7 @@ FRAMEWORK:
   - elasticsearch-7
   - cassandra-newest
   - psutil-newest
-  - eventlet-newest
+  #- eventlet-newest
   - gevent-newest
   - zerorpc-0.4
   - mysql_connector-newest

.ci/.jenkins_framework_full.yml

@@ -54,7 +54,7 @@ FRAMEWORK:
   - psutil-newest
   - psutil-5.0
   - psutil-4.0
-  - eventlet-newest
+  #- eventlet-newest
   - elasticsearch-2
   - elasticsearch-5
   - elasticsearch-6

CONTRIBUTING.md

@@ -36,17 +36,17 @@ Once your changes are ready to submit for review:
 1. Code style
 
     This project uses several tools to maintain a consistent code style:
-    
+
      * the automatic code formatter [black](https://black.readthedocs.io/en/stable/)
      * sorting of imports via [isort](https://isort.readthedocs.io/en/latest/)
      * [flake8](http://flake8.pycqa.org/en/latest/)
      * License header check via custom script
-     
+
     The easiest way to make sure your pull request adheres to the the code style
     is to install [pre-commit](https://pre-commit.com/).
-    
+
         pip install pre-commit # or "brew install pre-commit" if you use Homebrew
-        
+
         pre-commit install
 
 1. Test your changes
@@ -87,6 +87,23 @@ you need to install several databases (Elasticsearch, PostgreSQL, MySQL, Cassand
 This can be quite a hassle, so we recommend to use our dockerized test setup.
 See [Running tests](https://www.elastic.co/guide/en/apm/agent/python/master/run-tests-locally.html) for detailed instructions.
 
+However, for running local unit tests, you can install the relevant
+[requirements files](https://github.com/elastic/apm-agent-python/tree/master/tests/requirements)
+and then run `py.test` from the project root.
+
+Pytest will automatically discover all the tests and skip the ones for which
+dependencies are not met.
+
+#### Pytest
+
+This project uses [pytest](https://docs.pytest.org/en/latest/) for all of its
+testing needs. Note that pytest can be a bit confusing at first, due to its
+dynamic discovery features. In particular,
+[fixtures](https://docs.pytest.org/en/stable/fixture.html) can be confusing
+and hard to discover, due to the fact that they do not need to be imported to
+be used. For example, whenever a test has `elasticapm_client` as an argument,
+that is a fixture which is defined
+[here](https://github.com/elastic/apm-agent-python/blob/ed4ce5fd5db3cc091a54d3328384fbce62635bbb/tests/fixtures.py#L150).
 
 ### Workflow
 

README.rst

@@ -23,10 +23,14 @@ WSGI-compatible web applications via `custom integrations`_.
 Your application doesn't live on the web? No problem! Elastic APM is easy to use in
 any Python application.
 
-Read the documentation_.
+Read the documentation_, including instructions on `running the tests locally`_.
+
+If you're interested in contributing, `start here!`_
 
 .. _documentation: https://www.elastic.co/guide/en/apm/agent/python/current/index.html
 .. _`custom integrations`: https://www.elastic.co/blog/creating-custom-framework-integrations-with-the-elastic-apm-python-agent
+.. _`running the tests locally`: https://www.elastic.co/guide/en/apm/agent/python/current/run-tests-locally.html
+.. _`start here!`: https://github.com/elastic/apm-agent-python/blob/master/CONTRIBUTING.md
 
 License
 -------

docs/logging.asciidoc

@@ -9,6 +9,19 @@ as well as http://www.structlog.org/en/stable/[`structlog`].
 * <<logging-integrations>>
 * <<log-correlation-in-es>>
 
+[float]
+[[ecs-logging]]
+=== `ecs-logging`
+
+The easiest way to integrate your logs with APM is to use the
+https://github.com/elastic/ecs-logging-python[`ecs-logging`] library, which
+is also provided by Elastic. This library provides formatters for both `logging`
+and `structlog` which create ECS-compatible logs and will include the tracing
+information required for log correlation in kibana. Coupled with something like
+https://www.elastic.co/beats/filebeat[Filebeat], it is the easiest way to get
+logs into Elasticsearch.
+
+
 [float]
 [[logging-integrations]]
 === Logging integrations

docs/run-tests-locally.asciidoc

@@ -58,6 +58,10 @@ $ ./tests/scripts/docker/run_tests.sh python-version framework-version <pip-cach
 NOTE: The `python-version` must be of format `python-version`, e.g. `python-3.6` or `pypy-2`.
 The `framework` must be of format `framework-version`, e.g. `django-1.10` or `flask-0.12`.
 
+You can also run the unit tests outside of docker, by installing the relevant
+https://github.com/elastic/apm-agent-python/tree/master/tests/requirements[requirements file]
+and then running `py.test` from the project root.
+
 ==== Integration testing
 
 Check out https://github.com/elastic/apm-integration-testing for resources for
@@ -68,5 +72,5 @@ checkout, you might do something like this:
 
 [source,bash]
 ----
-$ ./scripts/compose.py start 7.3 --with-agent-python-django --with-opbeans-python --opbeans-python-agent-local-repo=~/elastic/apm-agent-python

+$ ./scripts/compose.py start 7.3 --with-agent-python-django --with-opbeans-python --opbeans-python-agent-local-repo=~/elastic/apm-agent-python
 ----

docs/troubleshooting.asciidoc

@@ -7,6 +7,7 @@ python agent.
 * <<easy-fixes>>
 * <<django-test>>
 * <<agent-logging>>
+* <<disable-agent>>
 
 [float]
 [[easy-fixes]]
@@ -154,3 +155,18 @@ logger.addHandler(console_handler)
 See the https://docs.python.org/3/library/logging.html[python logging docs]
 for more details about Handlers (and information on how to format your logs
 using Formatters).
+
+[float]
+[[disable-agent]]
+=== Disable the Agent
+
+In the unlikely event the agent causes disruptions to a production application,
+you can disable the agent while you troubleshoot.
+
+If you have access to <<dynamic-configuration,dynamic configuration>>,
+you can disable the recording of events by setting <<config-recording,`recording`>> to `false`.
+When changed at runtime from a supported source, there's no need to restart your application.
+
+If that doesn't work, or you don't have access to dynamic configuration, you can disable the agent by setting
+<<config-enabled,`enabled`>> to `false`.
+You'll need to restart your application for the changes to take effect.