exemONE api Agent 설치 및 설정

exemONE api Agent(api-agent)는 exemONE 수집 서버에 설치되어 URL 모니터링 등의 수집 기능을 담당하는 에이전트입니다.

전제 조건:
Docker 패키지 기준 v3.0.405.15.0 이상 패키지부터 api-agent가 포함됩니다. 낮은 버전을 사용하는 경우 수동 배포가 필요합니다.
api-agent 설치 대상은 exemONE 수집 서버입니다.

1. 지원 환경

설치 방식	설명
Docker 패키지	exemONE Docker 환경에 api-agent 서비스 컨테이너를 추가하는 방식
Binary 패키지	exemONE Binary 환경에 api-agent 바이너리를 직접 설치하는 방식

2. Docker 패키지 설치

2-1. docker-compose.yml 서비스 블록 추가

파일 경로: $EXEMONE_HOME/docker-compose.yml

아래 서비스 블록을 추가합니다.

api-agent:
  labels:
    io.exem: true
    io.exem.prod: exemone
    io.exem.one.type: application
    io.exem.one.app: api-agent
  container_name: exemone-api-agent
  build:
    context: ${EXEMONE_HOME}/dockerfile/api-agent
    args:
      API_AGENT_IMAGE: ${API_AGENT_IMAGE}
      API_AGENT_VERSION: ${API_AGENT_VERSION}
      EXEMONE_USER_UID: ${EXEMONE_USER_UID}
      EXEMONE_USER_GID: ${EXEMONE_USER_GID}
  deploy:
    resources:
      limits:
        cpus: '1'
        memory: 2g
  volumes:
    - ${EXEMONE_HOME}/containers/exemone-api-agent/configs:/home/exemone/configs
    - ${EXEMONE_HOME}/containers/exemone-api-agent/logs:/home/exemone/logs
  networks:
    - exemone_network
  restart: unless-stopped
  logging: *logging
  security_opt:
    - no-new-privileges

2-2. .env 파일에 이미지 및 버전 기입

파일 경로: $EXEMONE_HOME/.env

API_AGENT_IMAGE=maxgauge/exemone-api-agent
API_AGENT_VERSION=v{버전}

2-3. Dockerfile 추가

파일 경로: $EXEMONE_HOME/dockerfile/api-agent/Dockerfile

ARG  API_AGENT_IMAGE
ARG  API_AGENT_VERSION
FROM ${API_AGENT_IMAGE}:${API_AGENT_VERSION}

ARG  EXEMONE_USER_UID
ARG  EXEMONE_USER_GID

USER root

# 설치 환경에 따른 uid, gid 변경
RUN usermod -u ${EXEMONE_USER_UID} exemone && \
    groupmod -g ${EXEMONE_USER_GID} exemone

USER exemone

2-4. configs 폴더 및 설정 파일 생성

폴더 경로: $EXEMONE_HOME/containers/exemone-api-agent/ 하위에 configs, logs 폴더를 생성합니다.

설정 파일 경로: $EXEMONE_HOME/containers/exemone-api-agent/configs/api-agent.yaml

global:
  agent_id: url_default
  receiver: receiver:9009

log:
  caller: false
  level: info
  file: /home/exemone/logs/agent.log

2-5. api-agent image load 및 실행

단계	명령어	설명
image load	`docker load -i 파일명.tar.gz`	api-agent 이미지를 Docker에 로드합니다.
실행	`$EXEMONE_HOME/scripts/restart.sh api-agent`	api-agent 컨테이너를 시작합니다.

3. Binary 패키지 설치

3-1. 설치 파일 압축 해제

tar -zxvf exemone-api-agent-v3.0.508.3.tar.gz

3-2. bins 디렉터리에 실행 바이너리 복사

cd exemone-api-agent-v3.0.508.3
cp exemone-api-agent-v3.0.508.3 /home/exemone/exemone/bins/exemone-api-agent/

3-3. licenses 생성

