はじめに
OpenTelemetryの基本から、ご自身のトレースがObservatoryに届くまで。各手順は前の手順を前提にしているので、順番に進めてください。
OpenTelemetryについて
まずOpenTelemetryから
Dartasticは、ソフトウェアの動作を記録するためのオープン標準であるOpenTelemetry(OTel)の上に構築されています。DartasticはOpenTelemetryの仕様に忠実に従っており、名前、データ、送信方法はすべて標準のものです。OpenTelemetryについて学んだことはDartasticにもそのまま当てはまり、Dartasticで作ったものは標準のOpenTelemetryのままです。
仕様はわかりやすく書かれています。先に進む前に、OpenTelemetryのドキュメントを1時間ほど読んで、基本を押さえてください:
- OpenTelemetryとは?
- オブザーバビリティ入門
- シグナル:以下で説明する3種類のデータ
3つのシグナル
OpenTelemetryは、シグナルと呼ばれる3種類のデータを記録します:
- トレース
- 何が起きたかを一歩ずつ、各ステップにかかった時間とともに記録します。トレースはスパンのツリーです:タップ、そのタップによるネットワーク呼び出し、その呼び出しを処理するサーバー側の処理、その下のデータベースクエリ。1つのトレースが、アプリからサーバーまでつながることもあります。
- メトリクス
- 時間とともに測定される数値:フレーム時間、メモリ、1分あたりのリクエスト数、リリースごとのエラー数。保持のコストが低いため、傾向の把握やアラートに使われます。
- ログ
- 時刻と重大度を持つテキストの行です。OpenTelemetryのログは、書き込まれた時点のトレースを保持しているため、ログからその瞬間に起きたほかの出来事をすべて開けます。
3つのシグナルはいずれもリソースを持ちます:どのアプリが、どのバージョンで、どの端末から送ったか。Dartasticはその上にリアルユーザーモニタリング(セッション、画面、タップ、リプレイ)を加え、これも標準のシグナルとして記録します。このヘルプで使うほかの用語は概要で説明しています。
1. ログイン
dartastic.ioにログイン。初回は、お客様の組織を設定します。組織とは、トークン、チームメンバー、プランが属するアカウントです。チームメンバーから招待された場合は、招待されたメールアドレスでログインすると、その組織に参加します。
登録すると、組織はCloud Freeで始まり、カードは不要です。次の項目を設定します。
- 組織名とサブドメイン:組織の名前と、アプリがテレメトリーを送信するサブドメインです。サブドメインはずっとお客様のものです。
- リージョン:テレメトリーを保存する場所です。後から変更することはできません。
- RUMの上限:エンジンが記録できる最も高いリプレイレベルです。Cloud FreeはWireframeまでで、ShadowとPixelは有料プランで利用できます。選んだ内容でエンジンを生成するため、端末側でそれを超えることはできません。
- Dartastic AI:自社のモデルキーで動作します。モデルキーは、その場でも後からでも追加できます。
Dartastic Pubだけを使う場合は、登録の前に料金ページでPubのプランを選んでください。組織に名前を付けてリージョンを選ぶだけで、ほかに尋ねられることはありません。
Control Roomが開きます。Organizationに、組織の名前とIDが表示されます。
2. Reference Demoをダウンロード
Control Roomの上部にあるReference Demoを押し、展開します。実行するのは手順5です。Dartasticが動く様子を最も早く確かめられ、そのコードからすべての機能の使い方がわかります。Reference Demoの詳細。
3. dart pubをDartastic Pubに接続
Dartasticのパッケージは、pub.devではなくお客様のDartastic Pubから取得します。dart pubがそこから読み取るにはトークンが必要です。ほとんどの開発者にとって初めての作業ですが、1台のコンピューターにつき1回、1分ほどで終わります。
Dartastic Pubは、pub.devへのパススルーとしても機能します。これまでどおりpubspec.yamlにパッケージを定義すれば、pub.devのパッケージはpub.devから自動的に解決され、Dartasticのパッケージやお客様のプライベートパッケージと一緒に使えます。
- Control RoomでTokensを開きます:

- Pubトークンを発行します。+ Pubを押すと、ダイアログが開きます:

- Name:トークンを見分けられる任意の名前。
pub-org-read-writeをおすすめします。 - Organization:このトークンでパッケージを読み取り、公開する組織。
- Allow write (publish) access:このトークンでDartastic Pubに公開する場合はチェックします。チェックしないと読み取り専用のトークンになります。Reference Demoでは、お客様のPubに公開する
symbolizer_demo_flutterとcrash_demo_flutter以外は、それで十分です。
- Name:トークンを見分けられる任意の名前。
- Generateをクリックします。トークンは一度だけ表示されます:
今すぐコピーボタンでトークンをコピーしてください。このダイアログを閉じると、二度と表示できません。Granted scopes: Pubは、このトークンがPub専用であることを示します。テレメトリーの送信や、ほかのサービスの呼び出しには使えません。
- コマンドシェルで、トークンを
dart pubに渡します:shelldart pub token add https://pub.dartastic.ioEnter secret token:と表示されたらトークンを貼り付け、Enterキーを押します。貼り付けても何も表示されませんが、正常です。次のように表示されます:terminalEnter secret token: Requests to "https://pub.dartastic.io" will now be authenticated using the secret token. - Reference Demoのフォルダーで、パッケージを取得します: 成功すれば、Pubとトークンは正しく機能しています。shell
flutter pub get
dart pubはトークンをそのホスト用に保存し、そのホストにだけ送信します。トークンの一覧表示、置き換え、削除と、パッケージの公開についてはPubで説明しています。
Pubトークンで使えるパッケージ
Pubトークンで使えるのは、その所有者が使えるパッケージだけです。
- 組織の管理者は組織内のすべてのパッケージを使えるため、そのトークンも同じです。
- ほかのチームメンバーは、割り当てられたパッケージのトークンしか発行できません。チームメンバーにパッケージを割り当てるのは管理者です。
ロールについてはチームメンバーを招待を、組織のメンバーへのパッケージの割り当てについてはPubを参照してください。
4. アプリからテレメトリーを送れるようにする
TokensでOTLPトークンを発行し、OpenTelemetry標準の形式でシェルにエクスポートします。authorizationは小文字のままにしてください:
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <your OTLP token>"5. デモを実行
Dockerを起動した状態で、Reference Demoのフォルダーから天気デモを起動し、端末を選びます:
tool/launch.sh weather_flutterタップして天気を取得します。このタップでトレースが始まり、アプリ、天気API、そのキャッシュ、外部の天気サービスを通ります。
6. Observatoryで確認
タップは数秒でObservatoryに届きます。アプリには、送信した内容へのリンクがあります。リンクをたどってトレースを開くと、すべてのステップと、それぞれにかかった時間がわかります。
次のステップ
- 初めてのアプリを作る:各パッケージに必要なFlutterとDartのバージョン。
- チームメンバーを招待:チームメンバーが初めてログインする前に。
- アプリにOTelを追加する:ご自身のアプリにDartasticを追加する方法。