メインコンテンツまでスキップ

DB Agent インストール

1. モジュールの説明​

exemONE DB Agent(exemone-db-agent)は、データベースの性能指標(セッション、SQL、Wait Event、Tablespace、Parameterなど)を収集し、エクセムワン収集サーバー(Receiver)へ送信するモニタリングエージェントです。

DB Agentには2つの形態があります。

  • Default DB Agent(収集サーバー内蔵): エクセムワンパッケージに含まれており、収集サーバーから対象DBへ直接接続してデータを収集します。
  • 個別DB Agent: 対象DBサーバーに直接インストールして当該DBのデータを収集した後、Receiverへ送信します。セキュリティ上の理由で収集サーバーと直接接続できない場合や、OS情報、Slow Queryなど追加データの収集が必要な場合は個別DB Agentを使用します。

2. サポート環境​

項目内容
OSLinux
Arch64bit (AMD64 · ARM64)
PlatformOn-premise
DBPostgreSQL 9.6 以上
SQL Server 2012 以上
MySQL 5.5 以上 / MariaDB 10 以上
(MySQL 5.5 は一部サポート)
Oracle 12c 以上
Redis 3.0.0 以上
CUBRID 9.2.1 以上
MongoDB 4.0.0 以上
Tibero 5 以上
Altibase 6.3 以上
(6.3 は一部サポート)
ClickHouse v24.8.6.70 以上
Amazon Redshift
SingleStore 8.9 以上
ProtocolgRPC 9009 → Receiver
CloudAWS
Azure
OCI
GCP
NCP
KT Cloud
Samsung Cloud (SCP)

3. 通信ポート​

区分送信元送信先TypePort内容
Default DB Agent(収集サーバー内蔵)エクセムワン収集サーバー対象DBTCPDB Listener PortDB指標収集
個別DB Agentモニタリング対象機器エクセムワン収集サーバー(Receiver)gRPC9009汎用gRPCリクエスト及びレスポンス

4. インストール手順​

個別DB Agentをインストールする方法は次のとおりです。収集サーバー内蔵DB Agentは別途エージェント登録なしで対象への接続が可能です。

4-1. エクセムワンWeb UIでAgentを登録​

  1. プロフィール > 環境設定 > 管理 > エージェント メニューに移動します。

  2. 上部の[エージェント追加] ボタンをクリックします。

clipboard

  1. エージェントタイプでデータベースを選択します。

  2. エージェント作成画面でAgent IDおよびAccess Tokenを確認します。Access TokenはRegenerateを選択した後に確認し、確認後は必ず[保存]をクリックします。エージェント名を直接入力します。

危険
発行されたエージェントIDとアクセストークンの情報を必ず記録しておき、**[保存]** ボタンをクリックしてエージェントが一覧に正常に追加されたことを確認してください。
  1. Instance タブでAdd Groupを選択してグループを追加した後、Add Instanceを選択してインスタンスを追加します。Agent項目には手順1で追加したAgentを登録します。

clipboard

4-2. DBサーバーにexemone-db-agentをインストール​

Linux環境へのインストール​

方法1. tarファイルでインストール

  1. exemoneアカウントを作成した後、exemone-db-agentの圧縮を解凍します。
  2. conf/agent.yamlファイル内にAgent ID、Access Token、Receiverの情報を追加します。
    注意

    値を入力する際、agent_id:の後に必ず半角スペースを1つ入れる必要があります。

clipboard

  1. ./startup.shスクリプトを実行してexemone-db-agentを起動します。

  1. エージェントが起動するとlogsフォルダが作成されます。logs/agent.logファイルを確認してエラーが発生していないかを確認します。正常に接続された場合、次のようなログが出力されます。

方法2. binファイルでインストール

  1. binファイルに実行権限を付与します。

    chmod +x setup_exemone-db-agent_v3.0.412.9.0.bin

  2. binファイルを実行します。

    ./setup_exemone-db-agent_v3.0.412.9.0.bin
    ===
    exemone-db-agent Install
    ===

    new install start
    Would you like to do a new install? (y/n)
    y
    xmSuccess(0): Installation is complete.

  3. exemone-db-agent/conf/agent.yamlファイルを編集してAgent ID、Access Token、Receiverの情報を入力します。

  4. exemone-db-agent/start.shを実行します。

    ./start.sh
    xmSuccess(0): exemONE DB agent start success

Windows環境へのインストール​

  1. setup_exemone-db-agent_{version}.exeファイルを実行します。サービスとして登録して使用する場合は、該当オプションにチェックを入れてインストールします。

  1. {exemone-db-agent-home}\\conf\\agent.yamlファイル内にAgent ID、Access Token、Receiverの情報を追加します。
    注意

    値を入力する際、agent_id:の後に必ず半角スペースを1つ入れる必要があります。

  1. start.batを実行してexemone-db-agentを起動します。
  2. エージェントが起動するとlogsフォルダが作成されます。logs/agent.logファイルを確認してエラーが発生していないかを確認します。正常に接続された場合、次のようなログが出力されます。

5. 設定ファイル詳細(agent.yaml)​