cd /home/exemone/exemone/licenses
mkdir exemone-api-agent

cd /home/exemone/exemone/agent/exemone-api-agent-v3.0.508.3
cp -r licenses /home/exemone/exemone/licenses/exemone-api-agent

3-4. .env에 버전 입력

파일 경로: /home/exemone/exemone/.env

EXEMONE_API_AGENT=exemone-api-agent-v3.0.508.3

3-5. 실행/중지 스크립트 생성

경로: /home/exemone/exemone/services/exemone-api-agent/

아래 내용으로 start.sh, stop.sh, version.sh 파일을 생성합니다.

start.sh

#!/bin/bash
set -e
if [ -z "${EXEMONE_HOME}" ]; then
    export EXEMONE_HOME="$(dirname $(dirname $(pwd)))"
    echo "set EXEMONE_HOME=$EXEMONE_HOME"
fi
. "${EXEMONE_HOME}/scripts/lib.sh"

cur_dir=$(pwd)

if [ -f "${cur_dir}/.env" ]; then
    set -a
    source "${cur_dir}/.env"
    set +a
fi
service_name=$(basename "${cur_dir}")
pid_file=${cur_dir}/${service_name}.pid
binary_file=${EXEMONE_HOME}/bins/exemone-api-agent/${EXEMONE_API_AGENT}
config_file=${cur_dir}/configs/agent.yaml
signal_file=${cur_dir}/signal.act
lockfile=${cur_dir}/${service_name}.lock

(
  flock -n 200 || { log INFO "${service_name} start.sh already running. Exiting."; exit 1; }

  log INFO "Start ${service_name} init"
  if [[ -z "${LD_LIBRARY_PATH}" ]]; then
      export LD_LIBRARY_PATH=${EXEMONE_HOME}/libs
  elif [[ ! ${LD_LIBRARY_PATH} =~ ${EXEMONE_HOME}/libs ]]; then
      export LD_LIBRARY_PATH="${EXEMONE_HOME}/libs:${LD_LIBRARY_PATH}"
  fi

  if [ -f "${pid_file}" ]; then
      log "INFO" "Stop ${service_name} process before start process"
      stop_process "${service_name}" "${pid_file}"
  fi

  if [ -f "${signal_file}" ]; then
      rm -f "${signal_file}"
  fi

  log "INFO" "Start ${service_name} process"
  nohup "${binary_file}" start --config "${config_file}" > /dev/null 2>&1 & echo -n $! > "${pid_file}"

  sleep 1
  check_process "${service_name}" "${pid_file}"
) 200>"${lockfile}"

stop.sh

#!/bin/bash
set -e
if [ -z ${EXEMONE_HOME} ]; then
    export EXEMONE_HOME="$(dirname $(dirname $(pwd)))"
    echo "set EXEMONE_HOME=$EXEMONE_HOME"
fi
. ${EXEMONE_HOME}/scripts/lib.sh

cur_dir=$(pwd)
service_name=$(basename ${cur_dir})
pid_file=${cur_dir}/${service_name}.pid
signal_file=${cur_dir}/signal.act

touch ${signal_file}
stop_process ${service_name} ${pid_file}

version.sh

set -e
if [ -z ${EXEMONE_HOME} ]; then
    export EXEMONE_HOME="$(dirname $(dirname $(pwd)))"
    echo "set EXEMONE_HOME=$EXEMONE_HOME"
fi
. ${EXEMONE_HOME}/scripts/lib.sh

cur_dir=$(pwd)
service_name=$(basename ${cur_dir})
binary_path=${EXEMONE_HOME}/bins/exemone-api-agent/${EXEMONE_API_AGENT}

${binary_path} version

3-6. 스크립트 실행 권한 부여

cd /home/exemone/exemone/services/exemone-api-agent/
chmod +x *.sh

3-7. observer 동작을 위한 파일 추가

파일 경로: /home/exemone/exemone/services/exemone-api-agent/observer.properties

monitoring=true

