はじめに

Oracle Cloud Infrastructure(以下、OCI)には、分散トレーシングを提供するOCI APMというマネージドサービスがあります。
本記事では、OKEにサンプルアプリケーションをデプロイしてOCI APMからトレーシングをしてみたいと思います。

分散トレーシングとは

Cloud Nativeな文脈では、Observabilityの一つの要素になり、各アプリケーション間のトランザクションや通信の状況を把握するための営みになります。
例えば、大量のサービスが連携しているマイクロサービス下でパフォーマンスの低下などが発生した場合にどのアプリケーション部分が原因になっているかを特定することができます。

OCI APMとは

OCI APMはOracle Cloud Observability and Management Platfotmの中のサービスの一つです。
その中でもOCI APMは、分散トレーシングや合成モニタリングなどを提供するサービスになります。

今回は、このOCI APMを利用して、OKE上のコンテナアプリケーションをトレーシングしてみたいと思います。

事前準備

まずは、事前準備をしていきます。

事前準備は以下の4つです。

ポリシーの作成
APMドメインの作成
OCIRレポジトリ作成
OKEクラスタの準備
サンプルアプリケーションの準備

ポリシーの作成

OCIでは各サービスを利用するためにポリシーを作成する必要がある場合があります。
OCI APMを利用する場合にもポリシーが必要なので、作成していきます。
トライアル環境や管理者権限をお持ちの環境で実施する場合は本手順は不要ですので、無視してください。

OCIコンソールのハンバーガーメニューを開き、「アイデンティティとセキュリティ」から「ポリシー」を選択します。

「ポリシーの作成」をクリックします。

以下の情報を入力します。
また、「手動エディタの表示」にチェックを入れます。

key	value
名前	apm_policy
説明	apm_policy
コンパートメント	ご自身のコンパートメント名
ポリシー	`Allow group APM-Admins to manage apm-domains in compartment id <ご自身のコンパートメントOCID>`

画像はイメージですので、コンパートメントOCIDはご自身の環境に合わせて読み替えてください。

「作成」をクリックします。

これで、ポリシーの設定は完了です。

APMドメインの作成

ここでは、APMドメインの作成を行います。

OCIコンソールのハンバーガーメニューを開き、「監視および管理」から「アプリケーション・パフォーマンス・モニタリング」カテゴリの「管理」を選択します。

「APMドメインの作成」をクリックします。

以下の情報を入力します。

key	value
名前	oke-handson-apm
説明	oke-handson-apm

「作成」をクリックします。

ドメインが「作成中」のステータスになるので、「アクティブ」になるまで待機します。

ドメインが「アクティブ」になったら、ドメイン名の箇所をクリックします。

「APMドメイン情報」の「データ・アップロード・エンドポイント」と「データ・キー」の「プライベート」キーの値をコピーし、エディタなどに記録しておきます。
この値は、アプリケーション側からトレーシング情報をAPMにアップロードする際のエンドポイントとその際に利用するキーになり、後ほど利用します。

これで、APMドメインの作成は完了です。

OCIRレポジトリの作成

後続手順で、サンプルアプリケーションをビルドして、コンテナイメージを作成します。
そのコンテナイメージを格納するコンテナイメージレジストリのセットアップを行います。

左上のハンバーガーメニューをクリックして、「開発者サービス」-「コンテナ・レジストリ」を選択します。

「リポジトリの作成」ボタンをクリックします。

「リポジトリ名」に「frontend-app-apm」と入力、「アクセス」で「パブリック」を選択して、「リポジトリの作成」ボタンをクリックします。

次に、OCIRにコンテナイメージをプッシュする際に必要となる、「Username」と「Password」を取得します。

「Username」は、<オブジェクト・ストレージ・ネームスペース>/<ユーザ名> となります。

＜ユーザ名＞を確認します。ユーザ名は右上にある「プロファイル」アイコンをクリックして、プロファイル名を選択します。

