whatap-python 2.1.4rc1__py3-none-any.whl → 2.2.1__py3-none-any.whl

whatap/__init__.py

@@ -117,6 +117,37 @@ def whatap_print(*args):
             message = " ".join(args)
             print(message)
 
+
+def whatap_error_log(msg, log_id='WHATAP_AGENT_ERROR'):
+    """에이전트 시작 오류를 프로세스 로그(stdout)와 hook.log 양쪽에 동일하게 노출한다.
+
+    hook.log FileHandler 는 Configure.load(display=True)->Logger() 시점에 붙는데,
+    go() 스레드가 config() 보다 먼저 도는 경로(자동 attach)나 start_agent 경로에서는
+    아직 핸들러가 없을 수 있다. 그 경우에도 오류가 유실되지 않도록, 핸들러가 없으면
+    whatap-hook.log 에 직접 append 한다."""
+    # 1) 프로세스 로그 (사용자 애플리케이션 stdout)
+    whatap_print(msg)
+
+    # 2) hook.log
+    try:
+        if logging.handlers:
+            logging.error(msg, extra={'id': log_id})
+            return
+    except Exception:
+        pass
+
+    # FileHandler 미부착: whatap-hook.log 에 직접 기록
+    try:
+        logs_dir = os.environ.get('WHATAP_LOGS') or \
+            os.path.join(os.environ.get('WHATAP_HOME', '.'), 'logs')
+        if not os.path.exists(logs_dir):
+            os.makedirs(logs_dir)
+        with open(os.path.join(logs_dir, LOG_FILE_NAME), 'a') as f:
+            f.write('[{0}] : {1} - {2}\n'.format(
+                time.strftime(LOGGING_DATE_FORMAT), log_id, msg))
+    except Exception as e:
+        whatap_print('WHATAP: hook.log write failed: {}'.format(e))
+
 class Logger(object):
     def __init__(self):
         self.logger = logging
@@ -291,6 +322,18 @@ def config(home):
             from whatap.conf.license import License
             conf.PCODE = License.getProjectCode(conf.license)
 
+        # LLM 채널은 자기 프로젝트 코드를 가진다. LLM 트랜잭션(is_llm=1)은 LLM Go Agent
+        # 소켓으로만 나가므로 결합 좌표에 APM PCODE 를 실으면 서버가 호출자를 엉뚱한
+        # 프로젝트에서 찾는다(conf.pcode_of 참조). getProjectCode 는 키 문자열 파싱이라
+        # 서버 왕복이 없고, apm_enabled=false 인 LLM 전용 배포에서도 해소된다.
+        llm_key = str(getattr(conf, 'llm_accesskey', '') or '').strip()
+        if llm_key:
+            try:
+                from whatap.conf.license import License
+                conf.LLM_PCODE = License.getProjectCode(llm_key)
+            except Exception as e:
+                whatap_print('WHATAP: LLM PCODE RESOLVE ERROR: {}'.format(e))
+
         import whatap.counter
 
         hooks(home)
@@ -335,11 +378,20 @@ def _is_instrumentation_ignored(definition_key, ignore_set):
 def hooks(home):
     ignore_set = _build_ignore_instrumentation_set()
     skipped_keys = []
+    # LLM 계측은 llm_enabled 일 때만 **등록**한다. instrument_* 함수들도 각자
+    # llm_enabled 를 보고 되돌아가지만, 등록만 해둬도 대상 모듈이 로드되는 순간
+    # import 훅이 ``whatap.llm.*`` 서브트리를 통째로 끌어온다 — 켜지도 않은 기능
+    # 때문에. ``botocore.client``(Bedrock) 처럼 LLM 과 무관한 앱도 흔히 쓰는 모듈이
+    # 대상에 들어오면서 이 비용이 실제로 문제가 된다.
+    # conf.init() 이 hooks() 보다 먼저 돌므로 여기서 llm_enabled 는 이미 확정이다.
+    llm_enabled = bool(getattr(conf, 'llm_enabled', False))
     try:
         for key, value_list in DEFINITION.items():
             if _is_instrumentation_ignored(key, ignore_set):
                 skipped_keys.append(key)
                 continue
