Oracle APEX 24.2の新機能として追加されたOpenTelemetryの設定について確認してみました。Oracle APEX 24.2のRelease Notesの2. 31 Java Script Library Upgradesから確認できる範囲では、OpenTelemetry SDKとして、以下のライブラリがOracle APEXのフロントエンドに組み込まれています。
Oracle APEX 24.2で、OpenTelemetryによるクライアント側のテレメトリー・データの送信を有効にするために必要な設定は、それほど多くはありません。2.31 JavaScript Library Upgrades
- @opentelemetry/api 1.9.0
- @opentelemetry/core 1.26.0
- @opentelemetry/instrumentation 0.53.0
- @opentelemetry/instrumentation-document-load 0.39.0
- @opentelemetry/instrumentation-fetch 0.53.0
- @opentelemetry/instrumentation-xml-http-request 0.53.0
- @opentelemetry/sdk-trace-base 1.26.0
- @opentelemetry/sdk-trace-web 1.26.0
Oracle APEX 24.2では、ワークスペース・ユーティリティにOpenTelemetryが新設されました。
OpenTelemetryの構成としてクライアント・ロギング・サービスURLとトークン・リレーURLを設定します。
APEXアプリケーションのアプリケーション定義のユーザー・インターフェースに、OpenTelemetryのセクションが追加されています。そのセクションで製品ファミリを設定します。
クライアント・ロギング・サービスURL、トークン・リレーURLおよび製品ファミリといった設定がOpenTelemetryの何の設定に対応しているのか不明だったのですが、Oracle APEX 24.2のOpenTelemetryの対応は、OracleのSaaS製品が提供しているオブザーバビリティのフレームワークに送信することを想定しているようです。
OracleのSaaSに接続するのは難しいため、クライアント・ロギング・サービスURLとトークン・リレーURLの処理を、Oracle REST Data Servicesで実装してOracle APEX 24.2のOpenTelemetryの動作を確認します。
最初にクライアント・ロギング・サービスを実装します。
OpenTelemetryが有効化されたAPEXアプリケーションは、ブラウザよりトレース・データをHTTP/JSON形式でgzip圧縮して送信します。クライアント・ロギング・サービスURLは、このデータの送信先になります。この形式のデータは、OpenTelemetry Collectorのreceiverでも、そのまま受信可能と思われます。
受信したトレースを保存する表を作成します。表名はEBAJ_OTEL_TRACESとします。
create table ebaj_otel_traces (
id number generated by default on null as identity
constraint ebaj_otel_traces_id_pk primary key,
trace clob check (trace is json),
created date default on null sysdate
);以下は、SQLワークショップのSQLコマンドで実行した例です。
SQLワークショップのRESTfulサービスより、モジュールOpenTelemetryを作成します。
モジュール名はOpenTelemetry、モジュール・ベース・パスは/otel/とします。
作成したモジュールOpenTelemetryに、URIテンプレートとしてtracesを作成します。
テンプレートtracesに、POSTハンドラを登録します。
ソースとして以下を記述します。受信したデータをgzipで解凍し、取り出したJSONドキュメントを表EBAJ_OTEL_TRACESの列TRACEに保存します。
以上で、クライアント・ロギング・サービスは完成です。リソース・ハンドラの完全なURLはクライアント・ロギング・サービスURLとして設定するため、コピーして記録しておきます。
Oracle APEXのOpenTelemetryの実装では、クライアント・ロギング・サービスURLはOAuth2による認証で保護されていることが想定されています。トークン・リレーURLは、Authorizationヘッダーに設定するアクセス・トークンを取得する際に呼び出します。
クライアント・ロギング・サービスを実装したモジュールOpenTelemetryにアクセスする際に、OAuth2による認証を要求するように構成します。
以下のスクリプトを実行します。モジュールOpenTelemetryをOAuth2で保護し、そのアクセスに必要なclient_idとclient_secretを印刷します。
印刷されたclient_idとclient_secretは、APEXのWeb資格証明を作成する際に使用するため、コピーして記録しておきます。
作業の参考になるように、上記で作成したOAuth2のクライアント、権限およびロールを削除するスクリプトを掲載しておきます。
ワークスペース・ユーティリティのWeb資格証明を開き、新たにWeb資格証明を作成します。
作成するWeb資格証明の名前はOpenTelemetry、静的IDはOPENTELEMETRYとします。認証タイプはOAuth2クライアント資格証明を選択します。
クライアントIDまたはユーザー名に、先ほどのスクリプトの実行結果として印刷されたclient_idの値、クライアント・シークレットまたはパスワードに、client_secretの値を入力します。
以上で作成します。
Web資格証明としてOpenTelemetry（静的ID: OPENTELEMETRY）が作成されました。
このWeb資格証明を使ってアクセス・トークンを取得するサービスを、Oracle REST Data Servicesで作成します。このサービスがトークン・リレーになります。
RESTfulサービスを開き、モジュールを作成します。モジュール名はOpenTelemetry-Auth、ベース・パスは/otel-auth/とします。
テンプレートとしてtokenを作成します。
このトークン・リレーURLはAPEXのセッションで保護すべきですが、難しいため保護はかけていません。
以上でクライアント・ロギング・サービスURLとトークン・リレーURLの準備ができました。
ワークスペース・ユーティリティのOpenTelemetryを開き、それぞれの値を設定します。
テストに使用するAPEXアプリケーションを作成します。アプリケーション自体は何でもよいのですが、サンプル・データセットのEMP/DEPTをインストールしたときに作成できるアプリケーションを使うことにします。
サンプル・データセットを開き、EMP/DEPTをインストールまたは更新します。
インストールまたは更新が完了した後に表示される、アプリケーションの作成ボタンをクリックします。
アプリケーション作成ウィザードが開きます。
アプリケーションの名前をTest App for OpenTelemetryに変更し、アプリケーションの作成を実行します。
アプリケーションが作成されたら、アプリケーション定義のユーザー・インターフェースを開き、OpenTelemetryの製品ファミリにtest-appを設定します。
以上でテストの準備は完了です。
APEXアプリケーションを実行し、適当にアプリケーションを操作します。デバッグを有効にし、JavaScriptコンソールを開いてトークン・リレーURLやクライアント・ロギング・サービスURLの呼び出しが失敗していないことを確認します。失敗するとtelemetry.jsでエラーが発生し、JavaScriptコンソールに出力されます。
SQLワークショップのSQLコマンドを開き、表EBAJ_OTEL_TRACESにデータが書き込まれていることを確認します。
select count(*) from ebaj_otel_traces;
表EBAJ_OTEL_TRACESに保存されたデータを一覧するAPEXアプリケーションを作成します。Oracle APEX 24.2で追加されたJSONソースの機能を使います。
空のAPEXアプリケーションを作成します。名前はOpenTelemetry Trace Reportとします。
アプリケーションが作成されます。共有コンポーネントを開きます。
JSONソースを開きます。APEX 24.2の新機能です。
作成済みのJSONソースが一覧されます。作成をクリックします。
作成するJSONソースの名前はOpenTelemetry Tracesとします。JSONソース・タイプはJSON列のある表、JSON列のある表としてEBAJ_OTEL_TRACESを選択します。
次へ進みます。
JSON列1にTRACE(Clob)を選択します。JSONスキーマは無いため設定せず、すでに保存済みのデータより、データ・プロファイルを生成します。
次へ進みます。
列TRACEに保存済みのデータから、データ・プロファイルが作成されます。
列IDは表EBAJ_OTEL_TRACESの主キー列なので、デフォルトで主キーにチェックが入ります。列TRACEがJSONドキュメントとして認識されます。
列TRACEに保存されているJSONドキュメントの属性spansに、spanオブジェクトの配列が含まれます。spans配列中のspanオブジェクトを一意に識別する属性はspan_idであるため、SPAN_IDの主キーにチェックを入れます。
以上の設定を行い、作成をクリックします。
JSONソースとしてOpenTelemetry Tracesが作成されました。
作成したJSONソースOpenTelemetry Tracesをソースとした、対話モード・レポートとフォームのページを作成します。
ページの作成をクリックします。
対話モード・レポートを選択します。
ページの名前をSpansとし、フォーム・ページを含めるをオンにします。フォーム・ページ名はSpan Detailとします。
データ・ソースにJSONソースを選択し、JSONソースに先ほど作成したOpenTelemetry Tracesを選択します。ネストした行に列TRACEに含まれているJSON配列に当たる1.SPANSを選択します。
次へ進みます。
主キー列1にID (Number)、主キー列2にSPAN_ID (Varchar2)が選択されます。
確認してページの作成をクリックします。
OpenTelemetryのトレースと、トレースに含まれるspanを表示する対話モード・レポートとフォームのページが作成されました。
以上でアプリケーションは完成です。
アプリケーションを実行すると、受信したスパンの一覧が表示されます。
フォームを作成しているため、編集アイコンをクリックすると詳細情報が表示されます。
これでOracle APEX 24.2のOpenTelemetryについて、ある程度の評価ができそうです。
今回作成した、OpenTelemetryのスキャンを一覧するAPEXアプリケーションのエクスポートを以下に置きました。
https://github.com/ujnak/apexapps/blob/master/exports/opentelemetry_trace_report.zip
今回の記事は以上になります。
Oracle APEXのアプリケーション作成の参考になれば幸いです。
完
