Python Agent インストール

1. モジュールの説明

exem-python-agentは、Pythonベースのアプリケーション(Django、Flask、FastAPIなど)で実行されるトランザクション、SQL、Call Tree、例外データを収集してExemONE収集サーバー(Receiver)に送信するモニタリングエージェントです。

2. サポート環境

項目	内容
OS	Linux
Arch	64bit
Runtime	Python 3.7以上
Platform	On-premise Docker Kubernetes
Framework	Django WSGI Django ASGI Flask FastAPI (0.95.2以上 — サポートガイド基準)
DB	SQLite (sqlite3, pysqlite3) MySQL (pymysql, MySQLdb) Oracle (cx_Oracle) PostgreSQL (psycopg2) MongoDB (pymongo, motor) Redis redis-om
HTTP	httplib (http.client) urllib3 requests aiohttp HTTPX
Messaging	Kafka (kafka_python, confluent_kafka) — producer・consumer (decorator)
Protocol	TCP 9010 → Receiver
Prereq	pipが使用可能であること Django / Flask / FastAPIのいずれか
Other	APScheduler

3. 通信ポート

送信元	送信先	プロトコル	ポート	用途
モニタリング対象サーバー (Python App)	ExemONE収集サーバー (Receiver)	TCP	9010	エージェント-収集サーバー間通信

注記

モニタリング対象サーバーからExemONE収集サーバー方向に9010ポートが開放されている必要があります。ver 3.0.7からはJava Agentと同じTCP 9010ポートを使用します。

4. インストール方法

環境に応じて2種類のインストール方式をサポートします。

インストール方式	適合環境	特徴
On-Premiseインストール	物理サーバー、VM	tar.gz解凍後にpipインストール
InitContainer方式	Kubernetes	アプリケーションの再ビルドなしにinitContainerとしてインストール(v3.0.18.1+)
Dockerfile Rebuild方式	Kubernetes、Docker	Dockerfileにエージェントを含めてイメージをビルド

4-1. On-Premiseインストール

1. パッケージのダウンロード

インストールパッケージ(EXEM-PYTHON-AGENT-X.X.X.tar.gz)をサーバーにダウンロードするか、直接アップロードします。

EXEM-PYTHON-AGENT-[version].tar.gz

2. 解凍

tar -zxvf EXEM-PYTHON-AGENT-[version].tar.gz

解凍後のディレクトリ構造は以下の通りです。

exem/python/
├── cfg/
│   └── agent/
│       ├── pymon.ini           # エージェント基本設定ファイル
│       └── pymon_extend.ini
├── lib/
│   ├── dependency/             # grpcio, protobuf, psutil 依存パッケージ
│   └── exem-python-agent-[version].tar.gz
└── data/

3. モジュールのインストール

exem/python/lib/ディレクトリのエージェントパッケージをpipでインストールします。

cd exem/python/lib
pip install exem-python-agent-[version].tar.gz

依存パッケージ(grpcio, grpcio-tools, protobuf, psutil)がないオフライン環境では、dependency/フォルダのパッケージを先にインストールします。

pip install dependency/grpcio-1.53.0.tar.gz
pip install dependency/grpcio-tools-1.53.0.tar.gz
pip install dependency/protobuf-4.21.6.tar.gz
pip install dependency/psutil-5.9.8.tar.gz

4. 必須オプションの設定

エージェント起動には以下の4つのオプションが必須です。

オプション	説明
`EXEM_PYTHON_HOME`	エージェントのインストールパス(解凍した`exem/python`ディレクトリ)
`EXEM_PYTHON_AGENT_NAME`	ExemONE画面に表示されるエージェント名
`EXEM_GROUP_ID`	WASグループID
`EXEM_RECEIVER_ADDR`	ExemONE収集サーバーのアドレス(`IP:ポート`)

注記

CURR_TRACE_TXNオプションのデフォルト値は*:3000で、3,000ms(3秒)未満のトランザクションは収集されません。すべてのトランザクションを収集するには*:0に設定してください。

オプションは環境変数または起動オプション + 設定ファイルの2つの方式で設定します。

方法1 — 環境変数

4つのオプションをすべて環境変数として設定します。

export EXEM_PYTHON_HOME=/exem/python
export EXEM_PYTHON_AGENT_NAME=python-agent
export EXEM_GROUP_ID=python
export EXEM_RECEIVER_ADDR=<収集サーバーIP>:9010

方法2 — 起動オプション + 設定ファイル

EXEM_PYTHON_HOMEとEXEM_PYTHON_AGENT_NAMEはエージェント起動時にオプションとして渡し、EXEM_RECEIVER_ADDRとEXEM_GROUP_IDはpymon.ini設定ファイルに記述します。

# exem/python/cfg/agent/pymon.ini
EXEM_GROUP_ID=python
RECEIVER_ADDR=<収集サーバーIP>:9010

5. エージェントの適用と起動