+            if key.startswith('llm.') and not llm_enabled:
+                continue
             for value in value_list:
                 if len(value) >= 3 and isinstance(value[2], str):
                     module_path = value[2]
@@ -366,47 +418,61 @@ def hooks(home):
                 from whatap.trace.mod.logging import instrument_logging
                 instrument_logging(logging_module)
 
+            # 한 모듈에 여러 패턴 계열(스텝=instrument_plugin / 워크플로우=instrument_workflow
+            # / 트랜잭션=instrument_service)이 공존할 수 있도록, IMPORT_HOOKS[모듈]에
+            # 인스트루먼터를 각자의 class_defs 와 함께 리스트로 누적한다. 과거엔 단일 dict 라
+            # 뒤 계열이 앞을 덮어써서 같은 모듈에 두 패턴(예: predict=트랜잭션 + 헬퍼=스텝)을
+            # 못 걸었다.
+            def _register_pattern_hook(module_name, class_def, def_name, mod_path):
+                if not PLUGIN.get(module_name):
+                    PLUGIN[module_name] = []
+                if class_def not in PLUGIN[module_name]:
+                    PLUGIN[module_name].append(class_def)  # 호환용(외부 참조)
+                existing = IMPORT_HOOKS.get(module_name)
+                if isinstance(existing, list):
+                    entry_list = existing
+                elif isinstance(existing, dict):
+                    entry_list = [existing]
+                    IMPORT_HOOKS[module_name] = entry_list
+                else:
+                    entry_list = []
+                    IMPORT_HOOKS[module_name] = entry_list
+                for e in entry_list:
+                    if isinstance(e, dict) and e.get('def') == def_name \
+                            and e.get('module') == mod_path:
+                        e.setdefault('class_defs', []).append(class_def)
+                        return
+                entry_list.append({'def': def_name, 'module': mod_path,
+                                   'class_defs': [class_def]})
+
             if conf.hook_method_patterns:
-                from whatap.trace.mod.plugin import instrument_plugin
-                patterns = conf.hook_method_patterns.split(',')
-                for pattern in patterns:
-                    pattern=pattern.strip()
-                
-                    module_name, class_def = pattern.split(':')
-                    if not PLUGIN.get(module_name):
-                        PLUGIN[module_name] = []
-                    PLUGIN[module_name].append(class_def)
-                    
-                    DEFINITION["plugin"].append(
-                        (module_name, 'instrument_plugin'))
-                    
-                    key = 'plugin'
-                    for value in DEFINITION[key]:
-                        IMPORT_HOOKS[value[0]] = {'def': value[1],
-                                                  'module': '{0}.{1}.{2}.{3}'.format(
-                                                      'whatap',
-                                                      'trace',
-                                                      'mod',
-                                                      key)}
-
-            # 서비스(트랜잭션) 진입점 자동 래핑 (conf 방법). hook_method_patterns 와 같은
-            # import-hook 플러밍, 래퍼만 트랜잭션 open/close (whatap.trace.mod.hook_service_patterns).
-            # @method_profiling 을 소스 수정 없이 conf 로 적용하는 경로.
+                for pattern in conf.hook_method_patterns.split(','):
+                    pattern = pattern.strip()
+                    if not pattern or ':' not in pattern:
+                        continue
+                    module_name, class_def = pattern.split(':', 1)
+                    _register_pattern_hook(module_name.strip(), class_def.strip(),
+                                           'instrument_plugin', 'whatap.trace.mod.plugin')
+
+            # LLM 워크플로우 경계 자동 래핑 (conf 방법). 래퍼만 워크플로우 open/close.
+            if conf.workflow_method_patterns:
+                for pattern in conf.workflow_method_patterns.split(','):
+                    pattern = pattern.strip()
+                    if not pattern or ':' not in pattern:
+                        continue
+                    module_name, class_def = pattern.split(':', 1)
+                    _register_pattern_hook(module_name.strip(), class_def.strip(),
+                                           'instrument_workflow', 'whatap.trace.mod.workflow_plugin')
+
+            # 서비스(트랜잭션) 진입점 자동 래핑 (conf 방법). @method_profiling 의 conf 버전.
             if conf.hook_service_patterns:
                 for pattern in conf.hook_service_patterns.split(','):
                     pattern = pattern.strip()
                     if not pattern or ':' not in pattern:
                         continue
                     module_name, class_def = pattern.split(':', 1)
