`agenteye-collector`로 마이그레이션

마이그레이션은 비파괴적입니다. 다운타임과 데이터 손실이 없으며, 짧은 agenteye 이름을 AgentEye CLI에 양도하여 컬렉터 데몬과 CLI가 동일한 머신에서 공존할 수 있게 됩니다. 컬렉터 바이너리가 agenteye에서 agenteye-collector로 이름이 변경되었습니다. 짧은 agenteye 이름은 이제 AgentEye CLI에 속하며, 이는 터미널에서 세션, 이벤트, 평가를 조회하기 위한 별도의 도구입니다. 이 가이드는 기존 컬렉터 설치를 마이그레이션하는 과정을 안내합니다.

변경 사항

	변경 전	변경 후
커맨드 / 바이너리	`agenteye`	`agenteye-collector`
기본 설치 경로	`/usr/local/bin/agenteye`	`/usr/local/bin/agenteye-collector`
서브커맨드	`start`, `flush`, `health`, `update`	`start`, `flush`, `health`
자체 업데이트 (`agenteye update`)	내장 기능	제거됨: 새 바이너리를 다운로드하거나 새 이미지를 pull
설치 스크립트 (`install.sh`)	제공됨	제거됨: 바이너리를 직접 다운로드 (Collector Installation 참고)
`AGENTEYE_TOKEN`	다운로드 및 백그라운드 업데이트 확인에 필요	바이너리/이미지 다운로드에만 필요

설정은 변경되지 않습니다. 동일한 ~/.agenteye/config.json, 동일한 AGENTEYE_URL / AGENTEYE_KEY / AGENTEYE_HOME / TLS 환경 변수, 그리고 동일한 ~/.agenteye/events/ 스풀을 그대로 사용합니다. 설정 파일을 수정할 필요가 없습니다.

이름이 변경된 바이너리를 이전 이름인 agenteye로 실행하면 여전히 동작하지만, stderr에 agenteye-collector로 전환하도록 안내하는 한 줄짜리 지원 중단 경고를 출력합니다.

시작하기 전에

기존 agenteye 설치는 계속 실행됩니다. 업그레이드 직후에도 아무것도 중단되지 않습니다. 신중하게 마이그레이션을 진행한 후 마지막에 이전 바이너리를 제거하세요.
다운타임을 피하려면 다음 순서를 따르세요:
1. 새 agenteye-collector 바이너리를 설치합니다(또는 새 이미지를 pull).
2. 서비스 정의 / 헬스 프로브 / 스크립트를 agenteye-collector를 호출하도록 업데이트합니다.
3. 서비스를 리로드하고 재시작한 후 정상 상태를 확인합니다.
4. 그런 다음에만 이전 /usr/local/bin/agenteye 바이너리를 제거합니다.

1. 새 바이너리 설치

플랫폼에 맞는 아티팩트(agenteye-collector-linux-x86_64, agenteye-collector-darwin-arm64 등; 전체 목록은 Collector Installation → Option A 참고)를 최신 collector/v<version> 릴리스에서 다운로드하여 /usr/local/bin/agenteye-collector에 배치합니다. Docker 사용자: docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (또는 고정된 :v<version> 태그 사용을 권장하며, :latest는 안정 릴리스에만 존재합니다). 설치 확인:

agenteye-collector --version

2. 배포 환경 업데이트

systemd (Linux)

/etc/systemd/system/agenteye-collector.service를 편집하여 ExecStart가 새 바이너리를 가리키도록 합니다:

[Service]
ExecStart=/usr/local/bin/agenteye-collector start

그런 다음 리로드하고 재시작합니다:

sudo systemctl daemon-reload
sudo systemctl restart agenteye-collector
sudo systemctl status agenteye-collector

launchd (macOS)

브랜드 이름 변경: 기존 plist가 이전 경로인 ~/Library/LaunchAgents/host.exosphere.agenteye-collector.plist에 있다면, 파일 이름을 ai.befailproof.agenteye-collector.plist로 변경하고 파일 내부의 <key>Label</key> 값도 새 식별자로 변경한 후 리로드하세요.

~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist에서 첫 번째 ProgramArguments 항목을 /usr/local/bin/agenteye에서 /usr/local/bin/agenteye-collector로 변경한 후 리로드합니다:

launchctl unload ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist
launchctl load   ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist

supervisord

supervisord 프로그램 블록에서 command를 새 바이너리로 설정합니다:

[program:agenteye-collector]
command=/usr/local/bin/agenteye-collector start

그런 다음 supervisorctl reread && supervisorctl update를 실행합니다.

Docker / Kubernetes

