この仕様は、クライアントの JavaScript 実行時間を測定するためのサンプリングプロファイラーを Web アプリケーションが制御できるようにする API を説明します。

定義

サンプルとは、特定の時点における実行の 瞬間的な状態を表す記述子です。各サンプルは スタックに関連付けられます。

スタックとは、最も外側のフレームから最も内側のフレームまで 順番に並べなければならないフレームのリストです。

フレームとは、現在の実行状態に関する情報を含む スタックのコンテキスト内の要素です。

プロファイリングセッション

プロファイリングセッションとは、サンプルを生成する抽象的な生成元です。各セッションは次のものを持ちます。

1. 状態。{started, paused, stopped} のいずれかです。
2. サンプル間隔。セッションがサンプルを取得する周期として定義されます。

   UA はこの頻度でサンプルを取得することを要求されません。ただし、より高品質な トレースを生成するため、この頻度でサンプルを取得するようサンプリングを優先することが 推奨されます。

3. プロファイリング対象のエージェント。
4. プロファイリング対象のレルム。
5. サンプルのタイムスタンプを相対的に測定する基準となる時刻起点。
6. サンプルバッファサイズ上限。
7. 取得したサンプルを格納するProfilerTrace。

同じページ上で複数のプロファイリングセッションをサポートすべきです。

処理モデル

プロファイリングセッションを指定してサンプルを取得するには、次の手順を実行します。

1. ProfilerTrace.samples の長さが、プロファイリングセッションに関連付けられた サンプルバッファサイズ上限以上である場合、関連付けられたProfilerに samplebufferfull 型の新しいイベントを発火し、状態を stopped に移行して、 return します。
2. sample を新しいProfilerSampleとします。
3. sample のProfilerSample.timestampプロパティを、 プロファイリングセッションの時刻起点を基準とする現在の高解像度時刻に設定します。
4. stack を、プロファイリングセッションのエージェントに関連付けられた 実行コンテキストスタックとします。
5. sample のProfilerSample.stackIdプロパティを、 stack に対するスタック ID を取得するアルゴリズムの結果に設定します。
6. sample を、セッションのProfilerTraceに関連付けられた ProfilerTrace.samplesに追加します。

stack に束縛された実行コンテキストスタックを指定して スタック ID を取得するには、次の手順を実行します。

1. stack が空の場合、undefined を返します。
2. head を stack の先頭要素とし、tail を stack からその先頭要素を削除した残りとします。
3. parentId を、tail に対してスタック ID を取得するを再帰的に呼び出した結果とします。
4. frameId を、head に対してフレーム ID を取得するを呼び出した結果とします。
5. frameId が undefined の場合、parentId を返します。
6. profilerStack を、ProfilerStack.frameId が frameId と等しく、ProfilerStack.parentId が parentId と等しい 新しいProfilerStackとします。
7. profilerStack およびProfilerTrace.stacksに対して 要素 ID を取得するを実行した結果を返します。

context に束縛された実行 コンテキストを指定してフレーム ID を取得するには、次の手順を実行します。

1. context に関連付けられた [= realm =] が、プロファイリングセッションに関連付けられた レルムと一致しない場合、undefined を返します。
2. instance を、context に関連付けられた 関数インスタンスと等しいものとします。
3. scriptOrModule を、context に関連付けられた ScriptOrModule と等しいものとします。
4. |attributedScriptOrModule : ScriptOrModule| を、次のアルゴリズムを実行した結果と等しいものとします。
   1. |scriptOrModule| が null でない場合、|scriptOrModule| を返します。
   2. |instance| が組み込み関数オブジェクトである場合、|instance| を呼び出した関数を含む ScriptOrModule を返します。

      上記のロジックの目的は、アクセス不能なスクリプトによって呼び出された組み込み関数が トレースに公開されないようにすることです。そのため、帰属先としてそれらを呼び出した ScriptOrModule を使用します。

      「|instance| を呼び出した関数を含む ScriptOrModule」は、 より厳密に定義すべきです。これを提供するため、ScriptOrModule を定義する スタック上の最上位の実行コンテキストを利用できますが、これは理想的ではありません。 理論上、組み込み関数が実行コンテキストスタックにキューされる別の仕組みが存在する可能性があり、 その場合、帰属は無効になります。

   3. それ以外の場合、null を返します。
