harness-sdk 1.0.0__py3-none-any.whl

harness_sdk/__init__.py

@@ -0,0 +1,5 @@
+"""Harness Python SDK — generic instrumentation and plugin architecture."""
+
+from harness_sdk.agent import Agent
+
+__all__ = ["Agent"]

harness_sdk/agent.py

@@ -0,0 +1,171 @@
+import os
+import sys
+import threading
+import traceback
+
+import distro
+
+from harness_sdk import constants
+from harness_sdk.agent_init import AgentInit
+from harness_sdk.config.config import Config
+from harness_sdk.custom_logger import get_custom_logger
+from harness_sdk.env import get_env_value
+from harness_sdk.instrumentation.instrumentation_definitions import (
+    SUPPORTED_LIBRARIES,
+    get_instrumentation_wrapper,
+    FLASK_KEY,
+    DJANGO_KEY,
+    FAST_API_KEY,
+    instrument_supported_contrib_without_wrapper,
+)
+from harness_sdk.instrumentation.genai_env import maybe_set_genai_payload_capture_env_vars
+from harness_sdk.plugins.control import ControlPlugin, get_control_registry
+from harness_sdk.plugins.loader import load_control_plugins, load_observability_plugins
+from harness_sdk.version import __version__  # pylint:disable=C0413
+
+logger = get_custom_logger(__name__)
+
+
+class Agent:
+    _instance = None
+    _singleton_lock = threading.Lock()
+
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._singleton_lock:
+                logger.debug('Creating Agent')
+                logger.debug('Python version: %s', sys.version)
+                logger.debug('Harness SDK version: %s', __version__)
+                cls._instance = super(Agent, cls).__new__(cls)
+        else:
+            logger.debug('Using existing Agent.')
+        return cls._instance
+
+    def __init__(self):
+        if getattr(self, "_initialized", False):
+            self.is_lambda = False
+            return
+        logger.debug('Initializing Agent.')
+        if not self.is_enabled():
+            return
+        try:
+            self._config = Config()
+            self._init = AgentInit(self._config)
+            load_control_plugins(self._config)
+            self._init.init_trace_provider()
+            self._init.init_propagation()
+            load_observability_plugins(self._config)
+            self._initialized = True
+        except Exception as err:  # pylint: disable=W0703
+            logger.error(
+                'Failed to initialize Agent: exception=%s, stacktrace=%s',
+                err,
+                traceback.format_exc(),
+            )
+        self.is_lambda = False
+        logger.debug("Platform: %s", distro.id())
+        logger.debug("Platform version: %s", distro.version())
+        logger.debug('Harness SDK version: %s', __version__)
+        logger.debug("successfully initialized harness sdk")
+
+        if hasattr(os, 'register_at_fork'):
+            logger.info('Registering after_in_child handler.')
+            os.register_at_fork(after_in_child=self.post_fork)  # pylint:disable=E1101
+
+    def post_fork(self):
+        logger.info("In post fork hook")
+        self._init.post_fork()
+        load_control_plugins(self._config)
+
+    def instrument(self, app=None, skip_libraries=None, auto_instrument=False):
+        logger.debug("Beginning instrumentation")
+        self._init.apply_config(self._config)
+
+        if skip_libraries is None:
+            skip_libraries = []
+        if not self.is_initialized():
+            logger.debug('agent is not initialized, not instrumenting')
+            return
+
+        maybe_set_genai_payload_capture_env_vars()
+
+        for library_key in SUPPORTED_LIBRARIES:
+            if library_key in skip_libraries:
+                logger.debug('not attempting to instrument %s', library_key)
+                continue
+            logger.debug("attempting to instrument %s", library_key)
+            self._instrument(library_key, app, auto_instrument)
+
+        if self._should_instrument_generic_contrib():
+            instrument_supported_contrib_without_wrapper(skip_libraries)
+        else:
+            logger.debug("Skipping generic contrib fallback instrumentation")
+        logger.debug("Complete instrumentation")
+
+    def _should_instrument_generic_contrib(self):
+        """
+        Fallback instrumentation runs when no control plugin provides blocking.
+        """
+        if get_control_registry().has_blocking_capability():
+            logger.info("Blocking control plugin active, skipping fallback instrumentation")
+            return False
+        logger.info("No blocking control plugin, enabling fallback instrumentation")
+        return True
+
+    def _instrument(self, library_key, app=None, auto_instrument=False):
+        wrapper_instance = get_instrumentation_wrapper(library_key)
+        if wrapper_instance is None:
+            logger.debug("no instrumentation wrapper instance available for %s", library_key)
+            return
+
+        if library_key == FLASK_KEY and app is not None:
+            wrapper_instance.with_app(app)
+
+        if library_key == DJANGO_KEY and auto_instrument is True:
+            from harness_sdk.instrumentation.django.django_auto_instrumentation_compat import (  # pylint: disable=C0415
+                add_django_auto_instr_wrappers,
+            )
+            add_django_auto_instr_wrappers(self, wrapper_instance)
+            return
+
+        if library_key == FAST_API_KEY:
+            from harness_sdk.instrumentation.fast_api.fast_api_auto_instrumentation_compat import (  # pylint: disable=C0415
+                add_fast_api_auto_instr_wrappers,
+            )
+            add_fast_api_auto_instr_wrappers(self, wrapper_instance)
+            return
+
+        logger.debug("registering library %s with wrapper instance", library_key)
+        self.register_library(library_key, wrapper_instance)
+
+    def register_library(self, library_name, wrapper_instance):
+        logger.debug('attempting to register library instrumentation: %s', library_name)
+        try:
+            self._init.init_library_instrumentation(library_name, wrapper_instance)
+        except Exception as err:  # pylint: disable=W0703
+            logger.debug(constants.EXCEPTION_MESSAGE, library_name, err, traceback.format_exc())
+
+    def register_control_plugin(self, plugin: ControlPlugin) -> None:
+        logger.debug('Registering control plugin %s', plugin.name)
+        plugin.on_init(self._config)
+        get_control_registry().register(plugin)
+
+    def register_processor(self, processor) -> None:  # pylint: disable=R1710
+        logger.debug('Entering Agent.register_processor().')
+        if not self.is_initialized():
+            return None
+        return self._init.register_processor(processor)
+
+    def is_enabled(self) -> bool:
+        enabled = get_env_value('ENABLED')
+        if enabled and enabled.lower() == 'false':
+            logger.debug("ENABLED is disabled.")
+            return False
+        return True
+
+    def is_initialized(self) -> bool:
+        if not self.is_enabled():
+            return False
+        if not self._initialized:
+            return False
+        return True