モジュールインストール時にstart_agent実行ファイルがPython PATHに追加されます。start_agentでアプリケーションを起動すると、エージェントが併せて適用されます。

環境変数でオプションを設定した場合:

start_agent uvicorn app:app

起動オプションで設定する場合:

start_agent --python_home /exem/python --agent_name python-agent uvicorn app:app

正常起動時はアプリケーションログとともにサーバーが起動します。

4-2. InitContainer方式 (Kubernetes)

アプリケーションを再ビルドせずに、PodのinitContainerとしてエージェントをインストールする方法です。v3.0.18.1以降でサポートします。

エージェントイメージの命名規則: exem-python-agent:inst_[バージョン]

エージェントイメージには以下の内容が含まれています。

パス	内容
`/pkg/exem/python`	エージェント起動に必要な設定・ログディレクトリ
`/pkg/exem/exem-python`	エージェントパッケージ、モジュール、起動スクリプト

注記

1. ConfigMapの作成

コールツリーの追加が必要な場合、local.adviceをConfigMapとして定義します。設定が不要であれば空の値のままでも構いません。

apiVersion: v1
kind: ConfigMap
metadata:
  name: exem-python-agent-config
  namespace: <ネームスペース>
data:
  local.advice: |
    ###  記述形式
    #      [パッケージ名]
    #      クラス名:メソッド名
    ###  記述例
    #    [redis]
    #    * : *
    #    [mysql]
    #    PyMySQL : *

2. Deployment YAMLの修正

既存のDeployment YAMLに以下の項目を追加します。

全体例:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: python-k8s-init-fastapi
  namespace: <ネームスペース>
spec:
  replicas: 1
  selector:
    matchLabels:
      app: python-k8s-init-fastapi
  template:
    metadata:
      labels:
        app: python-k8s-init-fastapi
    spec:
      volumes:
        # exem-python-agent インストール対象ボリューム
        - name: exem-volume
          emptyDir: {}
        # exem-python-agent 設定ファイルボリューム
        - name: config-volume-python-agent
          configMap:
            name: exem-python-agent-config
      initContainers:
        - name: install-exem-python-agent
          image: exem/exem-python-agent:inst_[バージョン]
          imagePullPolicy: IfNotPresent
          volumeMounts:
            - name: exem-volume
              mountPath: /exem
            - name: config-volume-python-agent
              mountPath: "/exem-config"
              readOnly: true
      containers:
        - name: python-k8s-init-fastapi
          image: <アプリケーションイメージ>
          imagePullPolicy: Always
          volumeMounts:
            - name: exem-volume
              mountPath: /exem
          env:
            # 既存のPYTHONPATHがある場合、以下の2つのパスを既存の値の後ろに追加する必要があります。
            # 追加しないと既存のPYTHONPATHが上書きされます。
            - name: PYTHONPATH
              value: "/exem/exem-python:/exem/exem-python/pymon/bootstrap"
            - name: EXEM_PYTHON_HOME
              value: "/exem/python"
            - name: EXEM_PYTHON_AGENT_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: EXEM_GROUP_ID
              value: "python"
            - name: EXEM_RECEIVER_ADDR
              value: "<収集サーバーIP>:9010"
            - name: EXEM_RUN_ON_CONTAINER
              value: "true"
            - name: EXEMWID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.uid
          ports:
            - containerPort: 8000

各項目の説明:

項目	説明
`volumes.exem-volume`	initContainerとアプリケーションコンテナが共有するPodストレージです。エージェントファイルがこのボリュームにコピーされます
`volumes.config-volume-python-agent`	ConfigMapをボリュームとしてマウントし、`local.advice`設定を外部から注入します
`initContainers`	エージェントイメージをinitContainerとして起動し、エージェントファイルを`exem-volume`にコピーします
`containers.volumeMounts`	アプリケーションコンテナが`exem-volume`をマウントしてエージェントにアクセスできるようにします

環境変数の説明:

環境変数	説明	備考
`PYTHONPATH`	エージェント適用に必要なパス。固定値: `/exem/exem-python:/exem/exem-python/pymon/bootstrap`	既存パスがある場合は後ろに追加
`EXEM_PYTHON_HOME`	エージェントのHOMEパス。固定値: `/exem/python`
`EXEM_PYTHON_AGENT_NAME`	ExemONE画面に表示されるWAS名
`EXEM_GROUP_ID`	WASグループID。未設定時は`default`
`EXEM_RECEIVER_ADDR`	収集サーバーアドレス(`IP:ポート`)
`EXEM_RUN_ON_CONTAINER`	コンテナ環境での動作有無。コンテナ: `true`、On-Premise: `false`(デフォルト)
`EXEMWID`	コンテナ連携用のキー。`EXEM_RUN_ON_CONTAINER=true`設定時のみ適用

4-3. Dockerfile Rebuild方式

インストール対象アプリケーションのDockerfileにエージェントを含めてイメージをビルドする方式です。

注記

1. Dockerfileの修正

既存のDockerfileに以下の内容を追加します。

全体例:

