.NET Agent インストール
1. モジュールの説明
exem-dotnet-agentは、Linux環境の.NET(CoreCLR)ベースのプロセスのトランザクション、SQL、Call Tree、例外データを収集してExemONEに送信するモニタリングエージェントです。
2. サポート環境
| 項目 | 内容 |
|---|---|
| OS | Linux |
| Arch | 64bit |
| Runtime | .NET 6.0以上 (CoreCLR) |
| Platform | On-premise Docker Kubernetes |
| Framework | ASP.NET Core (Kestrel) |
| DB | SQL Server (Microsoft.Data.SqlClient.dll) |
| HTTP | Remote Call (System.Net.Http) Socket |
| Protocol | TCP 9010 → Receiver |
| Prereq | CoreCLRプロファイリング環境変数の設定が必須 |
| Other | Custom Transaction |
3. インストール方法
環境に応じて2種類のインストール方式をサポートします。
| インストール方式 | 適合環境 | 特徴 |
|---|---|---|
| On-Premiseインストール | 物理サーバー、VM | パッケージ解凍後に環境変数を設定 |
| InitContainer方式 | Kubernetes | アプリケーションの再ビルドなしにinitContainerとしてインストール |
3-1. On-Premiseインストール
1. パッケージの解凍
パッケージ(EXEM-DOTNET-AGENT-x.x.x.x)をサーバーにアップロードした後、解凍します。
tar.gzの場合:
tar -xzf EXEM-DOTNET-AGENT-x.x.x.x.tar.gz
zipの場合:
unzip EXEM-DOTNET-AGENT-x.x.x.x.zip
2. 設定ファイルの構成
解凍後、以下のパスに設定ファイルが配置されます。
| ファイル | パス | 用途 |
|---|---|---|
net.conf | exem/dotnet/cfg/agent/net.conf | Receiver接続アドレス、WAS名などの基本設定 |
profile.conf | exem/dotnet/cfg/profile.conf | プロファイラーの動作設定 |
x.advice | exem/dotnet/cfg/x.advice | トランザクション開始点の収集のためのメソッドweave設定 |
x.callback.conf | exem/dotnet/cfg/x.callback.conf | コールバックメソッド設定 |
net.confの主要設定項目:
| 設定項目 | 説明 | 備考 |
|---|---|---|
EXEM_GROUP_ID | WASグループID。未設定時はdefault | 環境変数での指定も可能 |
EXEM_RECEIVER_ADDR | 収集サーバーアドレス(IP:ポート) | 環境変数での指定も可能 |
EXEM_DOTNET_AGENT_NAME | ExemONE画面に表示されるWAS名 | 環境変数での指定も可能 |
3. 必須環境変数の設定
CoreCLRプロファイラーの有効化のため、以下の環境変数を設定します。
| 環境変数 | 説明 | 値の例 |
|---|---|---|
EXEM_DOTNET_HOME | エージェントのホームパス(exem/dotnetディレクトリ) | /opt/exem/dotnet |
CORECLR_ENABLE_PROFILING | CoreCLRプロファイラーの有効化有無 | 1 |
CORECLR_PROFILER | ロードするプロファイラーのCLSID | {cf0d821e-299b-5307-a3d8-b283c03916dd} |
CORECLR_PROFILER_PATH | Exem.DotNet.Profiler.soの絶対パス | $EXEM_DOTNET_HOME/binary/Exem.DotNet.Profiler.so |
DOTNET_STARTUP_HOOKS | 起動時に先行ロードするStartup Hook DLLのパス | $EXEM_DOTNET_HOME/binary/startup/Exem.DotNet.Startup.Hook.dll |
EXEM_DOTNET_PROFILE_TARGET_PROCESS | モニタリング対象プロセス(DLL)名 | MyService.dll |
方法1 — 直接export:
export EXEM_DOTNET_HOME=/opt/exem/dotnet
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER='{cf0d821e-299b-5307-a3d8-b283c03916dd}'
export CORECLR_PROFILER_PATH="$EXEM_DOTNET_HOME/binary/Exem.DotNet.Profiler.so"
export DOTNET_STARTUP_HOOKS="$EXEM_DOTNET_HOME/binary/startup/Exem.DotNet.Startup.Hook.dll"
export EXEM_DOTNET_PROFILE_TARGET_PROCESS='MyService.dll'
方法2 — setenv.shの使用:
パッケージに含まれるsetenv.shに、モニタリング対象プロセス名を引数として渡して環境変数を一括適用します。
source ./setenv.sh MyService.dll
4. エージェントの適用と起動
環境変数を設定した状態でアプリケーションを起動します。エージェントはCoreCLRプロファイラーを通じて自動的に適用されます。
cd /opt/apps/myapp
dotnet MyService.dll
3-2. InitContainer方式 (Kubernetes)
アプリケーションを再ビルドせずに、PodのinitContainerとしてエージェントをインストールする方法です。
エージェントイメージの命名規則: exem-dotnet-agent-inst:x.x.x.x
エージェントイメージの/exemパスに、バイナリ、設定、ログディレクトリが含まれています。
1. ConfigMapの作成
エージェント設定ファイルをConfigMapとして定義します。
apiVersion: v1
kind: ConfigMap
metadata:
name: exem-dotnet-agent-config
namespace: <ネームスペース>
data:
net.conf: |
# 環境変数での指定も可能
EXEM_RECEIVER_ADDR=<収集サーバーIP>:9010
# 未設定時は "exem-dotnet-agent"
# 環境変数での指定も可能
EXEM_DOTNET_AGENT_NAME=
# 未設定時は "default"
# 環境変数での指定も可能
EXEM_GROUP_ID=
calltree.advice: |
# 追加のコールツリー収集が必要な場合、以下の形式で記述します。
# classFullName:method signature name
2. Deployment YAMLの修正
既存のDeployment YAMLに以下の項目を追加します。
全体例:
apiVersion: apps/v1
kind: Deployment
metadata:
name: dotnet-k8s-app
namespace: <ネームスペース>
spec:
replicas: 1
selector:
matchLabels:
app: dotnet-k8s-app
template:
metadata:
labels:
app: dotnet-k8s-app
spec:
volumes:
# exem-dotnet-agent インストール対象ボリューム
- name: exem-volume
emptyDir: {}
# exem-dotnet-agent 設定ファイルボリューム
- name: config-volume-dotnet-agent
configMap:
name: exem-dotnet-agent-config
initContainers:
- name: install-exem-dotnet-agent
image: exem/exem-dotnet-agent-inst:[バージョン]
imagePullPolicy: IfNotPresent
volumeMounts:
- name: exem-volume
mountPath: /exem
- name: config-volume-dotnet-agent
mountPath: "/exem-config"
readOnly: true
containers:
- name: dotnet-k8s-app
image: <アプリケーションイメージ>
imagePullPolicy: Always
volumeMounts:
- name: exem-volume
mountPath: /exem
env:
- name: EXEM_DOTNET_HOME
value: "/exem/dotnet"
- name: CORECLR_ENABLE_PROFILING
value: "1"
- name: CORECLR_PROFILER
value: "{cf0d821e-299b-5307-a3d8-b283c03916dd}"
- name: CORECLR_PROFILER_PATH
value: "$(EXEM_DOTNET_HOME)/binary/Exem.DotNet.Profiler.so"
- name: DOTNET_STARTUP_HOOKS
value: "$(EXEM_DOTNET_HOME)/binary/startup/Exem.DotNet.Startup.Hook.dll"
- name: EXEM_DOTNET_PROFILE_TARGET_PROCESS
value: "<モニタリング対象DLL名>"
- name: EXEM_DOTNET_AGENT_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: EXEM_GROUP_ID
value: "dotnet"
- name: EXEM_RECEIVER_ADDR
value: "<収集サーバーIP>:9010"
- name: EXEM_RUN_ON_CONTAINER
value: "true"
- name: EXEMWID
valueFrom:
fieldRef:
fieldPath: metadata.uid
各項目の説明:
| 項目 | 説明 |
|---|---|
volumes.exem-volume | initContainerとアプリケーションコンテナが共有するPodストレージです。エージェントファイルがこのボリュームにコピーされます |
volumes.config-volume-dotnet-agent | ConfigMapをボリュームとしてマウントし、net.conf、calltree.advice設定を外部から注入します |
initContainers | エージェントイメージをinitContainerとして起動し、エージェントファイルをexem-volumeにコピーします |
containers.volumeMounts | アプリケーションコンテナがexem-volumeをマウントしてエージェントにアクセスできるようにします |
環境変数の説明:
| 環境変数 | 説明 | 備考 |
|---|---|---|
EXEM_DOTNET_HOME | エージェントのホームパス。固定値: /exem/dotnet | |
CORECLR_ENABLE_PROFILING | CoreCLRプロファイラーの有効化。固定値: 1 | |
CORECLR_PROFILER | プロファイラーのCLSID。固定値: {cf0d821e-299b-5307-a3d8-b283c03916dd} | |
CORECLR_PROFILER_PATH | Exem.DotNet.Profiler.soのパス。$(EXEM_DOTNET_HOME)を参照 | |
DOTNET_STARTUP_HOOKS | Startup Hook DLLのパス。$(EXEM_DOTNET_HOME)を参照 | |
EXEM_DOTNET_PROFILE_TARGET_PROCESS | モニタリング対象プロセス(DLL)名 | |
EXEM_DOTNET_AGENT_NAME | ExemONE画面に表示されるWAS名 | |
EXEM_GROUP_ID | WASグループID。未設定時はdefault | |
EXEM_RECEIVER_ADDR | 収集サーバーアドレス(IP:ポート) | |
EXEM_RUN_ON_CONTAINER | コンテナ環境での動作有無。コンテナ: true | |
EXEMWID | コンテナ連携用のキー。EXEM_RUN_ON_CONTAINER=true設定時のみ適用 |