logging: update documentation (#1318)

Author: Kyle-Verhoog

ddtrace/commands/ddtrace_run.py

@@ -30,7 +30,8 @@
     DATADOG_TRACE_AGENT_HOSTNAME=localhost: override the address of the trace agent host that the default tracer will attempt to submit to  (default: localhost)
     DATADOG_TRACE_AGENT_PORT=8126: override the port that the default tracer will submit to (default: 8126)
     DD_SERVICE: the service name to be used for this program (default only for select web frameworks)
-    DATADOG_PRIORITY_SAMPLING=true|false: (default: false): enables Priority Sampling.
+    DATADOG_PRIORITY_SAMPLING=true|false: enables Priority Sampling. (default: false)
+    DD_LOGS_INJECTION=true|false: enable injecting trace information into log records to correlate. (default: false)
 """  # noqa: E501
 
 

ddtrace/contrib/logging/__init__.py

@@ -1,13 +1,18 @@
 """
-Datadog APM traces can be integrated with Logs by first having the tracing
-library patch the standard library ``logging`` module and updating the log
-formatter used by an application. This feature enables you to inject the current
-trace information into a log entry.
+Datadog APM traces can be integrated with Logs by:
+
+1. Having ``ddtrace`` patch the ``logging`` module. This will add trace
+attributes to the log record.
+
+2. Updating the log formatter used by the application. In order to inject
+tracing information into a log the formatter must be updated to include the
+tracing attributes from the log record. ``ddtrace-run`` will do this
+automatically for you by specifying a format. For more detail or instructions
+for how to do this manually see the manual section below.
+
+With these in place the trace information will be injected into a log entry
+which can be used to correlate the log and trace in Datadog.
 
-Before the trace information can be injected into logs, the formatter has to be
-updated to include ``dd.trace_id`` and ``dd.span_id`` attributes from the log
-record. The integration with Logs occurs as long as the log entry includes
-``dd.trace_id=%(dd.trace_id)s`` and ``dd.span_id=%(dd.span_id)s``.
 
 ddtrace-run
 -----------
@@ -33,14 +38,18 @@ def hello():
 ----------------------
 
 If you prefer to instrument manually, patch the logging library then update the
-log formatter as in the following example::
+log formatter as in the following example
+
+Note that ``dd.trace_id`` and ``dd.span_id`` must come last::
 
     from ddtrace import patch_all; patch_all(logging=True)
     import logging
     from ddtrace import tracer
 
     FORMAT = ('%(asctime)s %(levelname)s [%(name)s] [%(filename)s:%(lineno)d] '
-              '[dd.trace_id=%(dd.trace_id)s dd.span_id=%(dd.span_id)s] '
+              '[dd.service=%(dd.service)s dd.env=%(dd.env)s '
+              'dd.version=%(dd.version)s] '
+              'dd.trace_id=%(dd.trace_id)s dd.span_id=%(dd.span_id)s]'
               '- %(message)s')
     logging.basicConfig(format=FORMAT)
     log = logging.getLogger()