自動計装をやってみる
それでは、早速、計装をやってみましょう。
今回は “RealWorld example apps” という、ある共通の仕様のブログアプリケーションを、さまざまな言語で実装して公開しているコードレポジトリから、FastAPIを利用してバックエンドのAPIを記述しているプロジェクトのサンプルアプリケーションを利用します。
アプリケーションの実行環境の構築は、紙面の都合から割愛します。
コードレポジトリのREADMEに記載されている前提やインストール・構成方法、レポジトリ内のMakefileを確認しながら環境構築をすることになりますが、本アプリケーションはPostgreSQLをdocker-composeで起動し、ローカル環境またはdocker上でアプリケーションを起動する形を取っています。起動したアプリケーションにアクセスをすると、Swagger画面が表示され、APIを実行することができるようになっています。
また、筆者は本アプリケーションを実行するホスト上にOpenTelemetry Collectorを導入済みです。今回の計装でも、アプリケーションから出力したテレメトリーデータはこのOpenTelemetry Collectorに送信するように構成していきます。また、オブザーバビリティバックエンドにはSplunk Observability Cloudを利用するように構成してあります。
利用する言語がOpenTelemetryの自動計装に対応しているのであれば、まずは自動計装からはじめてみるのがよいでしょう。
自動計装の基本的なアプローチは、（1）言語別のエージェントやパッケージをダウンロードし、（2）アプリケーション起動時に読み込むというシンプルなものです（公式ドキュメント）。
以下のコマンドを実行することで、適切なパッケージがダウンロードされます。
$ pip install opentelemetry-distro opentelemetry-exporter-otlp $ opentelemetry-bootstrap -a install
opentelemetry-distroパッケージには、APIやSDK、opentelemetry-bootstrapと opentelemetry-instrumentといったツール群が含まれています。opentelemetry-bootstrapコマンドを実行することで、既に導入済みのパッケージに対応するOpenTelemetryのライブラリをインストールしてくれるようになっています。
次に、エージェントの設定を行います。
これらの設定は、アプリケーション起動時の引数として指定することも可能ですが、今回は事前に環境変数を設定しておきます。
$ export OTEL_SERVICE_NAME='codezine-fastapi-app' $ export OTEL_EXPORTER_OTLP_ENDPOINT='http://localhost:4317' $ export OTEL_RESOURCE_ATTRIBUTES='deployment.environment=codezine-sample-env,service.version=0.1'
OTEL_SERVICE_NAMEは、アプリケーションの名前に相当し、オブザーバビリティバックエンドにおいてサービス名として表示されることになります。
OTEL_EXPORTER_OTLP_ENDPOINTは、テレメトリーデータをOTLP形式で送信する先を指定する設定で、今回は同一ホスト上のOpenTelemetry Collectorでテレメトリーデータを集約するように指定しています。
OTEL_RESOURCE_ATTRIBUTESは、テレメトリーデータに付与するkey-value形式の属性（attribute）です。今回はdeployment.environment（システム環境名）として codezine-sample-envを、service.version（アプリケーションのバージョン）として0.1を、それぞれ指定しています。属性としては他にも任意のkey-valueを指定できますが、基本的にOpenTelemetryが定めるSemantic Conventionに準拠することが望ましいので、あわせて確認するようにしましょう。
これらの設定を行った上で、opentelemetry-instrumentと共にアプリケーションを起動します。
今回のアプリケーションの起動コマンドは以下なので、この先頭にopentelemetry-instrumentを追加します。
## 通常の起動コマンド（Makefile内で定義されているコマンドを抜き出し） $ uvicorn conduit.app:app --host 0.0.0.0 ## opentelemetry-instrument を実行するために、以下に変更 $ opentelemetry-instrument uvicorn conduit.app:app --host 0.0.0.0
そのうえで、アプリケーションにアクセスして、なんらかの処理を試してみましょう。こんな感じのSwaggerからAPIを実行できるので、いくつか処理を実施していきます。
うまくアプリケーションが動き、自動計装もうまくいっていれば、オブザーバビリティバックエンドで処理の状況などを確認できるようになるはずです。
トレースも確認できるようになりました。
任意のトレースを開いてみると、ウォーターフォール形式でのトレース図が表示されるはずです。
ちなみに、アプリケーションが何らかの理由でうまく動かずエラーを返す場合、自動計装していると、そのエラーが発生した処理について、詳細を理解する助けになるかもしれません。
以下はあえて500：Internal Server Errorが起きる処理を実施した場合のトレースですが、アラートマークが表示されています。
加えて詳細のウォーターフォールチャートから、エラーとなったスパンを確認してみると、exception.messageやexception.stacktraceなどを確認することができるはずです。
わざわざサーバーにログインして、ログファイルを探すなどせずとも、これぐらいの情報は参照できるようになるのも、自動計装の恩恵の一つと言えます。
こういった形で、特にコード自体には手を入れることなくテレメトリーデータを取得できるようになるのが、自動計装のありがたいところです。