5. |attributedScriptOrModule| が null の場合、undefined を返します。
6. |attributedScript : Script| を、 |attributedScriptOrModule|.[[\HostDefined]] から取得した [= script =] とします。
7. |attributedScript| が [= classic script =] であり、その ミュートエラー真偽値が true と等しい場合、 undefined を返します。

   この検査により、CORS クロスオリジンレスポンスで提供されたクロスオリジンスクリプトの スタックフレームが含まれないようにします。この用途をより適切に反映するよう、 ミュートエラーの名称変更を検討してもよいでしょう。

8. frame を新しいProfilerFrameとします。
9. frame のProfilerFrame.nameを、|instance| に関連付けられた 関数インスタンス名に設定します。
10. |scriptOrModule| が null でない場合:
    1. script を、 scriptOrModule.[[\HostDefined]] から取得した スクリプトとします。
    2. resourceString を、script の ベース URLと等しいものとします。
    3. ProfilerFrame.resourceIdを、resourceString および ProfilerTrace.resourcesに対して要素 ID を取得するを実行した結果に設定します。
    4. frame のProfilerFrame.lineを、 |script| 内で instance が定義されている行の 1 を起点とするインデックスに設定します。
    5. frame のProfilerFrame.columnを、 |script| 内で instance が定義されている列の 1 を起点とするインデックスに設定します。
11. frame およびProfilerTrace.framesに対して 要素 ID を取得するを実行した結果を返します。

list 内の item に対して要素 ID を取得するには、次の手順を実行します。

1. list 内に item と成分ごとに等しい要素が存在する場合、そのインデックスを返します。
2. それ以外の場合、item を list の末尾に追加し、そのインデックスを返します。

Profiler インターフェイス

      [Exposed=(Window, Worker)]
      interface Profiler : EventTarget {
        readonly attribute DOMHighResTimeStamp sampleInterval;
        readonly attribute boolean stopped;

        constructor(ProfilerInitOptions options);
        Promise<ProfilerTrace> stop();
      };
      

各Profilerは、正確に一つのプロファイリングセッションに関連付けられなければなりません。

sampleInterval 属性は、関連付けられたプロファイリングセッションの サンプル間隔を、DOMHighResTimeStampとして表した値を反映しなければなりません。

stopped 属性は、プロファイリングセッションの状態が stopped である場合に限り、かつその場合に限って true でなければなりません。

ProfilerTrace 辞書

      typedef DOMString ProfilerResource;

      dictionary ProfilerTrace {
        required sequence<ProfilerResource> resources;
        required sequence<ProfilerFrame> frames;
        required sequence<ProfilerStack> stacks;
        required sequence<ProfilerSample> samples;
      };
      

resources 属性は、サンプルを取得するアルゴリズムによって設定された ProfilerResource リストを返さなければなりません。

frames 属性は、サンプルを取得するアルゴリズムによって設定された ProfilerFrame リストを返さなければなりません。

stacks 属性は、サンプルを取得するアルゴリズムによって設定された ProfilerStack リストを返さなければなりません。

samples 属性は、サンプルを取得するアルゴリズムによって設定された ProfilerSample リストを返さなければなりません。

この表現は、V8 トレース イベント形式 およびGecko プロファイル形式から着想を得ており、 容易かつ効率的にシリアル化できるよう設計されています。

        dictionary ProfilerSample {
          required DOMHighResTimeStamp timestamp;
          unsigned long long stackId;
        };
        

        dictionary ProfilerStack {
          unsigned long long parentId;
          required unsigned long long frameId;
        };
        

        dictionary ProfilerFrame {
          required DOMString name;
          unsigned long long resourceId;
          unsigned long long line;
          unsigned long long column;
        };
        

ProfilerInitOptions 辞書

      dictionary ProfilerInitOptions {
        required DOMHighResTimeStamp sampleInterval;
        required unsigned long maxBufferSize;
      };
      

ProfilerInitOptions は、次のフィールドをサポートしなければなりません。

• sampleInterval は、アプリケーションが希望するサンプル間隔です。この値は 0 以上でなければなりません。
• maxBufferSize は、サンプル数で表した希望するサンプルバッファサイズ上限です。

文書ポリシー

この仕様は、プロファイリング機能および初期化動作を制御するため、 文書 ポリシーに構成 ポイントを定義します。

自動化

ユーザーエージェントの自動化およびアプリケーションテストのために、この文書は次の [[WebDriver]] 拡張コマンドを定義します。