새 이미지를 pull합니다(ghcr.io/agenteye-enterprise/collector:beta-latest 또는 고정된 :v<version> 태그 사용을 권장하며, :latest는 안정 릴리스에만 존재합니다). 이미지 엔트리포인트가 이미 agenteye-collector이므로, start 서브커맨드와 함께 기존 docker run 명령을 변경 없이 그대로 사용할 수 있습니다. 중요: 헬스 프로브를 업데이트하세요. 바이너리 이름으로 실행하는 Kubernetes liveness/readiness 프로브(또는 docker exec)를 사용하는 경우, 커맨드를 agenteye-collector로 변경해야 합니다:

livenessProbe:
  exec:
    command: ["agenteye-collector", "health"]

새 이미지에는 agenteye 별칭이 포함되지 않으므로, 여전히 agenteye를 호출하는 프로브는 실패합니다. 새 이미지와 동일한 롤아웃에서 프로브를 업데이트하세요.

Cron / 수동 스크립트

agenteye start|flush|health 호출을 해당하는 agenteye-collector start|flush|health 커맨드로 교체합니다. agenteye update cron 작업은 모두 삭제하세요. 해당 서브커맨드는 더 이상 존재하지 않습니다(이후 업그레이드 방법 참고).

3. 이전 바이너리 제거 (마지막 단계)

서비스가 agenteye-collector로 실행되고 정상 상태를 보고하면:

sudo rm /usr/local/bin/agenteye

AgentEye CLI도 함께 사용하는 경우 이 단계가 특히 중요합니다. CLI는 자체적으로 agenteye 커맨드를 설치하며, 이전 컬렉터 바이너리가 /usr/local/bin/agenteye에 남아 있으면 PATH에서 agenteye 이름이 모호해집니다.

이후 업그레이드 방법

컬렉터는 더 이상 자체 업데이트를 지원하지 않습니다. 업그레이드 방법:

바이너리: 플랫폼에 맞는 새 아티팩트(예: agenteye-collector-linux-x86_64; 전체 목록은 Collector Installation → Option A 참고)를 다운로드하여 /usr/local/bin/agenteye-collector를 교체한 후 서비스를 재시작합니다.
Docker: docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (또는 고정된 :v<version> 태그 사용을 권장하며, :latest는 안정 릴리스에만 존재합니다)를 실행한 후 컨테이너를 재생성합니다.

AGENTEYE_TOKEN은 프라이빗 릴리스 저장소에서 다운로드하는 데 여전히 필요하지만, 실행 중인 데몬에서는 더 이상 필요하지 않습니다.

확인

agenteye-collector --version    # 새 바이너리가 PATH에 있는지 확인
agenteye-collector health       # 종료 코드 0 = 정상
agenteye-collector flush        # 대기 중인 이벤트를 전달하고 정상 종료

이후 대시보드에 새 이벤트가 나타나는지 확인하세요.

롤백

마이그레이션은 비파괴적입니다. 롤백이 필요한 경우, (아직 제거하지 않은 경우) 서비스 정의를 이전 /usr/local/bin/agenteye 바이너리로 다시 지정하고 재시작하세요. 이벤트 스풀과 설정은 공유되며 영향을 받지 않습니다.

문제 해결

증상	원인	해결 방법
실행할 때마다 `warning: the collector binary is now agenteye-collector …` 출력	이전 `agenteye` 이름으로 바이너리를 호출하고 있음	`agenteye-collector`를 사용하도록 변경하고, 서비스 파일과 스크립트를 업데이트하세요.
systemd 실패: `.../agenteye: No such file or directory`	`ExecStart`를 업데이트하기 전에 이전 바이너리를 제거했음	`ExecStart=/usr/local/bin/agenteye-collector start`로 설정한 후 `sudo systemctl daemon-reload`를 실행하세요.
이미지 업그레이드 후 Kubernetes 파드가 크래시 루프	liveness 프로브가 여전히 `agenteye`를 실행하고 있음	프로브 커맨드를 `["agenteye-collector", "health"]`로 변경하세요.
`agenteye: command not found`, 하지만 `agenteye-collector`는 동작함	스크립트/별칭이 이전 이름을 참조하고 있음	`agenteye-collector`로 업데이트하세요.
`agenteye`를 실행하면 컬렉터가 아닌 CLI가 시작됨	AgentEye CLI가 설치되어 있으며 `agenteye`를 소유하고 있음	데몬에는 `agenteye-collector`를 사용하고, `/usr/local/bin/agenteye`에 남아 있는 이전 컬렉터 바이너리를 제거하세요.

​변경 사항

​시작하기 전에

​1. 새 바이너리 설치

​2. 배포 환경 업데이트

​systemd (Linux)

​launchd (macOS)

​supervisord

​Docker / Kubernetes

​Cron / 수동 스크립트

​3. 이전 바이너리 제거 (마지막 단계)

​이후 업그레이드 방법

​확인

​롤백

​문제 해결