cavisson-pythonagent 0.0.1__py3-none-any.whl

pythonagent/agent/internal/framesinfo.py

@@ -0,0 +1,152 @@
+
+"""This module contains all interactions with raw Python frame objects.
+
+This module's public functions should never ever return a raw frame object to
+the caller.  To explain all the weird try: finally: del frame stuff, see:
+https://docs.python.org/3.4/library/inspect.html#the-interpreter-stack.
+
+"""
+
+from __future__ import unicode_literals
+import sys
+import traceback
+
+
+def is_internal_frame(filename):
+    """Return True if this filename belongs to an internal CavAgent module.
+
+    """
+    return 'site-packages/CavAgent' in filename
+
+
+class FrameInfo(object):
+    """Copy of the important info from a Python frame.
+
+    """
+    __slots__ = ('class_name', 'name', 'filename', 'lineno', 'internal')
+
+    def __init__(self, frame):
+        try:
+            try:
+                self.class_name = frame.f_locals['self'].__class__.__name__
+            except:
+                self.class_name = None
+
+            code = frame.f_code
+            self.name = code.co_name
+            self.filename = code.co_filename
+            self.lineno = code.co_firstlineno
+            self.internal = is_internal_frame(self.filename)
+        finally:
+            del frame
+
+    def __eq__(self, rhs):
+        try:
+            return (
+                self.name == rhs.name and
+                self.filename == rhs.filename and
+                self.lineno == rhs.lineno and
+                self.class_name == rhs.class_name
+            )
+        except:
+            return False
+
+    def __ne__(self, rhs):
+        return not self == rhs
+
+    def __hash__(self):
+        return hash((self.name, self.filename, self.lineno))
+
+
+def _frame_hash(frame):
+    try:
+        code = frame.f_code
+        key = (code.co_name, code.co_filename, code.co_firstlineno)
+        return hash(key)
+    finally:
+        del frame
+
+
+def _get_root_frame(thread_id):
+    # Internal use only - get the root frame for the specified thread.
+    frames = sys._current_frames()
+    try:
+        return frames.get(thread_id, None)
+    finally:
+        del frames
+
+
+def get_formatted_stack(thread_id):
+    """Return a list of formatted strings representing the current stack.
+
+    """
+    root = _get_root_frame(thread_id)
+    try:
+        return traceback.format_stack(root)
+    finally:
+        del root
+
+
+def get_frame_info(level):
+    """Drop in replacement for `sys._getframe` which returns a FrameInfo object.
+
+    """
+    frame = sys._getframe(level + 1)
+    try:
+        return FrameInfo(frame)
+    finally:
+        del frame
+
+
+def get_stack(frame_cache, from_root=True, thread_id=None, greenlet_ref=None):
+    """Generate a list of FrameInfo objects representing the python call stack.
+
+    By default this function tries to generate a full call stack from the root
+    frame on the specified thread or greenlet id.  When calling this function
+    for this purpose a thread_id must *always* be specified.
+
+    Passing `from_root=False` will generate a stack from the current frame
+    outwards.  When calling in this way a thread or greenlet id is not required.
+
+    `frame_cache` is a dict which is used to cache FrameInfo objects in order
+    to reduce the memory footprint of generating stacks with many duplicate
+    frames.  The management of this cache is left up to the caller.
+
+    """
+
+    frame = None
+    try:
+        if from_root:
+            if greenlet_ref:
+                ctx = greenlet_ref()
+                if ctx:
+                    # note that ctx.gr_frame may be none indicating that the current BT is not running
+                    # under the context of greenlet but thread
+                    frame = ctx.gr_frame or _get_root_frame(thread_id)
+                else:
+                    return None
+            else:
+                frame = _get_root_frame(thread_id)
+
+            if frame is None:
+                return None
+        else:
+            frame = sys._getframe()
+
+        stack = []
+        while frame:
+            f_hash = _frame_hash(frame)
+            try:
+                stack.append(frame_cache[f_hash])
+            except KeyError:
+                f_info = FrameInfo(frame)
+                frame_cache[f_hash] = f_info
+                stack.append(f_info)
+
+            next_frame = frame.f_back
+            del frame
+            frame = next_frame
+            del next_frame
+        return stack
+    finally:
+        del frame