-                    module_name = module_name.strip()
-                    class_def = class_def.strip()
-                    if not PLUGIN.get(module_name):
-                        PLUGIN[module_name] = []
-                    PLUGIN[module_name].append(class_def)
-                    # 대상 모듈이 PLUGIN 에 등록되면 ImportFinder 가 class_defs 패키징.
-                    IMPORT_HOOKS[module_name] = {
-                        'def': 'instrument_service',
-                        'module': 'whatap.trace.mod.hook_service_patterns'}
+                    _register_pattern_hook(module_name.strip(), class_def.strip(),
+                                           'instrument_service', 'whatap.trace.mod.hook_service_patterns')
 
             if conf.standalone_enabled:
                 if conf.standalone_type == 'multiple-transaction':
@@ -420,9 +486,43 @@ def hooks(home):
             logging.debug(e, extra={'id': 'PLUGIN ERROR'})
         finally:
             sys.meta_path.insert(0, ImportFinder())
+            _instrument_already_imported()
             logging.debug('WHATAP AGENT START!', extra={'id': 'WA000'})
 
 
+def _instrument_already_imported():
+    """finder 설치 시점에 **이미 import 돼 있던** 훅 대상을 직접 계측한다.
+
+    ``ImportFinder.find_spec`` 은 import 시스템이 ``sys.modules`` 미스일 때만 호출하므로,
+    finder 설치보다 먼저 로드된 모듈은 훅이 영원히 안 걸린다. 그리고 이 에이전트는 자기
+    부팅에 필요한 모듈(``subprocess`` — 최상단 import, 데몬 기동에 사용)을 finder 설치
+    **전에** 로드하므로, 그 대상은 DEFINITION 에 등록해도 계측되지 않는다.
+
+    앱이 우회할 수 없는 종류의 구멍이다(앱이 할 수 있는 건 에이전트 내부 instrument_*
+    함수를 대신 호출하는 것뿐이고, 그건 자동계측을 쓰는 의미를 없앤다).
+
+    ``load_module`` 을 그대로 재사용하므로 정상 import 경로와 완전히 같은 처리를 받는다
+    (엔트리 리스트/class_defs 패키징 포함). instrument_* 는 멱등이어야 한다 — 이 스윕과 이후의
+    재-import 가 같은 대상을 두 번 건드릴 수 있다.
+    """
+    try:
+        from whatap.trace.trace_import import load_module
+    except Exception as e:
+        logging.info("pre-imported sweep unavailable: %s: %s",
+                     e.__class__.__name__, e, exc_info=True)
+        return
+    for fullname in list(IMPORT_HOOKS.keys()):
+        module = sys.modules.get(fullname)
+        if module is None:
+            continue
+        try:
+            load_module(module, fullname)
+        except Exception as e:
+            # 계측 실패는 조용히 넘기면 "데이터가 안 보인다" 로만 드러난다.
+            logging.info("failed to inject pre-imported %s: %s: %s",
+                         fullname, e.__class__.__name__, e, exc_info=True)
+
+
 def agent():
     home = 'WHATAP_HOME'
     whatap_home = os.environ.get(home)
