このヘルプにはCloudのURLが表示されています。Dedicatedでログインすると、お客様のサーバーのURLが表示されます。

はじめに

OpenTelemetryの基本から、ご自身のトレースがObservatoryに届くまで。各手順は前の手順を前提にしているので、順番に進めてください。

OpenTelemetryについて

まずOpenTelemetryから

Dartasticは、ソフトウェアの動作を記録するためのオープン標準であるOpenTelemetry(OTel)の上に構築されています。DartasticはOpenTelemetryの仕様に忠実に従っており、名前、データ、送信方法はすべて標準のものです。OpenTelemetryについて学んだことはDartasticにもそのまま当てはまり、Dartasticで作ったものは標準のOpenTelemetryのままです。

仕様はわかりやすく書かれています。先に進む前に、OpenTelemetryのドキュメントを1時間ほど読んで、基本を押さえてください:

3つのシグナル

OpenTelemetryは、シグナルと呼ばれる3種類のデータを記録します:

トレース
何が起きたかを一歩ずつ、各ステップにかかった時間とともに記録します。トレースはスパンのツリーです:タップ、そのタップによるネットワーク呼び出し、その呼び出しを処理するサーバー側の処理、その下のデータベースクエリ。1つのトレースが、アプリからサーバーまでつながることもあります。
メトリクス
時間とともに測定される数値:フレーム時間、メモリ、1分あたりのリクエスト数、リリースごとのエラー数。保持のコストが低いため、傾向の把握やアラートに使われます。
ログ
時刻と重大度を持つテキストの行です。OpenTelemetryのログは、書き込まれた時点のトレースを保持しているため、ログからその瞬間に起きたほかの出来事をすべて開けます。

3つのシグナルはいずれもリソースを持ちます:どのアプリが、どのバージョンで、どの端末から送ったか。Dartasticはその上にリアルユーザーモニタリング(セッション、画面、タップ、リプレイ)を加え、これも標準のシグナルとして記録します。このヘルプで使うほかの用語は概要で説明しています。

ビルドDartasticアーキテクチャユーザートークンIssuePubトークンプッシュCIトークン交換アプリをユーザーへ配布:アプリストア、Web、サーバーシンボルクラッシュスタックトレースソーステレメトリー開発用コンピューターflutter run · dart pub getCIGitHub Actions、GitLab、…Control Roomトークン発行 · ロールベースのアクセス制御コントロールプレーン組織 · ロール · トークンDartastic Pubパッケージ · ソースObservatoryセッション · トレース · ログSymbolizerクラッシュ → ソースコードの行Dartastic AI両方のデータから回答IssueトラッカーGitHub · Jira · Linearモバイル・デスクトップアプリスマートフォン · タブレット · デスクトップOTLPトークンで送信Webアプリブラウザーで動作Browser OTLPトークンで送信Dartサーバーバックエンド · サービスOTLPトークンで送信

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のパッケージやお客様のプライベートパッケージと一緒に使えます。

  1. Control RoomでTokensを開きます:
    Control Roomの「Tokens」画面:「Generate Token」と、「+ Pub」、「+ Symbolizer」、「+ OTLP」、「+ Browser OTLP」
  2. Pubトークンを発行します。+ Pubを押すと、ダイアログが開きます:
    「Generate Pub Token」ダイアログ:「Name」、トークンが許可する内容、組織、「Allow write (publish) access」
    • Name:トークンを見分けられる任意の名前。pub-org-read-writeをおすすめします。
    • Organization:このトークンでパッケージを読み取り、公開する組織。
    • Allow write (publish) access:このトークンでDartastic Pubに公開する場合はチェックします。チェックしないと読み取り専用のトークンになります。Reference Demoでは、お客様のPubに公開するsymbolizer_demo_flutterとcrash_demo_flutter以外は、それで十分です。
  3. Generateをクリックします。トークンは一度だけ表示されます:
    新しいPubトークン:Token ID、コピーボタン付きのシークレットトークン、dart pub token addコマンド、「Granted scopes: Pub」
    今すぐコピーボタンでトークンをコピーしてください。このダイアログを閉じると、二度と表示できません。Granted scopes: Pubは、このトークンがPub専用であることを示します。テレメトリーの送信や、ほかのサービスの呼び出しには使えません。
  4. コマンドシェルで、トークンをdart pubに渡します:
    shell
    dart pub token add https://pub.dartastic.io
    Enter secret token:と表示されたらトークンを貼り付け、Enterキーを押します。貼り付けても何も表示されませんが、正常です。次のように表示されます:
    terminal
    Enter secret token:
    Requests to "https://pub.dartastic.io" will now be authenticated using the secret token.
  5. Reference Demoのフォルダーで、パッケージを取得します:
    shell
    flutter pub get
    成功すれば、Pubとトークンは正しく機能しています。

dart pubはトークンをそのホスト用に保存し、そのホストにだけ送信します。トークンの一覧表示、置き換え、削除と、パッケージの公開についてはPubで説明しています。

Pubトークンで使えるパッケージ

Pubトークンで使えるのは、その所有者が使えるパッケージだけです。

  • 組織の管理者は組織内のすべてのパッケージを使えるため、そのトークンも同じです。
  • ほかのチームメンバーは、割り当てられたパッケージのトークンしか発行できません。チームメンバーにパッケージを割り当てるのは管理者です。

ロールについてはチームメンバーを招待を、組織のメンバーへのパッケージの割り当てについてはPubを参照してください。

4. アプリからテレメトリーを送れるようにする

TokensでOTLPトークンを発行し、OpenTelemetry標準の形式でシェルにエクスポートします。authorizationは小文字のままにしてください:

shell
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <your OTLP token>"

5. デモを実行

Dockerを起動した状態で、Reference Demoのフォルダーから天気デモを起動し、端末を選びます:

shell
tool/launch.sh weather_flutter

タップして天気を取得します。このタップでトレースが始まり、アプリ、天気API、そのキャッシュ、外部の天気サービスを通ります。

6. Observatoryで確認

タップは数秒でObservatoryに届きます。アプリには、送信した内容へのリンクがあります。リンクをたどってトレースを開くと、すべてのステップと、それぞれにかかった時間がわかります。

次のステップ