Merge branch 'main' into trangl-o11ydocs-6385-muting-rules-react

Author: trangl-splunk

_images/collector/imagetest.png

@@ -21,6 +21,8 @@ Instrument Python applications for Splunk Observability Cloud
    Troubleshoot the Python instrumentation <troubleshooting/common-python-troubleshooting>
    About Splunk OTel Python <splunk-python-otel-distribution>
    Migrate from SignalFx Python agent <troubleshooting/migrate-signalfx-python-agent-to-otel>
+   Migrate to Splunk Python 2.X <migration-guide>
+   Version 1.X (deprecated) <version1x/get-started-1x>
 
 The Splunk Distribution of OpenTelemetry Python provides a Python agent that automatically adds APM instrumentation to your Python application. The instrumentation captures distributed traces and metrics and sends them to Splunk Observability Cloud.
 

gdi/get-data-in/application/python/get-started.rst

@@ -74,9 +74,9 @@ Follow these steps to automatically instrument your application using the Python
 
    .. code-block:: bash
 
-      splunk-py-trace-bootstrap
+      opentelemetry-bootstrap
 
-   To print the instrumentation packages to the console instead of installing them, run ``splunk-py-trace-bootstrap --action=requirements``. You can then add the output to your requirements or Pipfile.
+   To print the instrumentation packages to the console instead of installing them, run ``opentelemetry-bootstrap --action=requirements``. You can then add the output to your requirements or Pipfile.
 
 #. Set the ``OTEL_SERVICE_NAME`` environment variable:
 
@@ -122,11 +122,11 @@ Follow these steps to automatically instrument your application using the Python
 
          python3 main.py --port=8000
 
-   prefix the command with ``splunk-py-trace``:
+   prefix the command with ``opentelemetry-instrument``:
 
       .. code-block:: bash
 
-         splunk-py-trace python3 main.py --port=8000
+         opentelemetry-instrument python3 main.py --port=8000
 
    .. note:: To instrument uWSGI applications, see :ref:`python-manual-instrumentation`.
 

gdi/get-data-in/application/python/instrumentation/instrument-python-application.rst

@@ -23,12 +23,12 @@ For example, if your manage.py file sets the environment variable to mydjangopro
    .. code-tab:: bash Linux
 
          export DJANGO_SETTINGS_MODULE=mydjangoproject.settings
-         splunk-py-trace python3 ./manage.py runserver --noreload
+         opentelemetry-instrument python3 ./manage.py runserver --noreload
 
    .. code-tab:: shell Windows PowerShell
 
          $env:DJANGO_SETTINGS_MODULE=mydjangoproject.settings
-         splunk-py-trace python3 ./manage.py runserver --noreload
+         opentelemetry-instrument python3 ./manage.py runserver --noreload
 
 .. _uwsgi-instrumentation:
 
@@ -40,11 +40,11 @@ When using uWSGI, you must configure tracing as a response to the ``post_fork``
 .. code-block:: python
 
    import uwsgidecorators
-   from splunk_otel.tracing import start_tracing
+   from splunk_otel import init_splunk_otel
 
    @uwsgidecorators.postfork
-   def setup_tracing():
-      start_tracing()
+   def start_otel():
+      init_splunk_otel()
 
 Customize and use the following snippet to run the application:
 
@@ -65,15 +65,15 @@ When using both uSWGI and Flask, calling ``start_tracing()`` only autoinstrument
 
    # app.py
    import uwsgidecorators
-   from splunk_otel.tracing import start_tracing
+   from splunk_otel import init_splunk_otel
    from opentelemetry.instrumentation.flask import FlaskInstrumentor
    from flask import Flask
 
    app = Flask(__name__)
 
    @uwsgidecorators.postfork
-   def setup_tracing():
-      start_tracing()
+   def setup_otel():
+      init_splunk_otel()
       # Instrument the Flask app instance explicitly
       FlaskInstrumentor().instrument_app(app)
 

gdi/get-data-in/application/python/instrumentation/instrument-python-frameworks.rst

@@ -14,13 +14,13 @@ Instrumenting applications automatically using the agent of the Splunk Distribut
 Start tracing using code
 ===============================
 
