chore(docs): consolidate environment variable configuration (#1320)

* docs: consolidate environment variable configuration

* Update docs/configuration.rst

Co-Authored-By: Kyle Verhoog <[email protected]>

* remove env vars from usage

Co-authored-by: Kyle Verhoog <[email protected]>

Author: majorgreys

ddtrace/commands/ddtrace_run.py

@@ -17,21 +17,10 @@
 
 USAGE = """
 Execute the given Python program after configuring it to emit Datadog traces.
-Append command line arguments to your program as usual.
-
-Usage: [ENV_VARS] ddtrace-run <my_program>
 
-Available environment variables:
+Append command line arguments to your program as usual.
 
-    DATADOG_ENV : override an application's environment (no default)
-    DATADOG_TRACE_ENABLED=true|false : override the value of tracer.enabled (default: true)
-    DATADOG_TRACE_DEBUG=true|false : enabled debug logging (default: false)
-    DATADOG_PATCH_MODULES=module:patch,module:patch... e.g. boto:true,redis:false : override the modules patched for this execution of the program (default: none)
-    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: enables Priority Sampling. (default: false)
-    DD_LOGS_INJECTION=true|false: enable injecting trace information into log records to correlate. (default: false)
+Usage: ddtrace-run <my_program>
 """  # noqa: E501
 
 

docs/advanced_usage.rst

@@ -552,35 +552,11 @@ and database modules without the need for changing your code::
 
   Append command line arguments to your program as usual.
 
-  Usage: [ENV_VARS] ddtrace-run <my_program>
-
-
-The available environment variables for ``ddtrace-run`` are:
-
-* ``DATADOG_TRACE_ENABLED=true|false`` (default: true): Enable web framework and
-  library instrumentation. When false, your application code will not generate
-  any traces.
-* ``DATADOG_ENV`` (no default): Set an application's environment e.g. ``prod``,
-  ``pre-prod``, ``stage``
-* ``DD_ENV`` (no default): Set an application's environment e.g. ``prod``,
-  ``pre-prod``, ``stage`` (preferred over ``DATADOG_ENV``)
-* ``DD_VERSION`` (no default): Set an application's version e.g. ``1.2.3``, ``6c44da20``, ``2020.02.13``
-* ``DATADOG_TRACE_DEBUG=true|false`` (default: false): Enable debug logging in
-  the tracer
-* ``DD_SERVICE`` (no default): override the service name to be used for this
-  application. A default is provided for the bottle, flask, grpc, pyramid,
-  pylons, tornado, celery, django and falcon integrations.
-* ``DATADOG_PATCH_MODULES=module:patch,module:patch...`` e.g.
-  ``boto:true,redis:false``: override the modules patched for this execution of
-  the program (default: none)
-* ``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)
-* ``DATADOG_PRIORITY_SAMPLING`` (default: true): enables :ref:`Priority
-  Sampling`
-* ``DD_LOGS_INJECTION`` (default: false): enables :ref:`Logs Injection`
+  Usage: ddtrace-run <my_program>
+
+
+The environment variables for ``ddtrace-run`` used to configure the tracer are
+detailed in :ref:`Configuration`.
 
 ``ddtrace-run`` respects a variety of common entrypoints for web applications:
 

docs/configuration.rst

@@ -15,16 +15,67 @@ below:
      - Type
      - Default value
      - Description
-   * - ``DD_SERVICE_NAME`` or ``DATADOG_SERVICE_NAME``
+   * - ``DD_ENV``
+     - String
+     -
+     - Set an application's environment e.g. ``prod``, ``pre-prod``, ``stage``.
+   * - ``DATADOG_ENV``
+     - String
+     -
+     - Deprecated: use ``DD_ENV``
+   * - ``DD_SERVICE``
      - String
      - (autodetected)
-     - The service name to use.
+     - Set the service name to be used for this application. A default is
+       provided for these integrations: :ref:`bottle`, :ref:`flask`, :ref:`grpc`,
+       :ref:`pyramid`, :ref:`pylons`, :ref:`tornado`, :ref:`celery`, :ref:`django` and
+       :ref:`falcon`.
+   * - ``DD_SERVICE_NAME`` or ``DATADOG_SERVICE_NAME``
+     - String
+     -
+     - Deprecated: use ``DD_SERVICE``.
+   * - ``DD_VERSION``
+     - String
+     -
+     - Set an application's version in traces and logs e.g. ``1.2.3``,
+       ``6c44da20``, ``2020.02.13``.
+   * - ``DATADOG_TRACE_ENABLED``
+     - Boolean
+     - True
+     - Enable web framework and library instrumentation. When false, your
+       application code will not generate any traces.
+   * - ``DATADOG_TRACE_DEBUG``
+     - Boolean
+     - False
+     - Enable debug logging in the tracer
+   * - ``DATADOG_PATCH_MODULES``
+     - String
+     -
+     - Override the modules patched for this execution of the program. Must be
+       a list in the ``module1:boolean,module2:boolean`` format. For example,
+       ``boto:true,redis:false``.
+   * - ``DATADOG_PRIORITY_SAMPLING``
+     - Boolean
+     - True
+     - Enables :ref:`Priority Sampling`.
+   * - ``DD_LOGS_INJECTION``
+     - Boolean
+     - True
+     - Enables :ref:`Logs Injection`.
    * - ``DD_TRACE_AGENT_URL``
      - URL
      - ``http://localhost:8126``
      - The URL to use to connect the Datadog agent. The url can starts with
        ``http://`` to connect using HTTP or with ``unix://`` to use a Unix
        Domain Socket.
+   * - ``DATADOG_TRACE_AGENT_HOSTNAME``
+     - String
+     -
+     - Deprecated: use ``DD_TRACE_AGENT_URL``
+   * - ``DATADOG_TRACE_AGENT_PORT``
+     - Integer
+     -
+     - Deprecated: use ``DD_TRACE_AGENT_URL``
    * - ``DD_PROFILING_API_TIMEOUT``
      - Float
      - 10
@@ -68,5 +119,5 @@ below:
    * - ``DD_PROFILING_TAGS``
      - String
      -
-     - The tags to apply to uploaded profile. Must be a list of in the
+     - The tags to apply to uploaded profile. Must be a list in the
        ``key1:value,key2:value2`` format.