@@ -446,14 +546,28 @@ def agent():
             llm_enabled = preview_whatap_conf("llm_enabled")
 
             if apm_enabled == 'true':
-                t = threading.Thread(target=go)
-                t.setDaemon(True)
-                t.start()
+                if sys.platform.startswith('linux'):
+                    # Publish native ownership before a short-lived interpreter
+                    # can exit. This does not wait for collector/TCP readiness.
+                    go()
+                else:
+                    t = threading.Thread(target=go)
+                    t.setDaemon(True)
+                    t.start()
 
             if llm_enabled == 'true':
-                t = threading.Thread(target=go, kwargs={'llm': True})
-                t.setDaemon(True)
-                t.start()
+                # llm_enabled=true 라도 LLM 채널 자격증명(llm_accesskey)이 없으면 LLM
+                # 에이전트를 띄우지 않는다. (env 로 플래그만 켜진 경우의 오작동 방지 —
+                # llm_accesskey/LLM 서버 호스트 없이 LLM 모드로 도는 것을 막는다.)
+                llm_accesskey = (preview_whatap_conf("llm_accesskey")
+                                 or os.environ.get("llm_accesskey"))
+                if llm_accesskey:
+                    t = threading.Thread(target=go, kwargs={'llm': True})
+                    t.setDaemon(True)
+                    t.start()
+                else:
+                    whatap_print("WHATAP: llm_enabled=true 이나 llm_accesskey 가 "
+                                 "없어 LLM 에이전트 기동을 건너뜁니다")
 
         config(home)
 
@@ -464,14 +578,135 @@ ARCH = {
     'ARM': 'arm',
     'AArch64': 'arm64',
     'arm64': 'arm64',
-    'aarch64': 'arm64'
+    'aarch64': 'arm64',
+    # Windows 의 platform.machine() 은 **대문자**로 돌려준다('AMD64'/'ARM64').
+    # Windows 는 arch 하위 디렉토리를 쓰지 않아 지금은 이 표를 안 타지만, 빠져 있으면
+    # 누가 조회하는 순간 KeyError 로 기동이 통째로 죽는 종류의 구멍이라 채워 둔다.
+    'AMD64': 'amd64',
+    'ARM64': 'arm64',
+    'i386': '386',
 }
 
 AGENT_NAME = 'whatap_python'
 
 