-If you can't use the ``splunk-py-trace`` command to launch the application, you can instead import and configure ``start_tracing`` by adding the following snippet to your application code: 
+If you can't use the ``opentelemetry-instrument`` command to launch the application, you can instead import and configure ``start_otel`` by adding the following snippet to your application code: 
 
    .. code:: python
 
-      from splunk_otel.tracing import start_tracing
+      from splunk_otel.tracing import start_otel
 
-      start_tracing()
+      start_otel()
 
       # Also accepts optional settings. For example:
       #

gdi/get-data-in/application/python/instrumentation/python-manual-instrumentation.rst

@@ -0,0 +1,89 @@
+.. _python-migration-guide:
+
+*************************************************************
+Migrate to the Splunk Python 2.0 instrumentation
+*************************************************************
+
+.. meta:: 
+    :description: Learn how to migrate from the Splunk OpenTelemetry Python 1.X instrumentation to the Python 2.0 instrumentation.
+
+OpenTelemetry Python instrumentation 2.0 contains a set of breaking changes introduced with the OpenTelemetry semantic conventions updates. 
+
+This migration guide assumes that you're using a 1.x version of the Splunk Distribution of OpenTelemetry Python.
+
+.. _python-2.x-migration-prereqs:
+
+Prerequisites
+====================================
+
+To migrate to the Splunk Distribution of OpenTelemetry Python version 2.0, you need the following:
+
+* Splunk Distribution of OpenTelemetry Collector version 0.98 or higher deployed.
+* Administrator permissions for Splunk Observability Cloud.
+* pip version 3.0 or higher.
+
+.. _migrate-python-2.x-steps:
+
+Migrate to Splunk OTel Python 2.0
+=====================================
+
+Upgrading to Splunk OTel Python 2.0 requires upgrading the Splunk Distribution of OpenTelemetry Collector. 
+
+To upgrade to Splunk OTel Python 2.0, follow these steps:
+
+#. Open a terminal.
+#. Enter the following command:
+
+    .. code-block:: bash
+
+        pip install --upgrade splunk-opentelemetry
+
+#. Restart any running Python applications that you plan to instrument.
+
+.. _python-2.x-new-instrumentation:
+
+Instrumentation parameters for Python 2.0
+====================================================
+
+Splunk OpenTelemetry Python version 2.0 changes the parameters for zero-code instrumentation.
+
+See the following table for a list of changes:
+
+.. list-table:: 
+    :header-rows: 1
+
+    * - Version 1.x name
+      - Version 2.0 name
+      - Description
+    * - `splunk-py-trace`, `splk-py-trace`
+      - `opentelemetry-instrument`
+      - Activates the Splunk OpenTelemetry Python agent and sends traces and metrics to Splunk Observability Cloud. 
+    * - `splunk-py-trace-bootstrap`, `splk-py-trace-bootstrap`
+      - `opentelemetry-bootstrap`
+      - Installs instrumentation libraries and dependencies for Splunk OpenTelemetry Python.
+
+.. _python-2.x-new-functions:
+
+Function names for Python 2.0
+====================================
+
+Functions configure certain telemetry data settings in your Python application code.
+
+See the following table for new function names in Python 2.0:
+
+.. list-table:: 
+    :header-rows: 1
+
+    * - Version 1.x name
+      - Version 2.0 name
+      - Description
+    * - `start_tracing()`, `start_metrics()`
+      - `init_splunk_otel()`
+      - Configures tracing, metrics, and logs for Splunk OpenTelemetry Python.
+
+.. _python-2.x-troubleshooting:
+
+Troubleshooting
+====================================
+
+.. include:: /_includes/troubleshooting-components.rst

gdi/get-data-in/application/python/migration-guide.rst