# FROM python:3.10
# ... (既存のDockerfile内容)

# 1. インストールフォルダがない場合に作成
RUN mkdir -p /home/exemone

# 2. パッケージのコピーと解凍
COPY EXEM-PYTHON-AGENT-[version].tar.gz /home/exemone
RUN tar -zxvf /home/exemone/EXEM-PYTHON-AGENT-[version].tar.gz -C /home/exemone

# 3. モジュールのインストール
RUN pip install /home/exemone/exem/python/lib/exem-python-agent-[version].tar.gz

# 4. ENTRYPOINT設定
ENTRYPOINT ["start_agent", "<既存のPythonアプリケーション実行コマンド>"]

ENTRYPOINT記述例:

種類	例
フレームワークコマンド	`["start_agent", "uvicorn", "--app-dir", "/app", "app:app", "--host", "0.0.0.0"]`
Pythonスクリプトの直接実行	`["start_agent", "python", "/app/consumer.py"]`
実行スクリプト	`["start_agent", "/app/start.sh"]`
実行スクリプト + 引数	`["start_agent", "/app/start.sh", "arg1", "arg2"]`

コールツリーの追加が必要な場合、local.adviceファイルを以下のようにDockerfileで直接作成できます。ConfigMapを使用する方法も可能なので、次の手順を参照してください。

RUN printf '[redis]\nStrictRedis:*\n' > /home/exemone/exem/python/cfg/agent/local.advice.ini

2. Deployment YAMLの修正

既存のDeployment YAMLに以下の項目を追加します。

全体例:

apiVersion: v1
kind: ConfigMap
metadata:
  name: exem-python-agent-config
  namespace: <ネームスペース>
data:
  local.advice: |
    ###  記述形式
    #      [パッケージ名]
    #      クラス名:メソッド名
    ###  記述例
    #    [redis]
    #    * : *
    #    [mysql]
    #    PyMySQL : *
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: python-k8s-fastapi
  namespace: <ネームスペース>
spec:
  replicas: 1
  selector:
    matchLabels:
      app: python-k8s-fastapi
  template:
    metadata:
      labels:
        app: python-k8s-fastapi
    spec:
      volumes:
        - name: exem-python-agent-config
          configMap:
            name: exem-python-agent-config
      containers:
        - name: python-k8s-fastapi
          image: <エージェントを含めて再ビルドしたイメージ>
          imagePullPolicy: Always
          volumeMounts:
            - name: exem-python-agent-config
              mountPath: /home/exemone/exem/python/cfg/agent/local.advice
              subPath: local.advice
              readOnly: true
          env:
            - name: EXEM_PYTHON_HOME
              value: "/home/exemone/exem/python"
            - name: EXEM_PYTHON_AGENT_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: EXEM_GROUP_ID
              value: "python"
            - name: EXEM_RECEIVER_ADDR
              value: "<収集サーバーIP>:9010"
            - name: EXEM_RUN_ON_CONTAINER
              value: "true"
            - name: EXEMWID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.uid
          ports:
            - containerPort: 8000

環境変数の説明:

環境変数	説明
`EXEM_PYTHON_HOME`	エージェントのHOMEパス。パッケージ解凍パス配下の`exem/python`
`EXEM_PYTHON_AGENT_NAME`	ExemONE画面に表示されるWAS名
`EXEM_GROUP_ID`	WASグループID。未設定時は`default`
`EXEM_RECEIVER_ADDR`	収集サーバーアドレス(`IP:ポート`)
`EXEM_RUN_ON_CONTAINER`	コンテナ環境での動作有無。コンテナ: `true`、On-Premise: `false`(デフォルト)
`EXEMWID`	コンテナ連携用のキー。`EXEM_RUN_ON_CONTAINER=true`設定時のみ適用

Python Agent インストール

1. モジュールの説明​

2. サポート環境​

3. 通信ポート​

4. インストール方法​

4-1. On-Premiseインストール​

1. パッケージのダウンロード​

2. 解凍​

3. モジュールのインストール​

4. 必須オプションの設定​

方法1 — 環境変数​

方法2 — 起動オプション + 設定ファイル​

5. エージェントの適用と起動​

4-2. InitContainer方式 (Kubernetes)​

1. ConfigMapの作成​

2. Deployment YAMLの修正​

4-3. Dockerfile Rebuild方式​

1. Dockerfileの修正​

2. Deployment YAMLの修正​

1. モジュールの説明

2. サポート環境

3. 通信ポート

4. インストール方法

4-1. On-Premiseインストール

1. パッケージのダウンロード

2. 解凍

3. モジュールのインストール

4. 必須オプションの設定

方法1 — 環境変数

方法2 — 起動オプション + 設定ファイル

5. エージェントの適用と起動

4-2. InitContainer方式 (Kubernetes)

1. ConfigMapの作成

2. Deployment YAMLの修正

4-3. Dockerfile Rebuild方式

1. Dockerfileの修正

2. Deployment YAMLの修正