pythonagent/agent/internal/heap_dump.py

@@ -0,0 +1,39 @@
+
+def create_heap_dump_muppy(self):
+    try:
+        import os
+        import sys
+
+        # Use bundled Pympler library from agent vendor package to avoid external dependency installation.
+
+        from pythonagent.vendor.pympler import muppy, summary
+        all_objects = muppy.get_objects()
+        sum1 = summary.summarize(all_objects)
+        sum1_sorted = sorted(sum1, key=lambda x: x[2], reverse=True)
+
+        all_list = []
+        for item in sum1_sorted:  # Iterate over the sorted data
+            obj_type = item[0]  # Object type
+            obj_count = item[1]  # Object count
+            obj_size = item[2]  # Size in bytes
+            formatted_line = f"{obj_type: <40}\t{obj_count: <12}\t{obj_size: <15}"
+
+            all_list.append(formatted_line)
+
+        # Add header with fixed width
+        header = f"{'types': <40}\t{'# objects': <12}\t{'total size(bytes)': <15}"
+
+        all_list.insert(0, header)
+        return "\n".join(all_list)
+
+    except ImportError as e:
+        self.logger.error(f"Pympler library is not found{e}")
+        return "\nUnable to capture heap dump \n\n\n"
+
+
+
+    except Exception as e:
+        self.logger.error(f"Exception in heap dump{e}")
+        return "\nUnable to capture heap dump\n\n\n"
+
+

pythonagent/agent/internal/intercept_module.py

@@ -0,0 +1,70 @@
+
+
+from pythonagent.agent.probes import frameworks, http, sql, logging, mongodb, cache, message_brokers, coroutines, openai, langchain, elasticdb, Instrumentation
+
+BT = (
+#    # Entry points
+    ('flask', frameworks.intercept_flask),
+    ('django.core.handlers.wsgi', frameworks.intercept_django_wsgi_handler),
+    ('django.core.handlers.base', frameworks.intercept_django_base_handler),
+    ('django.core.handlers.asgi', frameworks.intercept_django_asgi_handler),
+    ('bottle', frameworks.intercept_bottle),
+    ('aiohttp.web_app', frameworks.intercept_aiohttp_web),
+    ('tornado.web', frameworks.intercept_tornado_async_web),
+    ('cherrypy', frameworks.intercept_cherrypy),    
+    ('pyramid', frameworks.intercept_pyramid),
+    ('falcon', frameworks.intercept_falcon),
+    ('starlette.routing', frameworks.intercept_fastapi_asgi_handler),
+    ('uvicorn.config', frameworks.intercept_uvicorn_config),
+#    # HTTP exit calls
+    ('httplib', http.intercept_httplib),
+    ('http.client', http.intercept_httplib),
+    ('urllib3', http.intercept_urllib3),
+    ('requests', http.intercept_requests),
+    ('tornado.httpclient', http.intercept_tornado_httpclient),
+    ('aiohttp.client', http.intercept_aiohttp_client),
+    ('httpx', http.intercept_httpx_client),
+    #('boto.https_connection', http.intercept_boto),
+
+#    # Logging
+    ('logging', logging.intercept_logging),
+
+#    # SQL exit calls
+    ('psycopg2', sql.psycopg2.intercept_psycopg2_connection),
+    ('pymysql.connections', sql.pymysql.intercept_pymysql_connections),
+    ('mysql.connector.connection', sql.mysql_connector.intercept_mysql_connector_connection),
+    ('mysql.connector.connection_cext', sql.mysql_connector_cext.intercept_mysql_connector_cext_connection),
+    ('MySQLdb.connections', sql.mysqldb.intercept_MySQLdb_connection),
+#    # MongoDB
+    ('pymongo', mongodb.intercept_pymongo),
+    #Dynamo
+    ('botocore.client', sql.dynamodb.intercept_dynamodb),
+    ('botocore.endpoint', sql.botocores3.intercept_s3),
+
+#    #REDIS
+    ('redis.connection', cache.intercept_redis),
+    ('redis.asyncio.connection', cache.intercept_redis_asyncio),
+    ('elasticsearch',elasticdb.intercept_elastic),
+
+    # RABBIT MQ
+    ('pika', message_brokers.intercept_pika),
+
+    # Asyncio
+    ('asyncio', coroutines.intercept_asyncio),
+
+    # OpenAI
+    ('openai', openai.intercept_openai),
+
+    # LangChain
+    #('langchain_core.language_models', langchain.intercept_langchain_core_language_models),
+    #('langchain_core.runnables', langchain.intercept_langchain_core_runnables),
+    ('langchain_core.tools', langchain.intercept_langchain_core_tools),
+    ('langchain_community.vectorstores', langchain.intercept_langchain_community_vectorstores),
+    ('langchain_community.embeddings', langchain.intercept_langchain_community_embeddings),
+    ('langchain_openai', langchain.intercept_langchain_openai),
+
+    # LangGraph
+    #('langgraph.pregel', langchain.intercept_langgraph_pregel),
+    #('langgraph.utils.runnable', langchain.intercept_langgraph_utils_runnable),
+
+)