+def agent_binary_name():
+    """OS 별 에이전트 실행 파일 이름."""
+    return AGENT_NAME + '.exe' if sys.platform == 'win32' else AGENT_NAME
+
+
+def llm_agent_reldir():
+    """LLM 전용 ``whatap_python`` 이 놓이는 ``$WHATAP_HOME`` 하위 상대경로.
+
+    Unix 계열은 ``<os>/<arch>`` (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64).
+    **Windows 는 arch 하위를 쓰지 않는다** — x64 하나면 ARM64 Windows 에서도 에뮬레이션
+    으로 돌아서 아키텍처별 빌드를 나눌 이유가 없다. 번들 APM 쪽
+    ``whatap/agent/windows/`` 가 평평한 것과 같은 이유이고, 같은 모양이다.
+
+    반환: ``(상대경로, 사유)``. 상대경로가 None 이면 사유에 왜 못 구하는지가 담긴다.
+    """
+    system = platform.system().lower()
+    if sys.platform == 'win32':
+        return system, ''
+    machine = platform.machine()
+    arch = ARCH.get(machine)
+    if not arch:
+        return None, ('unsupported architecture {0!r} for the LLM agent '
+                      '(known: {1})'.format(machine, ', '.join(sorted(set(ARCH.values())))))
+    return os.path.join(system, arch), ''
+
+
+def llm_agent_path():
+    """LLM 전용 ``whatap_python`` 의 배포 위치. @see ``llm_agent_reldir``
+
+    반환: ``(경로, 사유)``. 경로가 None 이면 사유에 왜 못 쓰는지가 담긴다.
+    """
+    reldir, reason = llm_agent_reldir()
+    if reldir is None:
+        return None, reason
+    home_path = os.environ.get('WHATAP_HOME')
+    if not home_path:
+        return None, 'WHATAP_HOME is not set'
+    path = os.path.join(home_path, reldir, agent_binary_name())
+    if not os.path.exists(path):
+        return None, ('LLM agent binary not found: {0} '
+                      '(place the LLM {1} under $WHATAP_HOME/{2}/)'.format(
+                          path, agent_binary_name(), reldir.replace(os.sep, '/')))
+    return path, ''
+
+
+
+def _native_agent_spec(opts):
+    from whatap.util.native_process import AgentSpec
+    source = os.path.join(os.path.dirname(__file__), 'agent', 'linux',
+                          ARCH[platform.machine()], AGENT_NAME)
+    env = os.environ.copy()
+    env.update(opts)
+    return AgentSpec(os.environ['WHATAP_HOME'], source, env)
+
+
+def _native_agent_log_path():
+    return os.path.join(os.environ.get('WHATAP_HOME', '.'), 'logs', AGENT_NAME + '.log')
+
+
+def _open_native_agent_log():
+    # managed 경로는 PIPE 를 읽지 않으므로 네이티브 stdout/stderr 를 파일로 남겨
+    # 기동 직후 실패 원인을 추적할 수 있게 한다.
+    try:
+        log_path = _native_agent_log_path()
+        os.makedirs(os.path.dirname(log_path), exist_ok=True)
+        return open(log_path, 'ab')
+    except Exception as e:
+        whatap_print('WHATAP: native agent log open failed: %s' % e)
+        return subprocess.DEVNULL
+
 
 def go(batch=False, opts={}, llm=False):
+    if sys.platform.startswith('linux') and not batch and not llm:
+        from whatap.util.native_process import FAILED, ensure_agent_running
+
+        def on_child_exit(pid, exit_code):
+            whatap_error_log(
+                'WHATAP: native APM exited (PID: {}, exit code: {}, log: {})'.format(
+                    pid, exit_code, _native_agent_log_path()),
+                log_id='WHATAP_AGENT_EXITED')
+
+        try:
+            spec = _native_agent_spec(opts)
+            result = ensure_agent_running(
+                spec, lambda: _start_go(batch, opts, llm, managed=True),
+                on_child_exit=on_child_exit)
+            if result.status == FAILED:
+                whatap_error_log('WHATAP: native APM startup failed',
+                                 log_id='WHATAP_AGENT_START_FAILED')
+            else:
+                whatap_print('WHATAP: native APM {} (PID: {})'.format(
+                    result.status, result.pid))
+        except Exception as e:
+            whatap_error_log('WHATAP: native APM startup failed: {}'.format(e),
+                             log_id='WHATAP_AGENT_START_FAILED')
+        return
+    return _start_go(batch, opts, llm)
+
+
+def _start_go(batch=False, opts={}, llm=False, managed=False):
+    # LLM 에이전트는 전용 whatap_python 이 $WHATAP_HOME 하위에 따로 배포된다
+    # (unix 는 <os>/<arch>, windows 는 windows/ — @see llm_agent_reldir).
+    # **OS 로 막지 않는다** — 그 자리에 바이너리가 놓였는지로 판단한다(그래야 windows
+    # 빌드가 배포되는 순간 코드 변경 없이 살아난다).
+    #
+    # 여기서 미리 걸러야 하는 이유: 그냥 흘려보내면 배포 분기로 빠져 **번들 APM
+    # 바이너리**를 골라 ``--llm`` 으로 띄우고, 심지어 APM 과 같은
+    # ``$WHATAP_HOME/whatap_python`` 에 배포해 서로를 덮는다(둘은 다른 바이너리다).
+    llm_agent_cmd = None
+    if llm:
+        llm_agent_cmd, reason = llm_agent_path()
+        if llm_agent_cmd is None:
+            whatap_error_log(
+                'WHATAP: skipping LLM agent start — {0}'.format(reason),
+                log_id='WHATAP_LLM_AGENT_UNAVAILABLE')
+            return
+
     newenv=os.environ.copy()
     newenv['WHATAP_VERSION'] = build.version
     newenv['whatap.start'] = str(DateUtil.now())