harness_sdk/agent_init.py

@@ -0,0 +1,151 @@
+'''Initialize all the components using configuration from AgentConfig'''
+# pylint: disable=C0303
+import os
+import traceback
+import logging
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
+try:
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter as OTLPGrpcSpanExporter
+except ImportError:
+    pass
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter as OTLPHttpSpanExporter
+from opentelemetry.trace import ProxyTracerProvider
+from opentelemetry.sdk.resources import Resource
+from harness_sdk import constants
+from harness_sdk.config import config_pb2
+from harness_sdk.otlp_reporting import (
+    compression_type_to_otlp_grpc,
+    compression_type_to_otlp_http,
+    is_supported_encoding,
+    normalize_otlp_http_traces_endpoint,
+)
+
+logger = logging.getLogger(__name__)  # pylint: disable=C0103
+
+
+class AgentInit:  # pylint: disable=R0902,R0903
+    '''Initialize all the OTel components using configuration from AgentConfig'''
+
+    def __init__(self, agent_config):
+        logger.debug('Initializing AgentInit object.')
+        self._config = agent_config
+
+        if hasattr(os, 'register_at_fork'):
+            logger.info('Registering after_in_child handler.')
+            os.register_at_fork(after_in_child=self.post_fork)  # pylint:disable=E1101
+
+    def post_fork(self):
+        self.apply_config(self._config)  # pylint:disable=W0212
+
+    def apply_config(self, agent_config):
+        if agent_config:
+            self._config = agent_config
+        self.init_trace_provider()
+        self.init_propagation()
+        if (
+            "HA_ENABLE_CONSOLE_SPAN_EXPORTER" in os.environ
+            or "AT_ENABLE_CONSOLE_SPAN_EXPORTER" in os.environ
+            or "TA_ENABLE_CONSOLE_SPAN_EXPORTER" in os.environ
+        ):
+            self.set_console_span_processor()
+
+    def init_trace_provider(self) -> None:
+        if isinstance(trace.get_tracer_provider(), ProxyTracerProvider):
+            logger.debug("no configured trace provider detected, adding one")
+            resource_attributes = {
+                "service.name": self._config.config.service_name.value,
+                "service.instance.id": os.getpid(),
+                "telemetry.sdk.version": constants.TELEMETRY_SDK_VERSION,
+                "telemetry.sdk.name": constants.TELEMETRY_SDK_NAME,
+                "telemetry.sdk.language": constants.TELEMETRY_SDK_LANGUAGE
+            }
+            if self._config.config.resource_attributes:
+                resource_attributes.update(self._config.config.resource_attributes)
+            tracer_provider = TracerProvider(
+                resource=Resource.create(resource_attributes)
+            )
+            trace.set_tracer_provider(tracer_provider)
+        else:
+            logger.debug("tracer provider already configured, skipping trace provider configuration")
+
+    def init_propagation(self) -> None:
+        propagator_list = []
+        for prop_format in self._config.config.propagation_formats:
+            if prop_format == config_pb2.PropagationFormat.TRACECONTEXT:
+                from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator  # pylint: disable=C0415
+                propagator_list += [TraceContextTextMapPropagator()]
+            if prop_format == config_pb2.PropagationFormat.B3:
+                from opentelemetry.propagators.b3 import B3MultiFormat  # pylint: disable=C0415
+                propagator_list += [B3MultiFormat()]
+
+        from opentelemetry.propagate import set_global_textmap  # pylint: disable=C0415
+        from opentelemetry.propagators.composite import CompositePropagator  # pylint: disable=C0415
+        set_global_textmap(CompositePropagator(propagator_list))
+
+    def init_library_instrumentation(self, instrumentation_name, wrapper_instance):
+        logger.debug("Attempting to initialize %s instrumentation", instrumentation_name)
+        try:
+            wrapper_instance.instrument()
+        except Exception as err:  # pylint: disable=W0703
+            logger.debug(
+                constants.INST_WRAP_EXCEPTION_MSSG,
+                instrumentation_name,
+                err,
+                traceback.format_exc(),
+            )
+
+    def register_processor(self, processor) -> None:
+        trace.get_tracer_provider().add_span_processor(processor)
+
+    def set_console_span_processor(self) -> None:
+        console_span_exporter = ConsoleSpanExporter(
+            service_name=self._config.config.service_name)
+        simple_export_span_processor = SimpleSpanProcessor(console_span_exporter)
+        trace.get_tracer_provider().add_span_processor(simple_export_span_processor)
+
+    def _init_exporter(self, trace_reporter_type):
+        exporter_type = ''
+        exporter = None
+        exporter_endpoint = None
+        reporting = self._config.config.reporting
+        reporting_encoding = getattr(self._config, 'reporting_encoding', None)
+        if reporting_encoding and not is_supported_encoding(reporting_encoding):
+            logger.warning(
+                'Unsupported reporting encoding `%s`; OTLP protobuf encoding will be used',
+                reporting_encoding,
+            )
+        try:
+            _token = reporting.token.value
+            headers = {"harness-sdk-token": _token} if _token else {}
+            if trace_reporter_type == config_pb2.TraceReporterType.OTLP:
+                exporter_type = 'otlp'
+                exporter_endpoint = reporting.endpoint.value
+                exporter = OTLPGrpcSpanExporter(
+                    endpoint=exporter_endpoint,
+                    insecure=not reporting.secure.value,
+                    headers=headers,
+                    compression=compression_type_to_otlp_grpc(reporting.compression_type),
+                )
+            elif trace_reporter_type == config_pb2.TraceReporterType.OTLP_HTTP:
+                exporter_type = 'otlp_http'
+                exporter_endpoint = normalize_otlp_http_traces_endpoint(
+                    reporting.endpoint.value
+                )
+                exporter = OTLPHttpSpanExporter(
+                    endpoint=exporter_endpoint,
+                    headers=headers,
+                    compression=compression_type_to_otlp_http(reporting.compression_type),
+                )
+
+            if exporter:
+                logger.info('Initialized %s exporter reporting to `%s`',
+                            exporter_type, exporter_endpoint)
+            return exporter
+        except Exception as err:  # pylint: disable=W0703
+            logger.error('Failed to initialize %s exporter: exception=%s, stacktrace=%s',
+                         exporter_type, err, traceback.format_exc())
+            return None

