開発用テレメトリビューア

トレーシングは、運用基盤が整ってから有効にするもの——普通はそう考えます。しかしいま自分がいるループにとって、その順序は逆です。読みたいスパンは、たったいま壊したリクエストのスパンです。それを読むためにコレクタを立ち上げるのは、修正そのものより手間がかかります。

そこで pw dev がコレクタの役を引き受けます。ループの開始と同時にループバックの OTLP レシーバとブラウザ UI が起動し、アプリケーションは起動前にそこを向くよう設定されます。

pw dev: telemetry viewer http://127.0.0.1:54321
pw dev:   traces and logs export to OTEL_EXPORTER_OTLP_ENDPOINT as service "myapp"

この URL を開いてください。既定で有効なので、これは何も設定していないプロジェクトの状態です。

最近のトレースとログ、プロセスのメモリやスレッド数を表示するテレメトリビューア

アプリケーションはどうやって見つけるのか

pw dev はポートを確保し、起動するプロセスに 3 つの環境変数を渡します。

変数	値
`OTEL_EXPORTER_OTLP_ENDPOINT`	ビューアのループバック URL
`OTEL_EXPORTER_OTLP_PROTOCOL`	`http/protobuf`
`OTEL_SERVICE_NAME`	`popcornweb.toml` の `project.name`

いずれも Popcorn Web 固有の名前ではなく OTLP の慣習です。そこが要点で、どのエクスポータもこの名前を見つけますし、開発用のエンドポイントをファイルにコミットする必要もありません。

ここに無いものに注目してください。observability.otel.enabled = true はどこにもありません。エンドポイントを指定することが、そのまま送信を有効にするからです。どこに送るかを書いた設定は、送ると言ったのと同じことです。実際に設定されるキーは [observability.otel] にあり、そのすべてが設定サマリにも現れます。

何が見えるのか

トレース。 すべてのリクエストには、フレームワークのミドルウェアチェイン全体を覆うルートスパンがあり、そこにリクエストトレーシングのレンダー・境界・文のスパンがぶら下がります。注入されたエンドポイントがそれらも一緒に有効にするので、ページはシェルがコミットされた時刻、各 await 境界がフォールバックを表示し続けた時間、その内側で走った SQL を持つ木として届きます。 pw.StartSpan で開いたスパンも同じ木に入り、記録されたエラーも一緒に届きます。

ログ。 pw.Logger のレコードは、書かれた時点で有効だったスパンと関連づけられた状態でビューアに届きます。トレースとそのログ行が 2 回の検索ではなく 1 つのビューになります。開発環境ではターミナルにも出続けます。他の環境ではレコードはコレクタか stdout のどちらか一方に行きますが、自分が見ているループのターミナルを空にするのは改善ではありません。

プロセスの状態。 ビューアはアプリケーションプロセスの CPU、メモリ、スレッド数、オープンファイル数、I/O をサンプリングします。pw dev はリビルドのたびにプロセスを差し替えるので、サンプラも新しいプロセスを追いかけます。すでに存在しない pid を報告し続けることはありません。

メトリクス。 レシーバは /v1/metrics を受け付けますが、フレームワークは何も出しません。アプリケーション自身がエクスポートしない限り、このビューは空のままです。

ディスクには何も書きません。ビューアはテレメトリをメモリだけに保持し、実行の終了とともに消えます。だから有効にしたままにしておけます。

設定

[dev.otel]
enabled = true   # 既定値
# port = 0       # 0 なら空いているループバックポートを確保する
# max = 0        # シグナルごとの保持件数。0 ならビューアの既定値

ポートの既定値が 0 なのは、開発用の認証プロバイダと同じ理由です。解決されたアドレスは書き留めるのではなく注入されるので、固定の番号に利点がなく、複数のプロジェクトで同時に pw dev を動かせます。

max は各シグナルが古いものを捨て始めるまでの保持件数です。長いセッションで目当てのリクエストが流れていってしまうなら上げてください。代償は実行中に確保するメモリです。

起動しない場合

自分のコレクタへの送信が優先されます。環境変数 OTEL_EXPORTER_OTLP_ENDPOINT がすでに設定されていれば、pw dev はそう伝えて何も起動しません。

pw dev: telemetry viewer skipped; OTEL_EXPORTER_OTLP_ENDPOINT already points at http://localhost:4318

誰も送ってこないビューアは、空のページを表示するためにポートを占有するだけです。同じ規則は注入される変数ひとつひとつに適用されます。自分で export した値が上書きされることはありません。

enabled = false は、どちらも要らないループのためのもうひとつの方法です。

適用範囲

このビューアは pw dev のものであり、それ以外のものではありません。 pw build でも go test でも、デプロイ先の環境でも決して起動せず、ループバックにしかバインドしません。ステージングや本番で実際のコレクタに届くのは、通常の [observability.otel] 設定であり、同じプロトコルで自分が選んだアドレスに送られます。