3-8. onectl 파일 수정 및 권한 부여

수정 사항이 많으므로 기존 onectl 파일을 신규 onectl 파일로 대체한 후 실행 권한을 부여합니다.

chmod +x onectl

4. 설정 파일 (`api-agent.yaml`)

항목	설명
`global.agent_id`	api-agent 식별 ID (예: `url_default`)
`global.receiver`	수집 서버(Receiver) 주소 및 포트 (예: `receiver:9009`)
`log.caller`	로그에 호출 위치 포함 여부 (`false` / `true`)
`log.level`	로그 레벨 (`info` / `debug` / `error`)
`log.file`	로그 파일 저장 경로

5. 실행 및 관리 명령어

5-1. Binary 방식 (onectl 사용)

동작	명령어
실행	`./onectl start api-agent`
중지	`./onectl stop api-agent`
로그 확인	`./onectl log api-agent`
버전 확인	`./onectl ver api-agent`

실행 예시:

[exemone@localhost exemone]$ ./onectl start api-agent
Starting service : exemone-api-agent
[2025-11-05 13:17:25] EXEMONE INFO Start exemone-api-agent init
[2025-11-05 13:17:25] EXEMONE INFO Start exemone-api-agent process
[2025-11-05 13:17:26] EXEMONE INFO exemone-api-agent process is started. pid: 1499726

로그 확인 예시:

[exemone@localhost exemone]$ ./onectl log api-agent
Selected service: exemone-api-agent
2025-11-05 13:06:13 INF receive start service=url-agent
2025-11-05 13:06:13 INF send loop start service=url-agent
2025-11-05 13:06:18 INF [STAT][INIT] service=url-agent

버전 확인 예시:

[exemone@localhost exemone]$ ./onectl ver api-agent
Checking version of service : exemone-api-agent
exemONE service Version: v3.0.508.3, CommitID: 4887b2d5
BuildTime: Mon Nov  3 06:50:07 UTC 2025, Build With go1.20.4

5-2. Docker 방식

동작	명령어
실행/재기동	`$EXEMONE_HOME/scripts/restart.sh api-agent`

6. 주의사항 / 참고

항목	내용
Docker 패키지 포함 버전	api-agent는 v3.0.405.15.0 이상 패키지부터 포함. 낮은 버전 사용 시 수동 배포 필요
agent_id 중복 주의	`agent_id`가 기존 등록된 agent와 중복될 경우 `DuplicationAgentError` 발생. 고유한 값으로 설정 필요
receiver 주소	`api-agent.yaml`의 `receiver` 항목은 수집 서버(Receiver) 주소:포트로 정확히 설정 필요
onectl 파일 교체	Binary 설치 시 기존 onectl 파일을 신규 파일로 대체해야 하며, 실행 권한(`chmod +x`) 부여 필수
observer.properties	Binary 설치 시 `monitoring=true` 값의 `observer.properties` 파일 생성이 필요

exemONE api Agent 설치 및 설정

1. 지원 환경​

2. Docker 패키지 설치​

2-1. docker-compose.yml 서비스 블록 추가​

2-2. .env 파일에 이미지 및 버전 기입​

2-3. Dockerfile 추가​

2-4. configs 폴더 및 설정 파일 생성​

2-5. api-agent image load 및 실행​

3. Binary 패키지 설치​

3-1. 설치 파일 압축 해제​

3-2. bins 디렉터리에 실행 바이너리 복사​

3-3. licenses 생성​

3-4. .env에 버전 입력​

3-5. 실행/중지 스크립트 생성​

3-6. 스크립트 실행 권한 부여​

3-7. observer 동작을 위한 파일 추가​

3-8. onectl 파일 수정 및 권한 부여​

4. 설정 파일 (api-agent.yaml)​

5. 실행 및 관리 명령어​

5-1. Binary 방식 (onectl 사용)​

5-2. Docker 방식​

6. 주의사항 / 참고​

참고 문서​