@@ -514,7 +749,7 @@ def go(batch=False, opts={}, llm=False):
         return ''
 
     pid = read_file(home, file_name)
-    if pid and get_pname(pid).find('whatap_python') >= 0:
+    if not managed and pid and get_pname(pid).find('whatap_python') >= 0:
         if sys.platform == 'win32':
             # Windows: Don't kill, just skip
             whatap_print('WHATAP: Agent already running (PID: {}). Skipping duplicate execution.'.format(pid))
@@ -531,48 +766,75 @@ def go(batch=False, opts={}, llm=False):
         home_path= os.environ.get(home)
 
         # Windows uses .exe extension
-        agent_binary_name = AGENT_NAME + '.exe' if sys.platform == 'win32' else AGENT_NAME
-        dest_agent = os.path.join(home_path, agent_binary_name)
-
-        # Try to remove existing binary
-        # Windows: File may still be locked even after waiting, ignore error and use existing binary
-        # Unix/Linux: Removal should always succeed
-        needs_deployment = False
-        if os.path.exists(dest_agent):
-            try:
-                os.remove(dest_agent)
-                needs_deployment = True
-            except (OSError, PermissionError) as e:
-                if sys.platform == 'win32':
-                    # Windows: File is still locked, use existing binary
-                    pass
-                else:
-                    # Unix/Linux: This should not happen
-                    raise
+        binary_name = agent_binary_name()
+
+        # LLM mode runs a dedicated whatap_python binary that ships separately under
+        # $WHATAP_HOME (unix: <os>/<arch>, windows: windows/ — @see llm_agent_reldir).
+        # It is executed in place from there rather than deployed
+        # from the bundled package into $WHATAP_HOME/whatap_python, which the APM
+        # agent uses (the two are distinct binaries and would otherwise clobber each
+        # other). **OS 로 가르지 않는다** — Windows 만 빼면 거기서 APM 바이너리를
+        # 골라 --llm 으로 띄우고 APM 의 배포 경로까지 덮어쓴다.
+        run_in_place = llm
+
+        if run_in_place:
+            # 경로·존재 확인은 _start_go() 진입부의 llm_agent_path() 가 이미 했다(단일 소스).
+            source_agent = llm_agent_cmd
+            # Ensure executable (best effort; ignore on read-only locations)
+            if not os.access(source_agent, os.X_OK):
+                try:
+                    os.chmod(source_agent, 0o755)
+                except OSError as e:
+                    whatap_print('WHATAP: chmod LLM agent binary failed: %s' % e)
+            agent_cmd = source_agent
         else:
-            needs_deployment = True
+            dest_agent = os.path.join(home_path, binary_name)
 
-        # Windows doesn't use architecture subdirectories (only single x64 binary for now)
-        if sys.platform == 'win32':
-            source_cwd = os.path.join(os.path.dirname(__file__), 'agent', 'windows')
-        else:
-            source_cwd = os.path.join(os.path.join(os.path.dirname(__file__), 'agent'), platform.system().lower(),
-                                      ARCH[platform.machine()])
+            # Try to remove existing binary
+            # Windows: File may still be locked even after waiting, ignore error and use existing binary
+            # Unix/Linux: Removal should always succeed
+            needs_deployment = False
+            if os.path.exists(dest_agent):
+                try:
+                    os.remove(dest_agent)
+                    needs_deployment = True
+                except (OSError, PermissionError) as e:
+                    if sys.platform == 'win32':
+                        # Windows: File is still locked, use existing binary
+                        pass
+                    else:
+                        # Unix/Linux: This should not happen
+                        raise
+            else:
+                needs_deployment = True
 