@@ -0,0 +1,166 @@
+.. _advanced-python-otel-configuration-1x:
+
+********************************************************************
+Configure the Python agent for Splunk Observability Cloud
+********************************************************************
+
+.. meta:: 
+   :description: Configure the agent of the Splunk Distribution of OpenTelemetry Python to suit most of your instrumentation needs, like correlating traces with logs, activating exporters, and more.
+
+You can configure the Python agent from the Splunk Distribution of OpenTelemetry Python to suit your instrumentation needs. In most cases, modifying the basic configuration is enough to get started.
+
+The following sections describe all available settings for configuring the Python agent, including options for activating new features that are unique to the Splunk Distribution of OpenTelemetry Python.
+
+.. _main-python-agent-settings-1x:
+
+General settings
+=========================================================================
+
+The following settings are specific to the Splunk Distribution of OpenTelemetry Python:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Environment variable
+     - Description
+   * - ``SPLUNK_ACCESS_TOKEN``
+     - A Splunk authentication token that lets exporters send data directly to Splunk Observability Cloud. Unset by default. Not required unless you need to send data to the Splunk Observability Cloud ingest endpoint. See :ref:`admin-tokens`.
+   * - ``SPLUNK_TRACE_RESPONSE_HEADER_ENABLED``
+     - Activates the addition of server trace information to HTTP response headers. For more information, see :ref:`server-trace-information-python`. The default value is ``true``.
+   * - ``OTEL_METRICS_ENABLED``
+     - Activates application metrics collection. The default value is ``true``. See :ref:`python-otel-metrics` for more information.
+
+.. _trace-configuration-python-1x:
+
+Trace configuration
+=======================================================
+
+The following settings control tracing limits and attributes:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Environment variable
+     - Description
+   * - ``OTEL_TRACE_ENABLED``
+     - Activates tracer creation and autoinstrumentation. The default value is ``true``.
+   * - ``OTEL_SERVICE_NAME``
+     - Name of the service or application you're instrumenting. Takes precedence over the service name defined in the ``OTEL_RESOURCE_ATTRIBUTES`` variable.
+   * - ``OTEL_RESOURCE_ATTRIBUTES``
+     - Comma-separated list of resource attributes added to every reported span. For example, ``key1=val1,key2=val2``.
+   * - ``OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT``
+     - Maximum number of attributes per span. The default value is unlimited.
+   * - ``OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT``
+     - Maximum number of attributes per event. The default value is unlimited.
+   * - ``OTEL_LINK_ATTRIBUTE_COUNT_LIMIT``
+     - Maximum number of attributes per link. The default value is unlimited.
+   * - ``OTEL_SPAN_EVENT_COUNT_LIMIT``
+     - Maximum number of events per span. The default value is unlimited.
+   * - ``OTEL_SPAN_LINK_COUNT_LIMIT``
+     - Maximum number of links per span. The default value is ``1000``.
+   * - ``OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT``
+     - Maximum length of strings for attribute values. Values larger than the limit are truncated. The default value is ``1200``.
+
+.. _trace-exporters-settings-python-1x:
+
+Exporters configuration
+===============================================================
+
+The following settings control trace exporters and their endpoints:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Environment variable
+     - Description
+   * - ``OTEL_TRACES_EXPORTER``
+     - Trace exporter to use. You can set multiple comma-separated values (for example, ``otlp,console``). The default value is ``otlp``.
+   * - ``OTEL_METRICS_EXPORTER``
+     - The metrics exporter to use. The default value is ``otlp``. Accepted values are ``otlp`` and ``none``. Setting ``none`` deactivates metric exports.
+   * - ``OTEL_METRIC_EXPORT_INTERVAL``
+     - Interval, in milliseconds, between the start of two export attempts. The default value is ``60000``.
+   * - ``OTEL_METRIC_EXPORT_TIMEOUT``
+     - Maximum allowed time to export data, in milliseconds. The default value is ``30000``.
+   * - ``OTEL_EXPORTER_OTLP_ENDPOINT``
+     - The OTLP endpoint. The default value is ``http://localhost:4317``.
+   * - ``OTEL_EXPORTER_OTLP_METRICS_ENDPOINT``
+     - The OTLP endpoint. The default value is ``http://localhost:4317``.
+
+To send data directly to Splunk Observability Cloud bypassing the Collector, see :ref:`export-directly-to-olly-cloud-python`.
+
+.. _trace-propagation-configuration-python-1x:
+
+Propagators configuration
+=======================================================
+
+The following settings control trace propagation:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Environment variable
+     - Description
+   * - ``OTEL_PROPAGATORS``
+     - Comma-separated list of propagators you want to use. The default value is ``tracecontext,baggage``. You can find the list of supported propagators in the OpenTelemetry documentation.
+
+For backward compatibility with the SignalFx Python Tracing Library, use the b3multi trace propagator:
+
+.. tabs::
+
+   .. code-tab:: shell Linux
+
+      export OTEL_PROPAGATORS=b3multi
+
+   .. code-tab:: shell Windows PowerShell
+
+      $env:OTEL_PROPAGATORS=b3multi
+
+.. _profiling-configuration-python-1x:
+
+Python settings for AlwaysOn Profiling
+====================================================
+
+.. note:: Only CPU profiling is supported.
+
+The following settings control the AlwaysOn Profiling feature for the Python agent:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40, 60
+
+   * - Environment variable
+     - Description
+   * - ``SPLUNK_PROFILER_ENABLED``
+     - Activates AlwaysOn Profiling. The default value is ``false``. 
+   * - ``SPLUNK_PROFILER_LOGS_ENDPOINT``
+     - The collector endpoint for profiler logs. By default, it takes the value of ``http://localhost:4317``.
+   * - ``SPLUNK_PROFILER_CALL_STACK_INTERVAL``
+     - The frequency of call stack sampling, in milliseconds. The default value is ``1000``.
+   * - ``SPLUNK_PROFILER_INCLUDE_INTERNAL_STACKS``
+     - Determines whether to include stack traces from internal profiler threads. The default value is ``false``.
+
+.. _server-trace-information-python-1x:
+
+Server trace information
+==============================================
+
+To connect Real User Monitoring (RUM) requests from mobile and web applications with server trace data, trace response headers are activated by default. The instrumentation adds the following response headers to HTTP responses:
+
+.. code-block::
+
+   Access-Control-Expose-Headers: Server-Timing
+   Server-Timing: traceparent;desc="00-<serverTraceId>-<serverSpanId>-01"
+
+The ``Server-Timing`` header contains the ``traceId`` and ``spanId`` parameters in ``traceparent`` format. For more information, see the Server-Timing and traceparent documentation on the W3C website.
+
+.. note:: If you need to deactivate trace response headers, set ``SPLUNK_TRACE_RESPONSE_HEADER_ENABLED`` to ``false``.
+
+.. _code-configuration-python-1x:
+
+Configure the Python agent in your code
+====================================================
+
+If you can't set environment variables or can't use ``splunk-py-trace`` for setting configuration values at runtime, define the configuration settings in your code.
+
+See :ref:`python-manual-instrumentation` for more information.
+

