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

.NET Agent インストール

1. モジュールの説明​

exem-dotnet-agentは、Linux環境の.NET(CoreCLR)ベースのプロセスのトランザクション、SQL、Call Tree、例外データを収集してExemONEに送信するモニタリングエージェントです。

2. サポート環境​

項目内容
OSLinux
Arch64bit
Runtime.NET 6.0以上 (CoreCLR)
PlatformOn-premise
Docker
Kubernetes
FrameworkASP.NET Core (Kestrel)
DBSQL Server (Microsoft.Data.SqlClient.dll)
HTTPRemote Call (System.Net.Http)
Socket
ProtocolTCP 9010 → Receiver
PrereqCoreCLRプロファイリング環境変数の設定が必須
OtherCustom 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.confexem/dotnet/cfg/agent/net.confReceiver接続アドレス、WAS名などの基本設定
profile.confexem/dotnet/cfg/profile.confプロファイラーの動作設定
x.adviceexem/dotnet/cfg/x.adviceトランザクション開始点の収集のためのメソッドweave設定
x.callback.confexem/dotnet/cfg/x.callback.confコールバックメソッド設定

net.confの主要設定項目:

設定項目説明備考
EXEM_GROUP_IDWASグループID。未設定時はdefault環境変数での指定も可能
EXEM_RECEIVER_ADDR収集サーバーアドレス(IP:ポート)環境変数での指定も可能
EXEM_DOTNET_AGENT_NAMEExemONE画面に表示されるWAS名環境変数での指定も可能

3. 必須環境変数の設定​

CoreCLRプロファイラーの有効化のため、以下の環境変数を設定します。

環境変数説明値の例
EXEM_DOTNET_HOMEエージェントのホームパス(exem/dotnetディレクトリ)/opt/exem/dotnet
CORECLR_ENABLE_PROFILINGCoreCLRプロファイラーの有効化有無1
CORECLR_PROFILERロードするプロファイラーのCLSID{cf0d821e-299b-5307-a3d8-b283c03916dd}
CORECLR_PROFILER_PATHExem.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-volumeinitContainerとアプリケーションコンテナが共有するPodストレージです。エージェントファイルがこのボリュームにコピーされます
volumes.config-volume-dotnet-agentConfigMapをボリュームとしてマウントし、net.conf、calltree.advice設定を外部から注入します
initContainersエージェントイメージをinitContainerとして起動し、エージェントファイルをexem-volumeにコピーします
containers.volumeMountsアプリケーションコンテナがexem-volumeをマウントしてエージェントにアクセスできるようにします

環境変数の説明:

環境変数説明備考
EXEM_DOTNET_HOMEエージェントのホームパス。固定値: /exem/dotnet
CORECLR_ENABLE_PROFILINGCoreCLRプロファイラーの有効化。固定値: 1
CORECLR_PROFILERプロファイラーのCLSID。固定値: {cf0d821e-299b-5307-a3d8-b283c03916dd}
CORECLR_PROFILER_PATHExem.DotNet.Profiler.soのパス。$(EXEM_DOTNET_HOME)を参照
DOTNET_STARTUP_HOOKSStartup Hook DLLのパス。$(EXEM_DOTNET_HOME)を参照
EXEM_DOTNET_PROFILE_TARGET_PROCESSモニタリング対象プロセス(DLL)名
EXEM_DOTNET_AGENT_NAMEExemONE画面に表示されるWAS名
EXEM_GROUP_IDWASグループID。未設定時はdefault
EXEM_RECEIVER_ADDR収集サーバーアドレス(IP:ポート)
EXEM_RUN_ON_CONTAINERコンテナ環境での動作有無。コンテナ: true
EXEMWIDコンテナ連携用のキー。EXEM_RUN_ON_CONTAINER=true設定時のみ適用