「ユーザーの詳細画面」の赤枠箇所をコピーして、テキストエディタにペーストしておきます。

次に、＜オブジェクト・ストレージ・ネームスペース＞を確認します。

右上にある「プロファイル」アイコンをクリックして、「テナンシ」を選択します。

「テナンシ詳細」の「オブジェクト・ストレージ・ネームスペース」の赤枠箇所をコピーして、テキストエディタにペーストしておきます。

次に、「Password」となる認証トークンを設定します。

右上にある「プロファイル」アイコンをクリックして、プロファイル名を選択します。

左メニュー「認証トークン」を選択します。

「トークンの作成」をボタンをクリックします。

「説明」に「oke-handson-apm」と入力して、「トークンの生成」ボタンをクリックします。

「コピー」をクリックして、「閉じる」ボタンをクリックします。コピーした認証トークンは、後の手順で必要となるので、テキストエディタなどにペーストしておきます。

以上で、認証トークンの作成は完了です。

以下、テキストエディタにペーストした内容に当てはめて利用します。

key	value
Username	`<オブジェクト・ストレージ・ネームスペース>/<ユーザ名>`
Password	`認証トークン`

以上でOCIRのセットアップは完了です。

OKEクラスタの準備

OKEクラスタはこちらの手順を参考に構築してください。

サンプルアプリケーションの準備

APMの動作確認用に簡単なアプリケーションを用意しました。
東京2020オリンピック・パラリンピック大会のメダル獲得者の一覧を表示するアプリケーションです。

以下のレポジトリを利用します。

git clone https://github.com/oracle-japan/code-at-customer-handson

今回のアプリケーションはHelidonを利用した構成になっています。
Helidonについてはこちらの記事で取り上げていますが、マイクロサービスに適したJavaアプリケーションフレームワークです。

Helidonでは、OCI APM用の専用エージェントが用意されており、依存関係(ライブラリ)と環境変数を設定するだけで利用できます。
詳細はこちらをご確認ください。

先ほどプロビジョニングしたOCI APMを利用するための設定をしていきます。

APMにはAPM Browser AgentとAPM Server Agentが存在するので、その両方を設定していきます。

サンプルアプリケーション(ブラウザ側)のAPM設定

まずは、APM Browser Agentから設定します。

フロントエンドアプリケーションのHTMLファイルを開きます。

vim code-at-customer-handson/olympic_frontend_apm/src/main/resources/web/index.html

~~~
    <script>
      window.apmrum = (window.apmrum || {}); 
      window.apmrum.serviceName='oke-helidon-demo-frontend-UI';
      window.apmrum.webApplication='OracleJetApp';
      window.apmrum.ociDataUploadEndpoint='https://xxxxxxxxxxxxxxx.apm-agt.us-ashburn-1.oci.oraclecloud.com';　#変更箇所1
      window.apmrum.OracleAPMPublicDataKey='<your-public-data-key>';　#変更箇所2
      window.apmrum.traceSupportingEndpoints =  [
        { headers: [ 'APM' ], hostPattern: '.*' },
      ]; 
    </script>
    <script async crossorigin="anonymous" src="https://xxxxxxxxxxxxxxx.apm-agt.us-ashburn-1.oci.oraclecloud.com/static/jslib/apmrum.min.js"></script> #変更箇所3
~~~

変更箇所	設定内容	備考
変更箇所1	APMドメインの作成で記録した「データ・アップロード・エンドポイント」
変更箇所2	APMドメインの作成で記録したデータ・キーの「パブリック」キー	プライベートキーではなく、パブリックキーとなるので注意してください。
変更箇所3	staticより前の部分`https～.com`までをAPMドメインの作成で記録した「データ・アップロード・エンドポイント」を設定します。

ソースコードを変更したので、コンテナイメージをビルドし、OCIR上にプッシュします。

cd code-at-customer-handson/olympic_frontend_apm