agent.yamlファイルは{DB_AGENT_HOME}/conf/agent.yamlパスに配置されており、主な設定項目は次のとおりです。

設定項目説明備考
global.agent_idエクセムワンWebで発行されたAgent ID必須。:の後にスペース必須
global.access_tokenエクセムワンWebで発行されたAccess Token必須。保存後に確認
global.receiver収集サーバーReceiverアドレス(IP:9009)必須
global.installed_pathdb-agentインストールパス必須
global.run_pathdb-agent実行パス必須
log.callerログ呼び出し元(関数名、行番号)の表示有無デフォルト値: false
log.levelログレベル設定info、warn、error、panic、debug、trace
log.fileログファイルパスパス変更時はエージェントの再起動が必要
log.max-backups保管するログファイル数v3.0.504.15.44以降でサポート
log.max-sizeログファイルの最大サイズ(MB単位)v3.0.504.15.44以降でサポート。1024で計算
log.max-ageログファイルの保管日数v3.0.504.15.44以降でサポート

5-1. ログパスの変更方法​

  1. db-agentを停止します: {DB_AGENT_HOME}/stop.sh
  2. {DB_AGENT_HOME}/conf/agent.yamlファイル内のログパスを変更します。

clipboard

  1. db-agentを起動します: {DB_AGENT_HOME}/start.sh
    ノート

    変更後のログパスに、エージェント実行アカウントの権限が設定されている必要があります。

6. Linux systemdサービス登録(任意)​

db-agent v3.0.506.15.10以上のバージョンからsystemdサービス登録がサポートされます。

  1. db-agentインストール後、conf/agent.yamlファイルにname: agent項目を追加します。

    log:
      caller: false
      level: info
      file: /home/exemone/db_agent/exemone-db-agent/logs/agent.log
      name: agent   # ==> 追加

  2. サービスファイルをコピーして適用します。

    # サービスファイルのコピー
    sudo cp exemone-db-agent.service /etc/systemd/system/

    # サービスファイルの適用
    sudo systemctl daemon-reload

  3. サービスを実行し、状態を確認します。

    # サービス実行
    sudo systemctl start exemone-db-agent

    # サービス状態確認
    systemctl status exemone-db-agent

    # サービス終了
    sudo systemctl stop exemone-db-agent

7. 手動パッチ方法​

  1. db-agentを停止します: {DB_AGENT_HOME}/stop.sh
  2. 別途ディレクトリを作成し、binファイルを実行します。
    mkdir ins
    chmod +x setup_exemone-db-agent_{version}.bin
    ./setup_exemone-db-agent_{version}.bin
  3. 作成された実行ファイルを既存のパスにコピーします。
    cp -R exemone-db-agent/exemone-db-agent-{version} {DB_AGENT_HOME}
  4. .envファイルでバージョン情報(DB_AGENT_VERSION)を修正します。
  5. db-agentを起動します: {DB_AGENT_HOME}/start.sh

8. 管理スクリプト​

スクリプト説明
./startup.sh または ./start.shdb-agent起動
./stop.shdb-agent終了
start.bat(Windows)db-agent起動(Windows環境)

9. 参考事項​

9-1. Oracle接続エラー発生時​

Oracle DBの場合、次のようなエラーが発生したら、db-agentインストールパス内の.envファイルにOracle接続用の環境変数の値を追加します。

9-2. パスワードの暗号化・復号化​

セキュリティポリシーに従い、モニタリング対象DBのパスワードを暗号化した形で管理できます。

  • 暗号化:
    {EXEMONE_HOME}/scripts/crypto-cli encrypt --plaintext {平文}
  • 復号化:
    {EXEMONE_HOME}/scripts/crypto-cli decrypt --ciphertext {暗号化テキスト}

10. 注意事項​

  1. agent_id設定時のYAML文法に注意: agent_id:の後に必ず半角スペースを1つ入れる必要があります。
  2. Unix非対応: exem-db-agentはAIX、HP-UX、SunOSなどのUnix環境をサポートしません。LinuxおよびWindowsのみサポートします。
  3. ファイアウォールポートの開放: 個別DB AgentとReceiver間のgRPC 9009ポート、Default DB Agentと対象DB間のDB Listener Portが開放されている必要があります。
  4. Access Tokenの保存必須: Agent作成後、Regenerateでトークンを確認した際は必ず[保存]をクリックする必要があります。保存しないとトークンが適用されません。
  5. Oracle環境変数: Oracle DB接続エラー時は、.envファイルにOracle環境変数(LD_LIBRARY_PATH、ORACLE_HOMEなど)を追加する必要があります。
  6. systemd登録: db-agent v3.0.506.15.10以上でのみsystemdサービス登録がサポートされます。
  7. ログ設定: max-backups、max-size、max-ageオプションはdb-agent v3.0.504.15.44以降のバージョンからサポートされます。
  8. 収集クエリ修正後は必ず再起動: 修正したクエリを適用するにはdb-agentを再起動する必要があります。
  9. パッケージファイルの準備: インストールファイルは製品技術チームに問い合わせて準備します。