feat: Add Span Disabling.

The span disabling allows the exclusion of specific traces or calls from tracing based on the category (technology) or type (frameworks, libraries, instrumentations) supported by the traces.

This commit adds support to handle the configuration from the INSTANA_TRACING_DISABLE, INSTANA_CONFIG_PATH, and Agent-provided configuration.

Signed-off-by: Paulo Vital <[email protected]>

Author: pvital

src/instana/__init__.py

@@ -20,6 +20,7 @@
     is_autowrapt_instrumented,
     is_webhook_instrumented,
 )
+from instana.util.config import is_truthy
 from instana.version import VERSION
 
 __author__ = "Instana Inc."
@@ -225,7 +226,9 @@ def _start_profiler() -> None:
         profiler.start()
 
 
-if "INSTANA_DISABLE" not in os.environ:
+if "INSTANA_DISABLE" not in os.environ and not is_truthy(
+    os.environ.get("INSTANA_TRACING_DISABLE", None)
+):
     # There are cases when sys.argv may not be defined at load time.  Seems to happen in embedded Python,
     # and some Pipenv installs.  If this is the case, it's best effort.
     if (

src/instana/options.py

@@ -16,12 +16,20 @@
 
 import logging
 import os
-from typing import Any, Dict
+from typing import Any, Dict, Sequence
 
 from instana.configurator import config
 from instana.log import logger
-from instana.util.config import (is_truthy, parse_ignored_endpoints,
-                                 parse_ignored_endpoints_from_yaml)
+from instana.util.config import (
+    SPAN_TYPE_TO_CATEGORY,
+    get_disable_trace_configurations_from_env,
+    get_disable_trace_configurations_from_local,
+    get_disable_trace_configurations_from_yaml,
+    is_truthy,
+    parse_ignored_endpoints,
+    parse_ignored_endpoints_from_yaml,
+    parse_span_disabling,
+)
 from instana.util.runtime import determine_service_name
 
 
@@ -37,6 +45,11 @@ def __init__(self, **kwds: Dict[str, Any]) -> None:
         self.ignore_endpoints = []
         self.kafka_trace_correlation = True
 
+        # disabled_spans lists all categories and types that should be disabled
+        self.disabled_spans = []
+        # enabled_spans lists all categories and types that should be enabled, preceding disabled_spans
+        self.enabled_spans = []
+
         self.set_trace_configurations()
 
         # Defaults
@@ -75,8 +88,9 @@ def set_trace_configurations(self) -> None:
             )
 
         # Check if either of the environment variables is truthy
-        if is_truthy(os.environ.get("INSTANA_ALLOW_EXIT_AS_ROOT", None)) or \
-           is_truthy(os.environ.get("INSTANA_ALLOW_ROOT_EXIT_SPAN", None)):
+        if is_truthy(os.environ.get("INSTANA_ALLOW_EXIT_AS_ROOT", None)) or is_truthy(
+            os.environ.get("INSTANA_ALLOW_ROOT_EXIT_SPAN", None)
+        ):
             self.allow_exit_as_root = True
 
         # The priority is as follows:
@@ -99,12 +113,69 @@ def set_trace_configurations(self) -> None:
             )
 
         if "INSTANA_KAFKA_TRACE_CORRELATION" in os.environ:
-            self.kafka_trace_correlation = is_truthy(os.environ["INSTANA_KAFKA_TRACE_CORRELATION"])
+            self.kafka_trace_correlation = is_truthy(
+                os.environ["INSTANA_KAFKA_TRACE_CORRELATION"]
+            )
         elif isinstance(config.get("tracing"), dict) and "kafka" in config["tracing"]:
             self.kafka_trace_correlation = config["tracing"]["kafka"].get(
                 "trace_correlation", True
             )
 