docker image build -t iad.ocir.io/<your-object-storage-namespace>/frontend-app-apm .

OCIRにログインします。「iad.ocir.io」エンドポイントについては、ビルド時と同様、環境に合わせてください。

Ashburn(us-ashburn-1)リージョンではない皆様
リージョンが、アッシュバーン(us-ashburn-1)ではない場合、環境に合わせて「iad.ocir.io」の部分も変更してください。
各リージョンのOCIRエンドポイントはこちらで確認できます。
ここでは、以降も「iad.ocir.io」で進めます。

「Username」と「Password」は、事前に確認した以下を入力します。

入力項目	入力内容
Username	`<オブジェクト・ストレージ・ネームスペース>/<ユーザ名>`
Password	`認証トークン`

docker login iad.ocir.io

docker image push iad.ocir.io/<your-object-storage-namespace>/frontend-app-apm

これでOCIRへのプッシュは完了です。

サンプルアプリケーション(サーバサイド側)のAPM設定

Manifestのあるディレクトリに移動します。

cd ~

cd code-at-customer-handson/k8s/app/for-oci-apm

フロントエンドアプリケーションのManifestをvimで開きます。

vim olympic_frontend.yaml


apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend-app
  labels:
    app: frontend-app
    version: v1
spec:
  replicas: 1
  selector:
    matchLabels:
      app: frontend-app
      version: v1
  template:
    metadata:
      labels:
        app: frontend-app
        version: v1
    spec:
      containers:
      - name: frontend-app
        image: iad.ocir.io/orasejapan/frontend-app-apm
        ports:
        - containerPort: 8082
        env:
        - name: tracing.data-upload-endpoint
          valueFrom:
            secretKeyRef:
              name: apm-secret
              key: endpoint
        - name: tracing.private-data-key
          valueFrom:
            secretKeyRef:
              name: apm-secret
              key: private-key
(省略)

25行目~35行目のenvフィールドにSecretから環境変数としてtracing.data-upload-endpoint、tracing.private-data-keyを読み込んでいます。
これと同じ設定をバックエンドアプリケーションとデータソースアプリケーションにも入れています。

ここで利用するSecretリソースを作成します。

項目	設定内容	備考
APMエンドポイント	APMドメインの作成で記録した「データ・アップロード・エンドポイント」
「データ・キー」の「プライベート」キー	APMドメインの作成で記録したデータ・キーの「プライベート」キー	パブリックキーではなく、プライベートキーとなるので注意してください。

kubectl create secret generic apm-secret --from-literal=endpoint=<APMエンドポイント> --from-literal=private-key=<「データ・キー」の「プライベート」キー>

これでサンプルアプリケーションのManifest設定の変更は完了です。

OCI APMでのトレーシング

いよいよ、OCI APMを利用したトレーシングを実施します。

OCI APMでの分散トレーシング

サンプルアプリケーションをデプロイします。

cd ~

cd code-at-customer-handson/k8s/app/for-oci-apm

kubectl apply -f .

コマンド結果

deployment.apps/backend-app-v1 created
deployment.apps/backend-app-v2 created
deployment.apps/backend-app-v3 created
service/backend-app created
deployment.apps/datasource-app created
service/datasource-app created
deployment.apps/frontend-app created
service/frontend-app created

アプリケーションにアクセスします。

kubectl get svc frontend-app

コマンド結果

NAME           TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)        AGE
frontend-app   LoadBalancer   10.96.110.178   146.56.xxx.xxx   80:31031/TCP   58s

上記の場合は、EXTERNAL-IPである146.56.xxx.xxxがエンドポイントになります。

この場合は、以下のURLにアクセスします。
http://146.56.xxx.xxx

何度かアクセスしたのちに、トレース情報をOCI APMから確認します。

OCIコンソールのハンバーガーメニューを開き、「監視および管理」から「アプリケーション・パフォーマンス・モニタリング」カテゴリの「トレース・エクスプローラー」を選択します。