[requests] update documentation using the configuration API

Author: Emanuele Palazzetti

ddtrace/contrib/requests/__init__.py

@@ -1,29 +1,33 @@
 """
-To trace all HTTP calls from the requests library, patch the library like so::
+The ``requests`` integration traces all HTTP calls to internal or external services.
+Auto instrumentation is available using the ``patch`` function that **must be called
+before** importing the ``requests`` library. The following is an example::
 
-    # Patch the requests library.
-    from ddtrace.contrib.requests import patch
-    patch()
+    from ddtrace import patch
+    patch(requests=True)
 
     import requests
-    requests.get("http://www.datadog.com")
+    requests.get("https://www.datadoghq.com")
 
-If you would prefer finer grained control without monkeypatching the requests'
-code, use a TracedSession object as you would a requests.Session::
+If you would prefer finer grained control, use a ``TracedSession`` object as you would a
+``requests.Session``::
 
     from ddtrace.contrib.requests import TracedSession
 
     session = TracedSession()
-    session.get("http://www.datadog.com")
+    session.get("https://www.datadoghq.com")
 
-To enable distributed tracing, for example if you call, from requests, a web service
-which is also instrumented and want to have traces including both client and server sides::
+The library can be configured globally and per instance, using the Configuration API::
 
-    from ddtrace.contrib.requests import TracedSession
+    from ddtrace import config
 
-    session = TracedSession()
-    session.distributed_tracing = True
-    session.get("http://host.lan/webservice")
+    # enable distributed tracing globally
+    config.requests['distributed_tracing'] = True
+
+    # change the service name only for this session
+    session = Session()
+    cfg = config.get_from(session)
+    cfg['service_name'] = 'auth-api'
 """
 from ...utils.importlib import require_modules