+        self.set_disable_trace_configurations()
+
+    def set_disable_trace_configurations(self) -> None:
+        disabled_spans = []
+        enabled_spans = []
+
+        # The precedence is as follows:
+        # environment variables > in-code (local) config > agent config (configuration.yaml)
+        # For the env vars: INSTANA_TRACING_DISABLE > INSTANA_CONFIG_PATH
+        if "INSTANA_TRACING_DISABLE" in os.environ:
+            disabled_spans, enabled_spans = get_disable_trace_configurations_from_env()
+        elif "INSTANA_CONFIG_PATH" in os.environ:
+            disabled_spans, enabled_spans = get_disable_trace_configurations_from_yaml()
+        else:
+            # In-code (local) config
+            # The agent config (configuration.yaml) is handled in StandardOptions.set_disable_tracing()
+            disabled_spans, enabled_spans = (
+                get_disable_trace_configurations_from_local()
+            )
+
+        self.disabled_spans.extend(disabled_spans)
+        self.enabled_spans.extend(enabled_spans)
+
+    def is_span_disabled(self, category=None, span_type=None) -> bool:
+        """
+        Check if a span is disabled based on its category and type.
+
+        Args:
+            category (str): The span category (e.g., "logging", "databases")
+            span_type (str): The span type (e.g., "redis", "kafka")
+
+        Returns:
+            bool: True if the span is disabled, False otherwise
+        """
+        # If span_type is provided, check if it's disabled
+        if span_type and span_type in self.disabled_spans:
+            return True
+
+        # If category is provided directly, check if it's disabled
+        if category and category in self.disabled_spans:
+            return True
+
+        # If span_type is provided but not explicitly configured,
+        # check if its parent category is disabled. Also check for the precedence rules
+        if span_type and span_type in SPAN_TYPE_TO_CATEGORY:
+            parent_category = SPAN_TYPE_TO_CATEGORY[span_type]
+            if (
+                parent_category in self.disabled_spans
+                and span_type not in self.enabled_spans
+            ):
+                return True
+
+        # Default: not disabled
+        return False
+
 
 class StandardOptions(BaseOptions):
     """The options class used when running directly on a host/node with an Instana agent"""
@@ -177,6 +248,26 @@ def set_tracing(self, tracing: Dict[str, Any]) -> None:
         if "extra-http-headers" in tracing:
             self.extra_http_headers = tracing["extra-http-headers"]
 
+        # Handle span disabling configuration
+        if "disable" in tracing:
+            self.set_disable_tracing(tracing["disable"])
+
+    def set_disable_tracing(self, tracing_config: Sequence[Dict[str, Any]]) -> None:
+        # The precedence is as follows:
+        # environment variables > in-code (local) config > agent config (configuration.yaml)
+        if (
+            "INSTANA_TRACING_DISABLE" not in os.environ
+            and "INSTANA_CONFIG_PATH" not in os.environ
+            and not (
+                isinstance(config.get("tracing"), dict)
+                and "disable" in config["tracing"]
+            )
+        ):
+            # agent config (configuration.yaml)
+            disabled_spans, enabled_spans = parse_span_disabling(tracing_config)
+            self.disabled_spans.extend(disabled_spans)
+            self.enabled_spans.extend(enabled_spans)
+
     def set_from(self, res_data: Dict[str, Any]) -> None:
         """
         Set the source identifiers given to use by the Instana Host agent.

src/instana/util/config.py

@@ -2,11 +2,43 @@
 
 import itertools
 import os
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, Sequence, Tuple, Union
 
+from instana.configurator import config
 from instana.log import logger
 from instana.util.config_reader import ConfigReader
 
+# List of supported span categories (technology or protocol)
+SPAN_CATEGORIES = [
+    "logging",
+    "databases",
+    "messaging",
+    "protocols",  # http, grpc, etc.
+]
+
+# Mapping of span type calls (framework, library name, instrumentation name) to categories
+SPAN_TYPE_TO_CATEGORY = {
+    # Database types
+    "redis": "databases",
+    "mysql": "databases",
+    "postgresql": "databases",
+    "mongodb": "databases",
+    "cassandra": "databases",
+    "couchbase": "databases",
+    "dynamodb": "databases",
+    "sqlalchemy": "databases",
+    # Messaging types
+    "kafka": "messaging",
+    "rabbitmq": "messaging",
+    "pika": "messaging",
+    "aio_pika": "messaging",
+    "aioamqp": "messaging",
+    # Protocol types
+    "http": "protocols",
+    "grpc": "protocols",
+    "graphql": "protocols",
+}
+
 
 def parse_service_pair(pair: str) -> List[str]:
     """
@@ -151,10 +183,10 @@ def parse_ignored_endpoints_from_yaml(file_path: str) -> List[str]:
 def is_truthy(value: Any) -> bool:
     """
     Check if a value is truthy, accepting various formats.
-    
+
     @param value: The value to check
     @return: True if the value is considered truthy, False otherwise
-    
+
     Accepts the following as True:
     - True (Python boolean)
     - "True", "true" (case-insensitive string)
@@ -163,17 +195,128 @@ def is_truthy(value: Any) -> bool:
     """
     if value is None:
         return False