gdi/get-data-in/application/python/version1x/advanced-python-otel-configuration-1x.rst

@@ -0,0 +1,28 @@
+.. _get-started-python-1x:
+
+**************************************************************
+Instrument Python applications for Splunk Observability Cloud
+**************************************************************
+
+
+.. meta::
+   :description: Instrument Python applications automatically to export spans and metrics to Splunk Observability Cloud.
+
+.. toctree::
+   :hidden:
+
+   Instrument your Python application <instrument-python-application-1x>
+   Configure the Python agent <advanced-python-otel-configuration-1x>
+   Metrics and attributes <python-otel-metrics-1x>
+
+The Splunk Distribution of OpenTelemetry Python provides a Python agent that automatically adds APM instrumentation to your Python application. The instrumentation captures distributed traces and metrics and sends them to Splunk Observability Cloud.
+
+To instrument your Python application, follow these steps:
+
+#. Check compatibility and requirements. See :ref:`python-otel-requirements`.
+#. Instrument your Python application. See :ref:`instrument-python-applications-1x`.
+#. Configure your instrumentation. See :ref:`configure-python-instrumentation-1x`.
+
+For more information, see :ref:`splunk-python-otel-dist`.
+
+.. note:: The SignalFx Python Agent is deprecated and will reach End of Support on December 17th, 2022. See :ref:`migrate-signalfx-python-agent-to-otel` to migrate to the Splunk Distribution of OpenTelemetry Python.