pythonagent/agent/internal/logs.py

@@ -0,0 +1,122 @@
+from __future__ import unicode_literals
+
+import copy
+import logging
+import logging.handlers
+import os.path
+import os
+import re
+from datetime import datetime
+import sys
+from pythonagent import config
+from pythonagent.lib import default_log_formatter, mkdir
+
+LOGGING_MAX_BYTES = 10 * 1024 * 1024
+LOGGING_MAX_NUM_FILES = 5
+
+
+def get_log_level():
+    default_logging_level = logging.WARNING
+    allowed_logging_levels = {'DEBUG': logging.DEBUG,
+                              'INFO': logging.INFO,
+                              'WARNING': logging.WARNING,
+                              'ERROR': logging.ERROR,         # Added for testing
+                              'CRITICAL': logging.CRITICAL    # Added for testing
+                              }
+
+    level = config.LOGGING_LEVEL.upper()
+    ret_val = allowed_logging_levels.get(level, default_logging_level)
+    # NOTSET=0
+    # DEBUG=10
+    # INFO=20
+    # WARN=30
+    # ERROR=40
+    # CRITICAL=50
+    return allowed_logging_levels.get(level, default_logging_level)
+
+
+def get_log_filename():
+    non_alphanumeric = re.compile(r'\W+')
+    sanitize = lambda x: non_alphanumeric.sub('_', x)
+    filename = 'nd_trace_'+'_'.join(
+        map(sanitize, [config.APP_NAME.lower(), config.TIER.lower(), datetime.now().strftime("%Y%m%d%H%M%S"), str(os.getpid())])) + '.log_0'
+    return os.path.join(config.LOGS_DIR, filename)
+
+
+def debug_enabled(logger):
+    for handler in logger.handlers:
+        if handler.__class__ is logging.StreamHandler:
+            return True
+    return False
+
+
+def enable_debug(logger):
+    logger.setLevel(logging.DEBUG)
+
+    for handler in logger.handlers:
+        handler.setLevel(logging.DEBUG)
+
+    stream_handler = logging.StreamHandler()
+    stream_handler.setLevel(logging.DEBUG)
+    stream_handler.setFormatter(default_log_formatter)
+    logger.addHandler(stream_handler)
+
+
+def disable_debug(logger):
+    level = get_log_level()
+    logger.setLevel(level)
+
+    handlers = copy.copy(logger.handlers)
+    logger.handlers = []
+    for handler in handlers:
+        if handler.__class__ is not logging.StreamHandler:
+            handler.setLevel(level)
+            logger.addHandler(handler)
+
+
+def configure_logging():
+    try:
+        logger = logging.getLogger('pythonagent.agent')
+        level = get_log_level()
+        print("Logging level:", level)
+        logger.setLevel(level)
+        path = get_log_filename()
+
+        print("Logging file path name", path)
+
+        agent_env = None
+
+        if "CAV_APP_AGENT_ENV" in os.environ:
+            if os.environ['CAV_APP_AGENT_ENV'] == "AWS_LAMBDA":
+                agent_env = "AWS_LAMBDA"
+            else:
+                agent_env = "NATIVE"
+        else:
+            agent_env = "NATIVE"
+
+        if agent_env == "AWS_LAMBDA":
+            consolHandler = logging.StreamHandler(sys.stdout)
+            consolHandler.setLevel(level)
+            consolHandler.setFormatter(default_log_formatter)
+            logger.addHandler(consolHandler)
+
+        else:
+            mkdir(os.path.dirname(path))
+            rotating_file_handler = logging.handlers.RotatingFileHandler(path, maxBytes=LOGGING_MAX_BYTES,
+                                                                         backupCount=LOGGING_MAX_NUM_FILES - 1)
+            # logging.getLogger('pythonagent.agent').addHandler()
+            rotating_file_handler.setLevel(level)
+            rotating_file_handler.setFormatter(default_log_formatter)
+            logger.addHandler(rotating_file_handler)
+
+        if config.DEBUG_LOG:
+            enable_debug(logger)
+
+        has_handlers = logger.hasHandlers()
+        logger.warning("has handlers {}".format(str(has_handlers)))
+        logger.propagate = False
+        logger.warning("has handlers {}".format(str(has_handlers)))
+
+
+    except:
+        logging.getLogger('pythonagent.agent').exception('Logging configuration failed.')