-    
+
     if isinstance(value, bool):
         return value
-    
+
     if isinstance(value, int):
         return value == 1
-    
+
     if isinstance(value, str):
         value_lower = value.lower()
         return value_lower == "true" or value == "1"
-    
+
     return False
 
+
+def parse_span_disabling(
+    disable_list: Sequence[Union[str, Dict[str, Any]]],
+) -> Tuple[List[str], List[str]]:
+    """
+    Process a list of span disabling configurations and return lists of disabled and enabled spans.
+
+    @param disable_list: List of span disabling configurations
+    @return: Tuple of (disabled_spans, enabled_spans)
+    """
+    if not isinstance(disable_list, list):
+        logger.debug(
+            f"parse_span_disabling: Invalid disable_list type: {type(disable_list)}"
+        )
+        return [], []
+
+    disabled_spans = []
+    enabled_spans = []
+
+    for item in disable_list:
+        if isinstance(item, str):
+            disabled = parse_span_disabling_str(item)
+            disabled_spans.extend(disabled)
+        elif isinstance(item, dict):
+            disabled, enabled = parse_span_disabling_dict(item)
+            disabled_spans.extend(disabled)
+            enabled_spans.extend(enabled)
+        else:
+            logger.debug(
+                f"parse_span_disabling: Invalid disable_list item type: {type(item)}"
+            )
+
+    return disabled_spans, enabled_spans
+
+
+def parse_span_disabling_str(item: str) -> List[str]:
+    """
+    Process a string span disabling configuration and return a list of disabled spans.
+
+    @param item: String span disabling configuration
+    @return: List of disabled spans
+    """
+    if item.lower() in SPAN_CATEGORIES or item.lower() in SPAN_TYPE_TO_CATEGORY.keys():
+        return [item.lower()]
+    else:
+        logger.debug(f"set_span_disabling_str: Invalid span category/type: {item}")
+        return []
+
+
+def parse_span_disabling_dict(items: Dict[str, bool]) -> Tuple[List[str], List[str]]:
+    """
+    Process a dictionary span disabling configuration and return lists of disabled and enabled spans.
+
+    @param items: Dictionary span disabling configuration
+    @return: Tuple of (disabled_spans, enabled_spans)
+    """
+    disabled_spans = []
+    enabled_spans = []
+
+    for key, value in items.items():
+        if key in SPAN_CATEGORIES or key in SPAN_TYPE_TO_CATEGORY.keys():
+            if is_truthy(value):
+                disabled_spans.append(key)
+            else:
+                enabled_spans.append(key)
+        else:
+            logger.debug(f"set_span_disabling_dict: Invalid span category/type: {key}")
+
+    return disabled_spans, enabled_spans
+
+
+def get_disable_trace_configurations_from_env() -> Tuple[List[str], List[str]]:
+    # Read INSTANA_TRACING_DISABLE environment variable
+    if tracing_disable := os.environ.get("INSTANA_TRACING_DISABLE", None):
+        if is_truthy(tracing_disable):
+            # INSTANA_TRACING_DISABLE is True/true/1, then we disable all tracing
+            disabled_spans = []
+            for category in SPAN_CATEGORIES:
+                disabled_spans.append(category)
+            return disabled_spans, []
+        else:
+            # INSTANA_TRACING_DISABLE is a comma-separated list of span categories/types
+            tracing_disable_list = [x.strip() for x in tracing_disable.split(",")]
+            return parse_span_disabling(tracing_disable_list)
+    return [], []
+
+
+def get_disable_trace_configurations_from_yaml() -> Tuple[List[str], List[str]]:
+    config_reader = ConfigReader(os.environ.get("INSTANA_CONFIG_PATH", ""))
+
+    if "tracing" in config_reader.data:
+        root_key = "tracing"
+    elif "com.instana.tracing" in config_reader.data:
+        logger.warning(
+            'Please use "tracing" instead of "com.instana.tracing" for local configuration file.'
+        )
+        root_key = "com.instana.tracing"
+    else:
+        return [], []
+
+    tracing_disable_config = config_reader.data[root_key].get("disable", "")
+    return parse_span_disabling(tracing_disable_config)
+
+
+def get_disable_trace_configurations_from_local() -> Tuple[List[str], List[str]]:
+    if "tracing" in config:
+        if tracing_disable_config := config["tracing"].get("disable", None):
+            return parse_span_disabling(tracing_disable_config)
+    return [], []
+
+
 # Made with Bob