harness_sdk/autoinstrumentation/sitecustomize.py

@@ -0,0 +1,30 @@
+import os
+
+import psutil
+from harness_sdk.agent import Agent # pylint:disable=C0413
+
+from harness_sdk.config.config import Config  # pylint:disable=C0413,C0412
+from harness_sdk.custom_logger import get_custom_logger  # pylint:disable=C0413,C0412,C0411
+
+config = Config()
+logger = get_custom_logger(__name__)
+
+a = Agent()
+a.instrument(None, None, auto_instrument=True)
+
+__POST_INIT = False
+POST_FORK_SERVERS = ['gunicorn']
+
+original_process = psutil.Process(os.getpid())
+args = original_process.cmdline()
+
+for entry in POST_FORK_SERVERS:
+    for arg in args:
+        if entry in arg:
+            __POST_INIT = True
+            logger.info('Detected server %s - deferring filter loading until post fork', entry)
+            break
+
+
+if __POST_INIT is not True:
+    logger.info("Control plugins loaded during autoinstrumentation agent init")

harness_sdk/autoinstrumentation/wrapper.py

@@ -0,0 +1,78 @@
+# Based upon the OTel autoinstrumentation feature
+'''This module implements a CLI command that be used to
+autoinstrument existing python programs that use supported
+modules.'''
+import argparse
+from logging import getLogger
+from os import environ, execl, getcwd
+from os.path import abspath, dirname, pathsep
+from shutil import which
+
+logger = getLogger(__file__)
+
+def parse_args():
+    '''Parse CLI arguments.'''
+    parser = argparse.ArgumentParser(
+        description="""
+        harness_sdk-instrument automatically instruments a Python
+        program and runs the program
+        """
+    )
+
+    parser.add_argument("command", help="Your Python application.")
+
+    parser.add_argument(
+        "command_args",
+        help="Arguments for your application.",
+        nargs=argparse.REMAINDER,
+    )
+
+    return parser.parse_args()
+
+def update_python_path() -> None:
+    '''Retrieve existing PYTHONPATH'''
+    python_path = environ.get("PYTHONPATH")
+
+    # Split the paths
+    if not python_path:
+        python_path = []
+    else:
+        python_path = python_path.split(pathsep)
+
+    # Get the current working directory
+    cwd_path = getcwd()
+
+    # If this directory is already in python_path, remove it.
+    python_path = [path for path in python_path if path != cwd_path]
+
+    # Add CWD to the front.
+    python_path.insert(0, cwd_path)
+
+    # What is the directory containing this python file?
+    filedir_path = dirname(abspath(__file__))
+
+    # If this directory is already in python_path, remove it.
+    python_path = [path for path in python_path if path != filedir_path]
+
+    # Add this directory to the front
+    python_path.insert(0, filedir_path)
+
+    # Reset PYTHONPATH environment variable
+    environ["PYTHONPATH"] = pathsep.join(python_path)
+
+def run() -> None:
+    '''harness_sdk-instrument Entry point'''
+    args = parse_args()
+
+    # update PYTHONPATH env var
+    update_python_path()
+
+    # Get full path to the command that was passed in as an
+    # argument
+    executable = which(args.command)
+
+    # Execute the app
+    execl(executable, executable, *args.command_args)
+
+if __name__ == '__main__':
+    run()

