1"""
  2The LaunchDarkly observability plugin for Python.
  3
  4In typical usage you will only need to instantiate the :class:`ObservabilityPlugin` and pass it to the LaunchDarkly client during initialization.
  5
  6The settings for the observability plugins are defined by the :class:`ObservabilityConfig` class.
  7
  8The `ldobserve.observe` singleton is used for manual tracking of events, metrics, and logs.
  9
 10# Quick Start
 11```python
 12from ldobserve import ObservabilityConfig, ObservabilityPlugin
 13import ldclient
 14from ldclient.config import Config
 15
 16ldclient.set_config(Config("YOUR_SDK_KEY",
 17plugins=[
 18    ObservabilityPlugin(
 19        ObservabilityConfig(
 20            service_name="your-service-name",
 21            service_version="your-service-sha",
 22        )
 23    )]))
 24```
 25
 26"""
 27
 28import logging
 29import os
 30from typing import List, Optional
 31from ldclient.hook import Hook as LDHook
 32from opentelemetry.instrumentation import auto_instrumentation
 33from ldobserve.config import ObservabilityConfig
 34from ldobserve.observe import _ObserveInstance
 35import ldobserve.observe as observe
 36from ldobserve.config import _ProcessedConfig
 37import ldobserve.observe
 38from ldobserve._otel.configuration import _OTELConfiguration
 39from ldclient.plugin import Plugin, EnvironmentMetadata, PluginMetadata
 40from ldotel.tracing import Hook, HookOptions
 41from ldclient.client import LDClient
 42from opentelemetry.instrumentation.environment_variables import (
 43    OTEL_PYTHON_DISABLED_INSTRUMENTATIONS,
 44)
 45from opentelemetry.sdk.environment_variables import OTEL_EXPERIMENTAL_RESOURCE_DETECTORS
 46
 47
 48def _extend_environment_list(env_var_name: str, *new_items: str) -> None:
 49    """
 50    Extend an environment variable containing a comma-separated list with additional items.
 51
 52    This function reads the current value of the specified environment variable,
 53    adds the provided items to the comma-separated list, and sets the
 54    environment variable with the extended list.
 55
 56    Args:
 57        env_var_name: The name of the environment variable to extend.
 58        *new_items: Variable number of items to add to the list.
 59
 60    Example:
 61        >>> _extend_environment_list("MY_LIST", "item1", "item2")
 62        # If MY_LIST was "existing_item", it will become "existing_item,item1,item2"
 63    """
 64    current_value = os.getenv(env_var_name, "")
 65
 66    # Split the current value by comma and strip whitespace
 67    # The if condition uses strip to determine if the result is non-empty.
 68    # When it is, then the returned item still needs stripped when creating the new list.
 69    # current_value = ",,,toast,"
 70    # [item.strip() for item in current_value.split(",") if item.strip()]
 71    # Result: ['toast']
 72    current_list = [item.strip() for item in current_value.split(",") if item.strip()]
 73
 74    # Add new items, avoiding duplicates
 75    for item in new_items:
 76        stripped_item = item.strip()
 77        if stripped_item and stripped_item not in current_list:
 78            current_list.append(stripped_item)
 79
 80    # Join the list back into a comma-separated string
 81    new_value = ",".join(current_list)
 82
 83    # Set the environment variable
 84    os.environ[env_var_name] = new_value
 85
 86
 87def _extend_experimental_resource_detectors(*detectors: str) -> None:
 88    """
 89    Extend the OTEL_EXPERIMENTAL_RESOURCE_DETECTORS environment variable with additional detectors.
 90
 91    This function reads the current value of OTEL_EXPERIMENTAL_RESOURCE_DETECTORS,
 92    adds the provided detectors to the comma-separated list, and sets the
 93    environment variable with the extended list.
 94    """
 95    _extend_environment_list(OTEL_EXPERIMENTAL_RESOURCE_DETECTORS, *detectors)
 96
 97
 98def _extend_disabled_instrumentations(*instrumentations: str) -> None:
 99    """
100    Extend the OTEL_PYTHON_DISABLED_INSTRUMENTATIONS environment variable with additional instrumentations.
101
102    This function reads the current value of OTEL_PYTHON_DISABLED_INSTRUMENTATIONS,
103    adds the provided instrumentations to the comma-separated list, and sets the
104    environment variable with the extended list.
105
106    Args:
107        *instrumentations: Variable number of instrumentation names to add to the disabled list.
108                          These should be the names of OpenTelemetry instrumentations to disable.
109
110    Example:
111        >>> extend_disabled_instrumentations("redis", "kafka")
112        # If OTEL_PYTHON_DISABLED_INSTRUMENTATIONS was "grpc_client",
113        # it will become "grpc_client,redis,kafka"
114    """
115    _extend_environment_list(OTEL_PYTHON_DISABLED_INSTRUMENTATIONS, *instrumentations)
116
117
118class ObservabilityPlugin(Plugin):
119    def __init__(self, config: Optional[ObservabilityConfig] = None):
120        self._config = _ProcessedConfig(config or ObservabilityConfig())
121        # Instruct auto-instrumentation to not instrument logging.
122        # We will either have already done it, or it is disabled.
123        _extend_disabled_instrumentations("logging")
124
125        if self._config.disabled_instrumentations:
126            _extend_disabled_instrumentations(*self._config.disabled_instrumentations)
127
128        # If the OTEL_EXPERIMENTAL_RESOURCE_DETECTORS environment variable is not set, then we will use the config.
129        # Consider an empty environment variable to be the same as not setting it.
130        if not os.getenv(OTEL_EXPERIMENTAL_RESOURCE_DETECTORS):
131            # Configure resource detectors based on config
132            resource_detectors = []
133            if self._config.process_resources:
134                resource_detectors.append("process")
135            if self._config.os_resources:
136                resource_detectors.append("os")
137
138            if resource_detectors:
139                _extend_experimental_resource_detectors(*resource_detectors)
140
141        auto_instrumentation.initialize()
142
143    def metadata(_self) -> PluginMetadata:
144        return PluginMetadata(name="launchdarkly-observability")
145
146    def register(self, _client: LDClient, metadata: EnvironmentMetadata) -> None:
147        if metadata.sdk_key is None:
148            logging.getLogger(__name__).warning(
149                "The observability plugin was registered without an SDK key. "
150                "This will result in no data being sent to LaunchDarkly."
151            )
152            return
153
154        _init(metadata.sdk_key, self._config)
155
156    def get_hooks(_self, _metadata: EnvironmentMetadata) -> List[LDHook]:
157        return [Hook(options=HookOptions(include_value=True))]
158
159
160def _init(project_id: str, config: _ProcessedConfig):
161    otel_configuration = _OTELConfiguration(project_id, config)
162    ldobserve.observe._instance = _ObserveInstance(project_id, otel_configuration)
163
164
165__all__ = ["ObservabilityPlugin", "ObservabilityConfig", "observe"]