Azure SDK documentation updateとして公開された「@azure/opentelemetry-instrumentation-azure-sdk 1.0.0」は、JavaScript／TypeScriptアプリでAzure SDKのOpenTelemetry計装を使っている開発者が確認すべきGAリリースです。結論から言うと、1.0.0-beta.10から1.0.0への昇格が中心で、PR上の差分はバージョン更新、SDK_VERSION更新、CHANGELOG追加です。既にbeta版を使っている場合は、依存関係の固定、ロックファイル、OpenTelemetryの登録順、Azure Monitor側の設定を確認してから本番反映するのが安全です。(GitHub)
今回のAzure SDK documentation updateで変わったこと
今回の更新は、Azure SDK for JavaScriptリポジトリのPR「[Release] @azure/opentelemetry-instrumentation-azure-sdk 1.0.0」によるものです。PRでは、@azure/opentelemetry-instrumentation-azure-sdkを1.0.0-beta.10から1.0.0 GAへ昇格させたことが明記されています。変更ファイルはCHANGELOG.md、package.json、src/configuration.tsの3つです。(GitHub)
| 確認項目 | 変更内容 | 実務での見方 |
|---|---|---|
| パッケージバージョン | 1.0.0-beta.10から1.0.0へ変更 | beta指定を続ける必要があるか見直す |
SDK_VERSION | 1.0.0へ更新 | テレメトリや診断情報上のSDKバージョン表記に影響する可能性がある |
| CHANGELOG | 1.0.0 (2026-05-05)として初の安定版リリースを追加 | リリース日ベースで社内変更管理に反映する |
| 検証結果 | ビルド成功、41件のテスト成功、lint／format問題なし | ただし自社アプリ側のE2E確認は別途必要 |
| API変更 | PR上は機能追加というよりGA化が中心 | 既存コードの大幅修正が必要とは限らない |
CHANGELOGでは、1.0.0は「Azure SDK OpenTelemetry Instrumentation library」の初の安定版リリースとして記載されています。直前の1.0.0-beta.10では@opentelemetry/instrumentation依存関係の更新、さらに過去のbetaではOpenTelemetry v2対応なども含まれているため、古いbetaから一気に上げる場合は差分を広めに確認してください。(GitHub)
対応が必要な人、様子見でよい人
このリリースは、すべてのAzure利用者に影響するものではありません。対象は主に、JavaScript／TypeScriptでAzure SDKクライアントライブラリを使い、OpenTelemetryによる分散トレーシングを有効化しているアプリケーションです。
| 利用状況 | 対応優先度 | 確認すべきこと |
|---|---|---|
@azure/opentelemetry-instrumentation-azure-sdkのbeta版を直接使っている | 高 | 1.0.0へ更新し、トレース出力を確認する |
| Azure Monitor OpenTelemetry経由でAzure SDKトレースを使っている | 中〜高 | バンドルされる計装設定、依存関係、ダッシュボード表示を確認する |
| Azure SDKは使っているがOpenTelemetryを使っていない | 低 | 今回の更新だけでアプリ挙動は変わりにくい |
| Application Insights SDKのみを使っている | 低〜中 | OpenTelemetry移行予定がある場合のみ調査する |
| 古いbeta版から更新する | 高 | OpenTelemetry v2系、spanステータス、環境変数設定の影響を確認する |
Azure SDKのトレーシングは、@azure/core-tracing側では既定でno-opのInstrumenterが使われ、OpenTelemetryベースのトレーシングを有効化するには@azure/opentelemetry-instrumentation-azure-sdkをインストールして登録する必要があります。つまり、パッケージがGAになったからといって、未設定のアプリで突然トレースが出始めるわけではありません。(GitHub)
GA化で「変わること」と「変わらないこと」
変わること
最も分かりやすい変化は、betaパッケージではなく安定版として扱えるようになったことです。社内ルールで「beta版やpreview版は本番利用不可」としている場合、1.0.0への昇格により採用しやすくなります。
また、package.jsonのバージョンとSDK_VERSION定数が1.0.0に更新されています。監視基盤やログにSDKバージョンを出している場合、リリース後に表示が変わる可能性があります。(GitHub)
変わらないこと
今回のPRだけを見る限り、Azure Storage、Key Vault、Cosmos DBなど各AzureサービスのAPI呼び出し仕様が変わる更新ではありません。アプリケーションロジックそのものより、観測性、依存関係、リリース管理に関わる変更と捉えるのが現実的です。
ただし、古いbeta版から更新する場合は別です。過去のbetaリリースではOpenTelemetryパッケージ更新やspanの扱いに関する変更が含まれているため、1.0.0-beta.10からの更新と、1.0.0-beta.6や1.0.0-beta.8からの更新ではリスクが異なります。現在使っているバージョンを先に確認してください。
移行前に確認するチェックリスト
本番反映前に、まず次の順で確認すると手戻りを減らせます。
| 手順 | コマンド・確認内容 | 判断基準 |
|---|---|---|
| 現在の利用有無を確認 | npm ls @azure/opentelemetry-instrumentation-azure-sdk | 直接依存か推移的依存かを確認する |
| beta指定を確認 | package.json、package-lock.json、pnpm-lock.yaml、yarn.lock | 1.0.0-beta.*が残っていないか見る |
| Node.jsバージョンを確認 | CI、Dockerfile、App Service、Functionsなど | パッケージのenginesはnode >=20.0.0 |
| OpenTelemetry登録順を確認 | アプリ起動時の初期化ファイル | Azure SDKクライアントの読み込み前に登録できているか |
| トレース出力を確認 | Application Insights、Azure Monitor、OTLP Collectorなど | 代表的なAzure SDK呼び出しでspanが出るか |
| アラート影響を確認 | 依存関係マップ、失敗率、レイテンシ、サンプリング | span名や件数の変化で誤検知しないか |
現在のpackage.jsonでは、@opentelemetry/api、@opentelemetry/core、@opentelemetry/instrumentationなどが依存関係に含まれ、enginesにはnode >=20.0.0が指定されています。Node.js 18以前で動かしている古いアプリや、CIだけ古いNode.jsを使っている環境では、更新前にランタイムを確認してください。(GitHub)
更新手順の例
まず、現在のバージョンを確認します。
npm ls @azure/opentelemetry-instrumentation-azure-sdkbeta版を使っている場合は、明示的に1.0.0へ更新します。
npm install @azure/[email protected]pnpmを使っている場合は次のように更新します。
pnpm add @azure/[email protected]yarnの場合は次の通りです。
yarn add @azure/[email protected]更新後は、ロックファイルを含めて差分を確認します。
npm ls @azure/opentelemetry-instrumentation-azure-sdk
npm test単にインストールするだけではテレメトリは出力されません。OpenTelemetry SDK側のTracer Provider、Exporter、Resource、Samplerなどの構成が必要です。公式READMEでも、テレメトリデータを生成するにはOpenTelemetry SDKの構成が必要と説明されています。(GitHub)
登録コードで見直すべきポイント
このライブラリの中心は、createAzureSdkInstrumentationです。OpenTelemetryのregisterInstrumentationsに登録することで、Azure SDK向けの計装を有効化します。公式READMEでは、createAzureSdkInstrumentationがOpenTelemetryへ登録するAzure SDK Instrumentationオブジェクトを作る主要なフックとして説明されています。(Microsoft Learn)
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { createAzureSdkInstrumentation } from "@azure/opentelemetry-instrumentation-azure-sdk";
registerInstrumentations({
instrumentations: [createAzureSdkInstrumentation()],
});実務では、次の点が重要です。
| 確認点 | なぜ重要か |
|---|---|
| アプリ起動の早い段階で登録する | Azure SDKクライアント読み込み後だと、期待したspanが取れない場合がある |
| Provider／Exporterを別途設定する | 計装だけでは送信先が決まらない |
| サンプリング設定を確認する | spanが出ていないように見えて、実際はサンプリングで落ちていることがある |
| ローカルと本番で環境変数を比較する | 本番だけトレース無効化設定が入っているケースがある |
特に注意したいのは、「登録したのにAzure SDKのspanが見えない」というケースです。原因はライブラリの不具合とは限りません。登録順、サンプリング、Exporter設定、接続文字列、環境変数、Collector側のフィルタリングを順に切り分けてください。
Azure Monitor OpenTelemetryを使っている場合の確認点
@azure/monitor-opentelemetryを使っている場合は、スタンドアロンの@azure/opentelemetry-instrumentation-azure-sdkを直接登録している構成とは確認箇所が異なります。Azure Monitor OpenTelemetryのREADMEでは、Azure SDK、Azure Functions、MongoDB、MySQL、PostgreSQL、Redisなどのinstrumentationが分散トレーシング向けに既定で有効と説明されています。(GitHub)
そのため、次の観点で確認します。
| 確認対象 | 見るべきポイント |
|---|---|
instrumentationOptions.azureSdk | 明示的に無効化していないか |
| Application Insights接続文字列 | APPLICATIONINSIGHTS_CONNECTION_STRINGが正しく設定されているか |
| サンプリング | OTEL_TRACES_SAMPLERやOTEL_TRACES_SAMPLER_ARGで意図せず落としていないか |
| ESMアプリ | loaderや初期化順が正しいか |
| ダッシュボード | 依存関係、トレース、失敗率の表示に変化がないか |
Azure Monitor OpenTelemetry側の設定と、このAzure SDK instrumentationパッケージのGA化を混同しないことも大切です。今回の更新はAzure SDK用のOpenTelemetry計装ライブラリのGA化であり、監視基盤全体の設計変更を強制するものではありません。
環境変数でトレースが無効化されていないか確認する
過去のCHANGELOGでは、AZURE_TRACING_DISABLEDをtrueにすることでAzure SDK spanの記録を無効化できること、AZURE_HTTP_TRACING_CHILDREN_DISABLEDでcore HTTP span配下の子span記録を制御できることが記載されています。現在のconfiguration.tsにも、これらの環境変数キーが含まれています。(GitHub)
本番だけspanが出ない場合は、アプリコードより先に環境変数を確認してください。
echo $AZURE_TRACING_DISABLED
echo $AZURE_HTTP_TRACING_CHILDREN_DISABLEDコンテナ環境では、Dockerfile、KubernetesのConfigMap／Secret、Azure App Serviceのアプリケーション設定、GitHub ActionsやAzure Pipelinesの環境変数に古い設定が残っていることがあります。
失敗しやすいポイント
インストールだけで監視できると思い込む
@azure/opentelemetry-instrumentation-azure-sdkはAzure SDK向けの計装ライブラリです。Exporterではありません。Application Insights、Azure Monitor、OTLP Collector、Jaegerなどへ送る設定は別途必要です。
betaからGAに上げてもロックファイルが古い
package.jsonだけを更新しても、ロックファイルにbeta版が残ることがあります。CIでnpm ciを使っている場合、ロックファイルが優先されるため、手元では更新済みでもビルド環境では旧版のままになることがあります。
古いbetaからの更新差分を軽く見る
1.0.0-beta.10から1.0.0への差分は小さく見えます。しかし、古いbetaから更新する場合は、OpenTelemetry依存関係やspanの扱いに関する過去の変更もまとめて取り込むことになります。特に監視ダッシュボードやアラートがspan属性に依存している場合は、ステージング環境で比較してください。
HTTP spanとAzure SDK spanの見え方を誤解する
Azure SDKの操作spanと、その下位にあるHTTP通信のspanが並んで見えることがあります。これは必ずしも「二重計測の不具合」ではありません。依存関係マップやトレースツリーで親子関係を確認し、必要に応じてサンプリングや表示側のフィルタを調整します。
Node.jsの実行環境を確認しない
開発端末は新しいNode.jsでも、CI、Dockerイメージ、本番ホストだけ古いことがあります。今回のパッケージのengines指定はnode >=20.0.0です。Azure Functions、App Service、コンテナ、オンプレミス実行環境でNode.jsバージョンが揃っているか確認してください。(GitHub)
本番反映前のおすすめ検証シナリオ
ステージング環境では、単にテストが通るかだけでなく、実際にAzure SDKの呼び出しを発生させてトレースを確認します。
| シナリオ | 確認する内容 |
|---|---|
| Key Vaultからシークレットやキーを取得 | Azure SDK操作spanが記録されるか |
| StorageへBlobをアップロード | 依存関係、レイテンシ、エラー時のspan状態を確認 |
| 失敗するリクエストを意図的に発生 | 例外、ステータス、アラートが想定通りか |
| サンプリング率を下げた状態で実行 | span欠落と設定ミスを区別できるか |
| 本番相当の起動方法で実行 | ESM、CommonJS、loader、初期化順の差を確認 |
監視の移行では、「トレースが出る」だけでは不十分です。運用チームが普段見ているダッシュボードで、依存関係名、エラー率、レイテンシ、相関ID、ログとの関連付けが維持されているか確認してください。
今回の更新をどう扱うべきか
今回のAzure SDK documentation updateは、@azure/opentelemetry-instrumentation-azure-sdkを本番採用しやすくする重要な節目です。1.0.0-beta.10から使っているチームにとっては、比較的低リスクなGA追従として扱える可能性があります。一方、古いbeta版から更新する場合や、Azure Monitor OpenTelemetry、独自OTLP Collector、複雑なサンプリング設定を組み合わせている場合は、テレメトリの見え方が変わらないか慎重に確認すべきです。
まずやるべきことは明確です。現在の利用バージョンを確認し、beta指定を1.0.0へ更新できるか判断し、ステージング環境で代表的なAzure SDK呼び出しのトレースを確認してください。そのうえで、ロックファイル、Node.jsバージョン、環境変数、Azure Monitor側の設定を点検すれば、本番移行時のトラブルをかなり減らせます。
コメント