# コードへのプロファイラーマーカーの追加

> Add profiler markers to mark up areas of your code.

コードに [プロファイラーマーカー](/engine/6000.0/manual/analysis/profiler/adding-information-code/intro.md) を追加して、[Profiler ウィンドウ](/engine/6000.0/manual/analysis/profiler/window.md) の [CPU Usage モジュール](/engine/6000.0/manual/analysis/profiler/collect-data/visualizing-data/cpu/introduction.md) の **Timeline ビュー** と **Hierarchy ビュー** に、`ProfilerMarker.Begin`、`ProfilerMarker.End`、または `ProfilerMarker.Auto` が生成するサンプルを表示します。


**Timeline ビューのメタデータを持つプロファイラーサンプル:**
![](/api/media?file=/engine/6000.0/media/images/profiler-marker-metadata-timeline.png)

\*
**Hierarchy ビューのメタデータを持つプロファイラーサンプル:**
![](/api/media?file=/engine/6000.0/media/images/profiler-marker-metadata-hierarchy.png)

## 前提条件

一部の例では [Profiling Core パッケージ](https://docs.unity3d.com/Packages/com.unity.profiling.core@latest) を使用します。これは開始前にインストールする必要があります。Unity Profiling Core パッケージはコアパッケージであるため、Package Manager UI では検出できません。パッケージをインストールするには、以下のいずれかを実行します。

* `com.unity.profiling.core` という [名前を使って追加](/engine/6000.0/manual/packages-list/packages/upm-ui/actions/quick.md) します。
* [このリンクから](/engine/6000.0/manual/com-unity-profiling.md) インストールします。

## コードのマークアップ

[`ProfilerMarker` API](/engine/6000.0/script-reference/unity-profiling/profiler-marker.md) を使用するには、プロファイルするコードを `ProfilerMarker.Begin` 呼び出しと `ProfilerMarker.End` 呼び出しの間に配置します。以下に例を示します。

```lang-csharp
using UnityEngine;
using Unity.Profiling;

public class ProfilerMarkerExample
{
    static readonly ProfilerMarker k_MyCodeMarker = new ProfilerMarker("My Code");

    void Update() {
        k_MyCodeMarker.Begin();
        Debug.Log("This code is being profiled");
        k_MyCodeMarker.End();
    }
}
```

\*\*注：\*\*プロファイラーマーカーの名前に `/` 文字を使用しないでください。Profiler ウィンドウが CPU Profiler モジュールのチャートビューでマーカーを強調表示できなくなります。

`End` が呼び出される前に、`Begin` 呼び出しと `End` 呼び出しの間のコードがスコープ外に出ないようにしてください。`End` が呼び出される前にコードがスコープを出ると、エラーメッセージがコンソールに記録されます。return のたびに `End` を呼び出す必要がないようにするには、`Auto` を使用して、サンプルがスコープから出るときに自動的に終了するようにします。詳細については、このドキュメントの [プロファイラーマーカーのコードブロックの自動終了](#automatically-close) セクションを参照してください。

Unity は、プロファイルされたコードブロックの実行時間を記録してプロファイラーに報告し、[Deep Profiling](/engine/6000.0/manual/analysis/profiler/collect-data/deep-profiling.md) を使用せずに [CPU Profiler モジュール](/engine/6000.0/manual/analysis/profiler/collect-data/visualizing-data/cpu/introduction.md) に表示します。以下のように、CPU Profiler モジュールの **Hierarchy ビュー** に新しいエントリーとして表示されます。


**Profiler ウィンドウのプロファイラーサンプル:**
![](/api/media?file=/engine/6000.0/media/images/profiler-marker-full-sample.png)

### プロファイラーマーカーのコードブロックの自動終了

`ProfilerMarker.Auto` を使用して、コードブロックの終了時に `ProfilerMarker.End` が自動的に呼び出されるようにします。以下の呼び出しは同等です。

```lang-csharp
using Unity.Profiling;

public class MySystemClass
{
    static readonly ProfilerMarker k_UpdatePerfMarker = new ProfilerMarker("MySystem.Update");

    public void Update()
    {
        k_UpdatePerfMarker.Begin();
        // ...
        k_UpdatePerfMarker.End();

        using (k_UpdatePerfMarker.Auto())
        {
            // ...
        }
    }
}
```

`Begin()` 呼び出しと `End()` 呼び出しとは異なり、Unity は開発以外の (リリース) ビルドで `ProfilerMarker.Auto` 呼び出しをコンパイルで除外できません。ただし、代わりに null を返すため、オーバーヘッドは最小限になります。

`ProfilerMarker.Auto` を `using var` とともに使用することもできます。現在のスコープが終了すると、`End` 呼び出しが自動的に発生します。このアプローチでは、コードに `ProfilerMarker` インスタンスを追加するときに変更する必要のあるコードの量が最小限に抑えられます。

```lang-csharp
using Unity.Profiling;

public class MySystemClass
{
    static readonly ProfilerMarker k_UpdatePerfMarker = new ProfilerMarker("MySystem.Update");

    public void Update()
    {
        using var _ = k_UpdatePerfMarker.Auto();
        // ...
    }
}
```

**注：**`ProfilerMarker` でマークアップされたエリア内の async `await` 呼び出しおよび `yield` 呼び出しはサポートされておらず、`Auto` を使用している場合でもコンソールにエラーメッセージが記録されます。

## サンプルへの整数または浮動小数点パラメーターの追加

コードサンプルにコンテキストを追加して、コードが長時間実行される特定の条件を特定する必要がある場合があります。

例えば、システムがオブジェクトのシミュレーションを実行する場合、プロファイラーサンプルでオブジェクトの数を渡すことができます。プロファイラーが長いサンプル継続時間とともに異常な数値を返す場合は、シミュレーションに別のスレッドを使用するか、CPU 処理を複数のフレームに分割するか (タイムスライス)、アプリケーションの設計を調整してフレーム落ちを防ぐ必要がある可能性があります。

`ProfilerMarker` は、[`ProfilerMarker<TP1>`](https://docs.unity3d.com/Packages/com.unity.profiling.core@1.0/api/Unity.Profiling.ProfilerMarker-1.html)、[`ProfilerMarker<TP1, TP2>`](https://docs.unity3d.com/Packages/com.unity.profiling.core@1.0/api/Unity.Profiling.ProfilerMarker-2.html)、[`ProfilerMarker<TP1, TP2, TP3>`](https://docs.unity3d.com/Packages/com.unity.profiling.core@1.0/api/Unity.Profiling.ProfilerMarker-3.html) の 3 つの数値パラメーターまでサポートします。

```lang-csharp
using Unity.Profiling;

public class MySystemClass
{
  static readonly ProfilerMarker<int> k_PreparePerfMarker = new ProfilerMarker<int>("MySystem.Prepare", "Objects Count");
  static readonly ProfilerMarker<float> k_SimulatePerfMarker = new ProfilerMarker<float>(ProfilerCategory.Scripts, "MySystem.Simulate", "Objects Density");

  public void Update(int objectsCount)
  {
    k_PreparePerfMarker.Begin(objectsCount);
    // ...
    k_PreparePerfMarker.End();

    using (k_SimulatePerfMarker.Auto(objectsCount * 1.0f))
    {
      // ...
    }
  }
}
```

## サンプルへの文字列パラメーターの追加

`ProfilerMarker` API では、プロファイラーマーカーに文字列パラメーターを追加できます。文字列パラメーターは、アプリケーションがレベルまたはデータのファイルをロードするときにレベルまたはファイルの名前を表示したい場合に便利です。[`ProfilerMarkerExtension`](https://docs.unity3d.com/Packages/com.unity.profiling.core@1.0/api/Unity.Profiling.ProfilerMarkerExtension.html) メソッドを使用して、プロファイラーサンプルとともに文字列パラメーターを渡します。

```lang-csharp
using Unity.Profiling;

public class MySystemClass
{
  static readonly ProfilerMarker k_PreparePerfMarker = new ProfilerMarker("MySystem.Prepare");

  public void Prepare(string path)
  {
    k_PreparePerfMarker.Begin(path);
    // ...
    k_PreparePerfMarker.End();
  }
}
```

## 追加リソース

* [コードへのプロファイリング情報の追加の概要](/engine/6000.0/manual/analysis/profiler/adding-information-code/intro.md)
* [コードへのプロファイラーカウンターの追加](/engine/6000.0/manual/analysis/profiler/adding-information-code/add-counters-code.md)
* [CPU Usage Profiler モジュールの概要](/engine/6000.0/manual/analysis/profiler/collect-data/visualizing-data/cpu/introduction.md)
* [`ProfilerMarker` API](/engine/6000.0/script-reference/unity-profiling/profiler-marker.md)
* [Profiling Core パッケージ](https://docs.unity3d.com/Packages/com.unity.profiling.core@latest)