本文へスキップ

インストールと使用

DBX for Cloud、DBXCは2つの主要コンポーネントで構成されています。

  • dbxc-agent: クラウド指標を監視するバックグラウンドサービス（エージェント）
  • dbxc-ctl: エージェントを制御するCLIツール（開始、停止、状態確認、ログ参照）

エージェントのインストール​

OSアーキテクチャーパッケージ
Linuxamd64、arm64.tar.gz
Windows 10、Windows Server 2016以上amd64.zip

インストールスクリプトがアーキテクチャー（x86_64、aarch64）を検出し、現在のパスのdbxcディレクトリにインストールします。

curl -fsSL https://repo.whatap.io/agent/dbx/cloud/install.sh | bash
cd dbxc

インストール後、dbxcディレクトリにconfig.yamlを作成し、./dbxc-ctl startで実行します。

設定ファイル構造​

DBXCはYAML形式の設定ファイルを通じて実行構成を定義します。

サポート形式​

DBXCは単一/マルチプロジェクトエージェントをサポートします。

  • YAML形式 (.yaml, .yml)
  • 単一ファイル: 1つのエージェントを実行
  • ディレクトリ: 複数のエージェントを実行

設定ファイル自動探索順序​

  1. -c オプションで指定されたファイル/ディレクトリ
  2. config.yaml, config.yml (デフォルトファイル)
  3. カレントディレクトリ内のすべての .yaml, .yml ファイル

設定ファイル例​

ディレクトリ tree 例
❯ tree
.
├── configs
│   ├── project-1.yml
│   └── project-2.yml
├── dbxc-agent
├── dbxc-ctl
├── dbxc.log
├── dbxc.pid

❯ ls -al
total 68456
drwxr-xr-x  8 kyw  staff       256  7 18 20:23 .
drwxr-xr-x  9 kyw  staff       288  7 18 20:10 ..
drwxr-xr-x  4 kyw  staff       128  7 18 20:23 configs
-rwxr-xr-x  1 kyw  staff  20174450  7 18 20:09 dbxc-agent
-rwxr-xr-x  1 kyw  staff   8565570  7 18 20:09 dbxc-ctl
-rw-------  1 kyw  staff   5574908  7 18 20:30 dbxc.log
-rw-r--r--  1 kyw  staff         5  7 18 20:23 dbxc.pid
yml 例
input:
  csp: "aws" # クラウドサービスのプロバイダーを入力します。
  namespace: "rds"
  region: "ap-northeast-1" # インスタンスが位置するリージョンを設定します。
  instances: # 指定したインスタンスは常に収集されます。クラスター内のインスタンスをここに指定すると、オートスケールに関係なく収集されます。
    - name: "mysql-rds" # インスタンス名
      slow_query: true # スロークエリページを使用する場合は、true に設定します。
  clusters:
    autoscale:
      enabled: false # オートスケールが有効な場合、スケーリングされたインスタンスを収集対象に追加または削除します。
      interval: 60 # 指定したクラスターのオートスケール確認間隔です。（単位: 秒）
    names:
      - "database-cluster-name"
  metrics: # 収集するメトリクスを入力します。
    - "CPUUtilization"
    - "FreeStorageSpace"
    - "FreeableMemory"
    - "ReadLatency"
    - "WriteLatency"
    - "ReadIOPS"
    - "WriteIOPS"
    - "NetworkReceiveThroughput"
    - "NetworkTransmitThroughput"
    - "FreeLocalStorage"
  logs:
    enabled: false # ログ収集を有効にするには true を入力します。
    groups: # 収集するAWSロググループを追加します。
      - "/aws/rds/cluster/database-cluster-name/error"
      - "/aws/lambda/MyLambda"

output: # 収集したメトリクスを送信する WhaTap 情報を入力します。
  license: "abcdefg-higjgkgjk-zxcvnbnbmc"
  host: "127.0.0.1"

エージェント実行および制御コマンド​

CLIはエージェントの開始から状態確認、ログ参照まで様々なコマンドを提供します。

開始/終了​

# 設定ファイルと権限の事前検証（エージェントは開始しない）
dbxc-ctl validate -c project.yaml

# エージェント開始
dbxc-ctl start -c project.yaml       # 特定の設定ファイル
dbxc-ctl start --config configs      # 複数プロジェクト（ディレクトリ）
dbxc-ctl start                       # デフォルト設定ファイルを自動探索

# エージェント停止
dbxc-ctl stop

# エージェント再起動
dbxc-ctl restart -c project.yaml

状態確認​

# 簡単な状態確認
dbxc-ctl status
dbxc-ctl describe

ログ参照​

# リアルタイムログ参照
dbxc-ctl logs -f

# 特定プロジェクトのログのみ参照
dbxc-ctl logs -c project.yaml

# ログレベルでフィルタリング
dbxc-ctl logs --level error

# 直近100件のログ参照
dbxc-ctl logs --tail 100

エージェント起動失敗時​

# ログ確認
dbxc-ctl logs --level error

エージェント状態確認​

# 全体状態確認
dbxc-ctl describe

# 特定エージェントのログ確認
dbxc-ctl logs -c specific-config.yaml -f
Tips

一般的なトラブルシューティング

  • ポート競合: デフォルトポート53200が使用中か確認

  • 設定ファイルエラー: YAML文法を確認

  • 権限問題: ファイル読み取り権限を確認

  • PIDファイルロック: 強制終了後にPIDファイルを削除

エージェントログ・設定の送信​

エージェントは問題診断のため、自身のwarn/errorログと設定ファイル（config.yaml）の内容をWhaTap収集サーバーへ送信します。設定ファイルは1時間ごとに送信します。デフォルトで有効になっており、agent_logs項目で無効化したり範囲を変更したりできます。

config.yaml
agent_logs:
  send_config: true            # 設定ファイルの送信有無（デフォルト値: true）
  send_logs: true              # エージェントログの送信有無（デフォルト値: true）
  log_levels: ["warn", "error"] # 送信するログレベル（デフォルト値: warn, error）

設定ファイルにNCPのsecretKeyなどの認証情報を含める場合、外部への送信を望まないときはsend_config: falseに設定します。

詳細技術情報​

DBXCの詳細なコマンド構成および内部システム動作情報です。

コマンド構造​

dbxc-ctlは以下のコマンドをサポートします。

  • start: DBXCエージェント開始
  • stop: DBXCエージェント停止
  • restart: DBXCエージェント再起動
  • logs: ログ参照
  • validate: 設定ファイルとAWS権限（AssumeRole、インスタンス照会、logs.groups照会）を事前検証した後に終了
  • status またはdescribe: エージェント状態確認
  • version: バージョン情報確認
  • help: ヘルプ表示

HTTP API エンドポイント​

エージェントはHTTPエンドポイントを提供します。

  • http://localhost:53200/health: ヘルスチェック
  • http://localhost:53200/status: 状態情報
  • http://localhost:53200/logs: ログ参照

ログシステム​

  • ファイル名: dbxc.log
  • 最大サイズ: 1ファイルあたり10MB
  • 最大バックアップファイル数: 7個 (dbxc.log.1, dbxc.log.2, ... dbxc.log.7)
  • 保管期間: 14日
  • 圧縮: 古いログファイルを自動圧縮（.gz形式）
  • タイムゾーン: ローカル時間

ログファイルが10MBに達すると自動的にローテーションされ、最大7個のバックアップファイルが保持されます。 14日以上経過したログは自動的に削除され、ディスク容量節約のため古いログは圧縮されます。

最終修正：