pythonagent/agent/internal/metadata/agent_meta_data.py

@@ -0,0 +1,276 @@
+# Purpose: collect a rich, point-in-time snapshot of the monitored Python application/process/
+# deployment environment, for the auto-discovery response's "****Start Metadata****" block
+# (sent from Agent.autodiscovery_py() in agent/internal/agent/agent.py). Mirrors the sibling
+# NodeJS agent's lib/metaData/agentMetaData.js + lib/autoDiscovery.js buildMetadataBlock(), adapted
+# to Python's runtime (no package.json/npm, no cluster module - platform/os/proc_compat stand in).
+#
+# Deliberately stdlib + /proc only (no psutil or other external dependency) - same constraint as
+# the sibling proc_compat.py this module builds on, and it keeps a metadata-collection failure
+# (e.g. a missing optional dependency) from ever being able to break auto-discovery.
+#
+# Every value collected here is synchronous and local to this process - no shelling out, no
+# network calls - so calling collect_metadata()/build_metadata_block() cannot add meaningful
+# latency to a discovery response. collect_metadata() returns a plain dict; callers are
+# responsible for escaping (escape_metadata_value) and formatting into "key=value;" lines -
+# build_metadata_block() does that end-to-end for the auto-discovery caller.
+
+import os
+import re
+import sys
+import platform
+import logging
+
+from pythonagent.agent.internal.proc_compat import get_process_name, get_virtual_memory, get_rss_bytes
+
+logger = logging.getLogger('pythonagent.agent')
+
+
+_VERSION_LINE_PATTERN = re.compile(r'^\s*VERSION\s+(\S+)', re.IGNORECASE | re.MULTILINE)
+_BUILD_LINE_PATTERN = re.compile(r'^\s*BUILD\s+(\S+)', re.IGNORECASE | re.MULTILINE)
+
+
+def _resolve_agent_version():
+    """Resolve this agent's actual shipped version/build from the "VERSION x.y.z / BUILD n" file
+    that install.sh lays down at $NDHOME/python/version - the same convention the sibling
+    .NET/native agents use for their own top-level 'version' file (see e.g.
+    cavisson_python_agent/version, dotnetagent/agent/version). This is the authoritative,
+    release-tracked version; the 'pythonagent' pip distribution's own version (setup.py) is just a
+    placeholder ("0.0.1", "A small example package") and not meaningful here.
+
+    Returns (version, build) - either may be None (field omitted) if NDHOME isn't set, the file is
+    missing, or a line can't be parsed - never raises, since this must not be able to block agent
+    metadata collection.
+    """
+    ndhome = os.environ.get('NDHOME')
+    if not ndhome:
+        return None, None
+    try:
+        with open(os.path.join(ndhome, 'python', 'version'), 'r') as f:
+            contents = f.read()
+    except (IOError, OSError):
+        return None, None
+
+    version_match = _VERSION_LINE_PATTERN.search(contents)
+    build_match = _BUILD_LINE_PATTERN.search(contents)
+    return (
+        version_match.group(1) if version_match else None,
+        build_match.group(1) if build_match else None,
+    )
+
+
+# Resolved once at import time - the installed version file can't change within a process lifetime.
+_AGENT_VERSION, _AGENT_BUILD = _resolve_agent_version()
+
+# Env var keys whose VALUE gets redacted in the metadata block - matched case-insensitively
+# against the key name, not the value, since we can't know a value is secret just by looking at
+# it. This list intentionally errs toward over-redacting common secret-naming conventions.
+_SECRET_KEY_PATTERN = re.compile(r'key|secret|token|password|pwd|credential|auth|apikey|connectionstring|private', re.IGNORECASE)
+_REDACTED_VALUE = '***REDACTED***'
+
+# Env var keys dropped entirely (not just redacted) - not secrets, just noisy shell/terminal
+# config that adds no diagnostic value and is heavy on ";"/"=".
+_EXCLUDED_ENV_KEYS = re.compile(r'^(LS_COLORS|LESSOPEN|LESSCLOSE|XMODIFIERS|DBUS_SESSION_BUS_ADDRESS)$', re.IGNORECASE)
+
+
+def _add_if_defined(target, key, value):
+    if value is None or value == '':
+        return
+    target[key] = value
+
+
+def _get_process_uptime_sec():
+    """Return seconds since this process started, via /proc only (Linux). Best-effort - returns
+    None on any platform/parse failure rather than raising, since it's cosmetic metadata."""
+    try:
+        clk_tck = os.sysconf('SC_CLK_TCK')
+        with open('/proc/uptime', 'r') as f:
+            system_uptime = float(f.read().split()[0])
+        with open('/proc/self/stat', 'r') as f:
+            # Field 22 (starttime, in clock ticks since boot) - skip past the "(comm)" field
+            # since it may itself contain spaces/parens.
+            stat = f.read()
+            fields = stat[stat.rfind(')') + 2:].split()
+            starttime_ticks = float(fields[19])
+        process_start_uptime = starttime_ticks / clk_tck
+        return int(system_uptime - process_start_uptime)
+    except (IOError, OSError, ValueError, IndexError, AttributeError):
+        return None
+
+
+def _collect_agent_identity(meta, agent):
+    _add_if_defined(meta, 'agentType', 'Python')
+    _add_if_defined(meta, 'agentVersion', _AGENT_VERSION)
+    _add_if_defined(meta, 'agentBuild', _AGENT_BUILD)
+    _add_if_defined(meta, 'agentTier', getattr(agent, 'tier_name', None))
+    _add_if_defined(meta, 'agentServer', getattr(agent, 'server_name', None))
+    _add_if_defined(meta, 'agentInstance', getattr(agent, 'instance_name', None))
+    _add_if_defined(meta, 'agentEnv', getattr(agent, 'cav_env', None))
+    _add_if_defined(meta, 'ndHome', os.environ.get('NDHOME'))
+    _add_if_defined(meta, 'testRunning', getattr(agent, 'test_running', None))
+    _add_if_defined(meta, 'nfEnabled', getattr(agent, 'nf_enabled', None))
+
+
+def _collect_app_identity(meta):
+    try:
+        from pythonagent import config
+        _add_if_defined(meta, 'appName', getattr(config, 'APP_NAME', None))
+        _add_if_defined(meta, 'wsgiModule', getattr(config, 'WSGI_MODULE', None))
+        _add_if_defined(meta, 'wsgiCallable', getattr(config, 'WSGI_CALLABLE_OBJECT', None))
+        _add_if_defined(meta, 'asgiModule', getattr(config, 'ASGI_MODULE', None))
+        _add_if_defined(meta, 'asgiCallable', getattr(config, 'ASGI_CALLABLE_OBJECT', None))
+    except Exception as e:
+        logger.warning('agent_meta_data | Error collecting app identity from config : %s', e)
+
+    try:
+        _add_if_defined(meta, 'appEntryPoint', get_process_name())
+        _add_if_defined(meta, 'appCwd', os.getcwd())
+    except Exception as e:
+        logger.warning('agent_meta_data | Error collecting app identity : %s', e)
+
+
+def _collect_runtime_versions(meta):
+    try:
+        _add_if_defined(meta, 'pythonVersion', platform.python_version())
+        _add_if_defined(meta, 'pythonImplementation', platform.python_implementation())
+        _add_if_defined(meta, 'pythonCompiler', platform.python_compiler())
+        _add_if_defined(meta, 'pythonBuild', ' '.join(platform.python_build()))
+        _add_if_defined(meta, 'isVirtualenv', hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix))
+    except Exception as e:
+        logger.warning('agent_meta_data | Error collecting runtime versions : %s', e)
+
+
+def _collect_os_info(meta):
+    try:
+        _add_if_defined(meta, 'osType', platform.system())
+        _add_if_defined(meta, 'osPlatform', sys.platform)
+        _add_if_defined(meta, 'osRelease', platform.release())
+        _add_if_defined(meta, 'osArch', platform.machine())
+        _add_if_defined(meta, 'hostname', platform.node())
+        _add_if_defined(meta, 'cpuCount', os.cpu_count() if hasattr(os, 'cpu_count') else None)
+
+        total, available, _percent, _used, _free = get_virtual_memory()
+        _add_if_defined(meta, 'totalMemBytes', total or None)
+        _add_if_defined(meta, 'freeMemBytesAtDiscovery', available or None)
+
+        try:
+            with open('/proc/uptime', 'r') as f:
+                _add_if_defined(meta, 'osUptimeSec', int(float(f.read().split()[0])))
+        except (IOError, OSError, ValueError, IndexError):
+            pass
+    except Exception as e:
+        logger.warning('agent_meta_data | Error collecting OS info : %s', e)
+
+
+def _collect_process_snapshot(meta):
+    try:
+        _add_if_defined(meta, 'pid', os.getpid())
+        _add_if_defined(meta, 'ppid', os.getppid() if hasattr(os, 'getppid') else None)
+        _add_if_defined(meta, 'execPath', sys.executable)
+        # Deliberately interpreter flags/warnoptions (sys.flags/sys.warnoptions), NOT sys.argv[1:] -
+        # the application's own command-line arguments may include secrets, mirroring the NodeJS
+        # agent's choice of process.execArgv over process.argv.
+        _add_if_defined(meta, 'pythonWarnOptions', ' '.join(sys.warnoptions) if sys.warnoptions else None)
+        _add_if_defined(meta, 'processUptimeSec', _get_process_uptime_sec())
+        _add_if_defined(meta, 'memRssBytes', get_rss_bytes() or None)
+    except Exception as e:
+        logger.warning('agent_meta_data | Error collecting process snapshot : %s', e)
+
+
+def _collect_deployment_hints(meta):
+    try:
+        env = os.environ
+        is_docker = False
+        try:
+            is_docker = os.path.exists('/.dockerenv')
+        except OSError:
+            pass
+
+        _add_if_defined(meta, 'isDocker', is_docker)
+        _add_if_defined(meta, 'isKubernetes', bool(env.get('KUBERNETES_SERVICE_HOST')))
+        _add_if_defined(meta, 'isAwsLambda', bool(env.get('AWS_LAMBDA_FUNCTION_NAME') or env.get('AWS_EXECUTION_ENV')))
+        _add_if_defined(meta, 'isEcs', bool(env.get('ECS_CONTAINER_METADATA_URI')))
+        _add_if_defined(meta, 'isAzureAppService', bool(env.get('WEBSITE_INSTANCE_ID')))
+        _add_if_defined(meta, 'isCloudRun', bool(env.get('K_SERVICE')))
+        _add_if_defined(meta, 'isHeroku', bool(env.get('DYNO')))
+        _add_if_defined(meta, 'isGunicorn', bool(env.get('SERVER_SOFTWARE', '').lower().startswith('gunicorn')))
+        _add_if_defined(meta, 'isUwsgi', bool(env.get('UWSGI_ORIGINAL_PROC_NAME')) or 'uwsgi' in sys.modules)
+
+        # Specific identifying values (operationally useful, not secret-shaped) - only meaningful
+        # when the corresponding hint above is true.
+        _add_if_defined(meta, 'k8sServiceHost', env.get('KUBERNETES_SERVICE_HOST'))
+        _add_if_defined(meta, 'lambdaFunctionName', env.get('AWS_LAMBDA_FUNCTION_NAME'))
+        _add_if_defined(meta, 'dyno', env.get('DYNO'))
+    except Exception as e:
+        logger.warning('agent_meta_data | Error collecting deployment hints : %s', e)
+
+
+def _collect_launch_context(meta):
+    try:
+        env = os.environ
+        _add_if_defined(meta, 'virtualEnv', env.get('VIRTUAL_ENV'))
+        _add_if_defined(meta, 'condaEnv', env.get('CONDA_DEFAULT_ENV'))
+        _add_if_defined(meta, 'pythonPath', env.get('PYTHONPATH'))
+
+        # Multi-worker context (gunicorn/uwsgi pre-fork workers have no direct equivalent of
+        # NodeJS's cluster.worker.id, so surface whatever the WSGI server exposes via env).
+        _add_if_defined(meta, 'workerId', env.get('APP_WORKER_ID') or env.get('UWSGI_WORKER_ID'))
+    except Exception as e:
+        logger.warning('agent_meta_data | Error collecting launch context : %s', e)
+
+
+def _collect_environment_variables(meta):
+    try:
+        for key, value in os.environ.items():
+            if _EXCLUDED_ENV_KEYS.match(key):
+                continue
+            meta['env.' + key] = _REDACTED_VALUE if _SECRET_KEY_PATTERN.search(key) else value
+    except Exception as e:
+        logger.warning('agent_meta_data | Error collecting environment variables : %s', e)
+
+
+def collect_metadata(agent):
+    """Return a plain dict of metadata key -> raw (unescaped) value for the given Agent instance.
+
+    None/''-valued entries are never added, so callers can iterate the dict directly without
+    extra filtering.
+    """
+    meta = {}
+    _collect_agent_identity(meta, agent)
+    _collect_app_identity(meta)
+    _collect_runtime_versions(meta)
+    _collect_os_info(meta)
+    _collect_process_snapshot(meta)
+    _collect_deployment_hints(meta)
+    _collect_launch_context(meta)
+    _collect_environment_variables(meta)
+    return meta
+
+
+def escape_metadata_value(value):
+    """Escape a value for embedding in a "key=value;" metadata line.
+
+    Mirrors the NodeJS agent's AgentSetting.escapeMetadataValue - a value containing ';', '=' or
+    a newline (env vars are the likely source) must not be able to corrupt the surrounding
+    "key=value;"-per-line, single-block message format.
+    """
+    text = value if isinstance(value, str) else str(value)
+    return text.replace('\\', '\\\\').replace(';', '\\;').replace('=', '\\=').replace('\n', '\\n').replace('\r', '\\r')
+
+
+def build_metadata_block(agent):
+    """Build the "****Start Metadata****...****End Metadata****" block for the auto-discovery
+    response, mirroring the NodeJS agent's autoDiscovery.js buildMetadataBlock().
+
+    Always returns a well-formed (possibly empty) block rather than raising, so a metadata
+    collection failure never breaks the rest of the auto-discovery response.
+    """
+    lines = []
+    try:
+        meta = collect_metadata(agent)
+        for key, value in meta.items():
+            if value is None:
+                continue
+            lines.append(key + '=' + escape_metadata_value(value) + ';')
+    except Exception as e:
+        logger.error('agent_meta_data | Error collecting auto-discovery metadata : %s', e)
+    return '****Start Metadata****\n' + ''.join(lines) + '\n****End Metadata****\n'