-        source_agent = os.path.join(source_cwd, agent_binary_name)
+            # Windows doesn't use architecture subdirectories (only single x64 binary for now)
+            if sys.platform == 'win32':
+                source_cwd = os.path.join(os.path.dirname(__file__), 'agent', 'windows')
+            else:
+                source_cwd = os.path.join(os.path.join(os.path.dirname(__file__), 'agent'), platform.system().lower(),
+                                          ARCH[platform.machine()])
 
-        # Deploy agent binary only if needed
-        if needs_deployment:
-            # Try symlink first (Unix/Linux or Windows with proper permissions)
-            try:
-                os.symlink(source_agent, dest_agent)
-            except (OSError, NotImplementedError):
-                # Fallback to copy on Windows or when symlink fails
-                import shutil
-                shutil.copy2(source_agent, dest_agent)
-                # Make executable on Unix-like systems
-                if sys.platform != 'win32':
-                    os.chmod(dest_agent, 0o755)
+            source_agent = os.path.join(source_cwd, binary_name)
+
+            # Deploy agent binary only if needed
+            if needs_deployment:
+                # Try symlink first (Unix/Linux or Windows with proper permissions)
+                try:
+                    os.symlink(source_agent, dest_agent)
+                except (OSError, NotImplementedError):
+                    # Fallback to copy on Windows or when symlink fails
+                    import shutil
+                    shutil.copy2(source_agent, dest_agent)
+                    # Make executable on Unix-like systems
+                    if sys.platform != 'win32':
+                        os.chmod(dest_agent, 0o755)
+
+            # Windows uses absolute path, Unix/Linux uses relative path
+            if sys.platform == 'win32':
+                agent_cmd = os.path.join(home_path, binary_name)
+            else:
+                agent_cmd = './{0}'.format(binary_name)
 
         sockfile_path = os.path.join(home_path, 'run')
         if not os.path.exists(sockfile_path):
@@ -581,12 +843,6 @@ def go(batch=False, opts={}, llm=False):
         newenv['WHATAP_PID_FILE'] = file_name
         newenv['PYTHON_PARENT_APP_PID'] = str(os.getpid())
 
-        # Windows uses absolute path, Unix/Linux uses relative path
-        if sys.platform == 'win32':
-            agent_cmd = os.path.join(home_path, agent_binary_name)
-        else:
-            agent_cmd = './{0}'.format(agent_binary_name)
-
         # Windows: Run in background with DETACHED_PROCESS
         # Unix/Linux: Run in background with start_new_session
         # 실행 인자 구성
@@ -638,6 +894,17 @@ def go(batch=False, opts={}, llm=False):
                                            cwd=home_path, env=newenv,
                                            creationflags=DETACHED_PROCESS,
                                            stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        elif managed:
+            go_out = _open_native_agent_log()
+            try:
+                process = subprocess.Popen(cmd_args,
+                                           cwd=home_path, env=newenv,
+                                           start_new_session=True,
+                                           stdout=go_out, stderr=go_out)
+            finally:
+                if go_out is not subprocess.DEVNULL:
+                    go_out.close()
+            return process
         else:
             process = subprocess.Popen(cmd_args,
                                        cwd=home_path, env=newenv,
@@ -657,7 +924,10 @@ def go(batch=False, opts={}, llm=False):
     except Exception as e:
         import traceback
         traceback.print_exc()
-        whatap_print('WHATAP: AGENT ERROR: {}'.format(e))
+        # hook.log + 프로세스 로그 양쪽에 동일하게 노출
+        whatap_error_log(
+            'WHATAP: {0} AGENT ERROR: {1}'.format('LLM' if llm else 'APM', e),
+            log_id='WHATAP_LLM_AGENT_ERROR' if llm else 'WHATAP_AGENT_ERROR')
     else:
         whatap_print('WHATAP: AGENT UP! (process name: {}{})\n'.format(AGENT_NAME, ' --llm' if llm else ''))
 
@@ -695,8 +965,8 @@ def _service_trace(fn, service_name=None):
     """fn 을 하나의 트랜잭션(TX_START~TX_END)으로 감싼 래퍼를 반환한다.
 
     ``@method_profiling`` 데코레이터와 conf ``hook_service_patterns``
-    (whatap.trace.mod.hook_service_patterns) 의 **공용 코어**. 여기엔 agent() 부팅이
-    없다 (데코레이터/부트 경로가 각자 처리).
+    (whatap.trace.mod.hook_service_patterns) 의 **공용 코어**. 여기엔 agent() 부팅이 없다
+    (데코레이터/부트 경로가 각자 처리).
 
     코루틴 함수는 동기 래퍼로 감싸면 트랜잭션이 start_interceptor → 코루틴 생성 →
     end_interceptor 로 즉시 열렸다 닫히고, 실제 본문은 호출자가 await 할 때 트랜잭션
@@ -772,26 +1042,7 @@ def _service_trace(fn, service_name=None):
 
 
 def method_profiling(fn):
-    # NOTE: 의도적으로 _service_trace 를 쓰지 않는다. 이 데코레이터는 이미 배포된
-    # 공개 API 라, 예외 재전파/컨텍스트 정리/async 지원으로 바꾸면 기존 사용자의
-    # 동작이 달라진다. 해당 수정은 dev 에 있고 정식 머지 때 함께 들어온다.
-    def trace(*args, **kwargs):
-        callback = None
-        try:
-            ctx = TraceContext()
-            ctx.service_name=fn.__name__
-            start_interceptor(ctx)
-            callback = fn(*args, **kwargs)
-        except Exception as e:
-            ctx = TraceContextManager.getLocalContext()
-            interceptor_step_error(e, ctx=ctx)
-            interceptor_error_log(ctx.id, e, fn, args, kwargs)
-            logging.debug('WHATAP(@method_profiling): ' + str(e),
-                          extra={'id': 'WA776'}, exc_info=True)
-        finally:
-            ctx = TraceContextManager.getLocalContext()
-            end_interceptor(ctx=ctx)
-            return callback
+    trace = _service_trace(fn)
 
     if not os.environ.get('whatap.enabled'):
         agent()
@@ -966,6 +1217,22 @@ def get_port_number(port=6600, home=os.environ.get('WHATAP_HOME'), lock_file=Non
 
 
 def configPort():
+    if sys.platform.startswith('linux') and preview_whatap_conf('apm_enabled') == 'true':
+        from whatap.util.native_process import acquire_start_lock, configured_channel, find_existing_agent
+        try:
+            spec = _native_agent_spec({})
+            with acquire_start_lock(spec):
+                if find_existing_agent(spec):
+                    # CLI allocation must not rewrite a live bootstrap agent's channel.
+                    return configured_channel(spec.home, spec.environment, include_unix=False)[1]
+                return _config_port()
+        except Exception as e:
+            # 락 타임아웃/다중 인스턴스 등은 CLI 를 죽이지 말고 기존 포트 할당으로 폴백
+            whatap_print('WHATAP: live agent check skipped, falling back to port file: %s' % e)
+    return _config_port()
+
+
+def _config_port():
     # force_net_udp_port가 설정된 경우 lock 파일 무시하고 해당 포트 강제 사용
     force_port_str = preview_whatap_conf("force_net_udp_port")
     if force_port_str and force_port_str not in ('false', 'False'):

whatap/build.py

@@ -1,4 +1,4 @@
 app = 'Python'
 name = 'whatap-python'
-version = '2.1.4rc1'
-release_date = '20260817'
+version = '2.2.1'
+release_date = '20260929'