harness_sdk/config/config.py

@@ -0,0 +1,152 @@
+import copy
+import json
+import os
+
+import yaml
+
+from google.protobuf import json_format
+
+from harness_sdk.config import config_pb2
+from harness_sdk.config.default import DEFAULT, SDK_CONFIG_KEYS
+from harness_sdk.config.environment import overwrite_with_environment
+from harness_sdk.otlp_reporting import normalize_reporting_dict
+from harness_sdk.custom_logger import get_custom_logger
+
+logger = get_custom_logger(__name__)
+
+
+def _parse_plugin_env(env_key: str) -> list | None:
+    raw = os.environ.get(env_key)
+    if not raw:
+        return None
+    return [name.strip() for name in raw.split(',') if name.strip()]
+
+
+def _ordered_plugin_names_from_section(section) -> list:
+    if section is None:
+        return []
+    if isinstance(section, list):
+        return [str(name).strip() for name in section if str(name).strip()]
+    if isinstance(section, dict):
+        return [
+            name for name, cfg in section.items()
+            if _is_plugin_entry_enabled(cfg)
+        ]
+    return []
+
+
+def _is_plugin_entry_enabled(cfg) -> bool:
+    if isinstance(cfg, dict):
+        return cfg.get('enabled', True)
+    return bool(cfg)
+
+
+def _filter_sdk_config(file_dict):
+    if not file_dict:
+        return {}
+    return {key: file_dict[key] for key in SDK_CONFIG_KEYS if key in file_dict}
+
+
+class Config:  # pylint:disable=R0903
+    _instance = None
+
+    def __new__(cls):
+        if not hasattr(cls, "_instance") or cls._instance is None:
+            cls._instance = super(Config, cls).__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if not hasattr(self, '_initialized'):
+            self._initialized = True
+            (
+                self.config,
+                self.plugins_config,
+                self.enabled_control_plugins,
+                self.enabled_observability_plugins,
+                self.reporting_encoding,
+            ) = build_config()
+
+    def get_plugin_option(self, plugin_name: str, option: str, default=None, plugin_type="control"):
+        section = self.plugins_config.get(plugin_type, {})
+        if plugin_name in section and isinstance(section[plugin_name], dict):
+            return section[plugin_name].get(option, default)
+        return default
+
+
+def merge_config(base_config, overriding_config):
+    for key in overriding_config:
+        if key in base_config and isinstance(base_config[key], dict):
+            if key in overriding_config:
+                base_config[key] = merge_config(base_config[key], overriding_config[key])
+        else:
+            base_config[key] = overriding_config[key]
+    return base_config
+
+
+def build_config():
+    agent_config = config_pb2.AgentConfig()
+    config_dict = copy.deepcopy(DEFAULT)
+    file_dict = read_from_file()
+    if file_dict is not None:
+        merge_config(config_dict, _filter_sdk_config(file_dict))
+
+    plugins_config = config_dict.pop('plugins', {})
+
+    enabled_control_plugins = _ordered_plugin_names_from_section(
+        plugins_config.get('control')
+    )
+    if not enabled_control_plugins:
+        enabled_control_plugins = _parse_plugin_env('HA_CONTROL_PLUGINS') or []
+    if not enabled_control_plugins:
+        enabled_control_plugins = _parse_plugin_env('AT_CONTROL_PLUGINS') or []
+
+    enabled_observability_plugins = _ordered_plugin_names_from_section(
+        plugins_config.get('observability')
+    )
+    if not enabled_observability_plugins:
+        enabled_observability_plugins = _parse_plugin_env('HA_OBSERVABILITY_PLUGINS')
+    if not enabled_observability_plugins:
+        enabled_observability_plugins = _parse_plugin_env('AT_OBSERVABILITY_PLUGINS')
+    if not enabled_observability_plugins:
+        enabled_observability_plugins = ['builtin_pipeline', 'builtin_span_attributes']
+
+    reporting_encoding = None
+    if 'reporting' in config_dict:
+        reporting_encoding = normalize_reporting_dict(config_dict['reporting'])
+
+    json_string = json.dumps(config_dict)
+    json_format.Parse(json_string, agent_config, ignore_unknown_fields=True)
+
+    agent_config, reporting_encoding = overwrite_with_environment(
+        agent_config, reporting_encoding
+    )
+    logger.debug(json_string)
+    return (
+        agent_config,
+        plugins_config,
+        enabled_control_plugins,
+        enabled_observability_plugins,
+        reporting_encoding,
+    )
+
+
+def read_from_file():
+    config_path = _config_file_path()
+    if config_path is None or not os.path.exists(config_path):
+        logger.debug("HA_CONFIG_FILE path not set")
+        return None
+
+    with open(config_path, 'r', encoding="UTF-8") as config_file:
+        try:
+            return yaml.safe_load(config_file)
+        except yaml.YAMLError as exc:
+            logger.debug(exc)
+            return None
+
+
+def _config_file_path():
+    return (
+        os.environ.get('HA_CONFIG_FILE')
+        or os.environ.get('AT_CONFIG_FILE')
+        or os.environ.get('TA_CONFIG_FILE')
+    )