# 코드에 프로파일러 마커 추가

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

코드에 [프로파일러 마커](/engine/6000.0/manual/analysis/profiler/adding-information-code/intro.md)를 추가하여 `ProfilerMarker.Begin`, `ProfilerMarker.End` 또는 `ProfilerMarker.Auto`가 생성하는 샘플을 [프로파일러 창](/engine/6000.0/manual/analysis/profiler/window.md)에 있는 [CPU Usage 모듈](/engine/6000.0/manual/analysis/profiler/collect-data/visualizing-data/cpu/introduction.md)의 **Timeline View** 및 **계층 구조 뷰**에서 확인할 수 있습니다.


**Timeline View에 메타데이터가 표시된 프로파일러 샘플.:**
![](/api/media?file=/engine/6000.0/media/images/profiler-marker-metadata-timeline.png)

\*
**계층 구조 뷰에 메타데이터 표시된 프로파일러 샘플.:**
![](/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 패키지는 코어 패키지이므로 패키지 관리자 UI에서 검색할 수 없습니다. 패키지를 설치하려면 다음 중 하나를 수행합니다.

* [패키지 이름으로 추가합니다](/engine/6000.0/manual/packages-list/packages/upm-ui/actions/quick.md)(`com.unity.profiling.core`).
* [이 링크](/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();
    }
}
```

**참고:** 프로파일러 마커의 이름에 `/` 문자를 넣지 마십시오. 프로파일러 창이 CPU Profiler 모듈의 차트 뷰에서 마커를 하이라이트할 수 없게 됩니다.

`End`가 호출되기 전에 `Begin` 및 `End` 호출 사이의 코드가 범위를 벗어나지 않게 하십시오. `End`가 호출되기 전에 코드가 범위를 벗어나면 콘솔에 오류 메시지가 기록됩니다. 모든 반환 이전에 `End`를 호출하지 않도록, `Auto`를 사용해 샘플이 범위를 벗어나면 자동으로 종료되도록 하십시오. 자세한 내용은 이 기술 자료의 [프로파일러 마커 코드 블록 자동으로 닫기](#automatically-close) 섹션을 참조하십시오.

Unity는 프로파일링된 코드 블록의 실행 시간을 프로파일러에 기록하고 보고하며 [CPU Profiler 모듈](/engine/6000.0/manual/analysis/profiler/collect-data/visualizing-data/cpu/introduction.md)에 표시하므로 [세부 프로파일링](/engine/6000.0/manual/analysis/profiler/collect-data/deep-profiling.md)을 사용하지 않아도 됩니다. 해당 정보는 CPU 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`로 표시된 영역 내의 모든 비동기 `await`와 모든 `yield` 호출은 지원되지 않으며 `Auto`를 사용하더라도 콘솔에 오류 메시지가 기록됩니다.

## 샘플에 정수 또는 부동 소수점 파라미터 추가

코드가 장시간 실행되는 특정 조건을 밝히기 위해 코드 샘플에 관련 정보를 추가해야 할 수 있을 것입니다.

예를 들어 시스템이 여러 오브젝트의 시뮬레이션을 수행할 경우 프로파일러 샘플로 오브젝트 수를 전달할 수 있습니다. 프로파일러가 긴 샘플 길이와 함께 비정상적인 숫자를 반환한다면, 시뮬레이션을 위해 다른 스레드를 사용하거나, CPU 작업을 여러 프레임으로 분할(타임슬라이싱)하거나, 애플리케이션 설계를 조정하여 프레임 저하를 방지해야 할 수 있습니다.

`ProfilerMarker`는 최대 3개의 숫자 파라미터([`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))를 지원합니다.

```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)