> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PlayFab Unified SDK 中的偵錯追蹤

> 在 PlayFab Unified SDK 中啟用和設定偵錯追蹤：設定 HCTraceLevel 詳細程度、將輸出路由至 Visual Studio，或轉送至自訂遊戲記錄。

PlayFab Unified SDK 提供可延伸的偵錯追蹤系統，協助開發人員監視內部 API 行為、追蹤錯誤，並將 PlayFab 記錄整合至遊戲的記錄基礎結構中。在開發期間，偵錯輸出也可以路由至 Visual Studio 的 \[輸出] 窗格。

## 概觀

偵錯追蹤適用於：

* 監視 PlayFab SDK 要求和回應
* 診斷 API 呼叫失敗
* 與自訂記錄系統整合
* 依環境 (開發與生產) 調整記錄詳細程度
* 透過執行緒識別碼追蹤來偵錯多執行緒問題

## 啟用和設定追蹤

您可以使用下列 API 呼叫來啟用追蹤、設定詳細程度，以及設定輸出的傳送位置：

```cpp theme={null}
HCSettingsSetTraceLevel(HCTraceLevel::Verbose);  // Verbose, Error, or Off
HCTraceSetTraceToDebugger(true);                 // Route to Visual Studio Output window
HCTraceSetClientCallback(TraceCallback);         // Custom trace handler
```

## 追蹤層級

| 層級 | 描述 |
| - | - |
| `HCTraceLevel::Off` | 停用所有追蹤 |
| `HCTraceLevel::Error` | 只記錄失敗的 API 呼叫 |
| `HCTraceLevel::Verbose` | 記錄所有要求、回應和中繼資料 |

## 與自訂記錄系統整合

### GameLog 協助程式函式

```cpp theme={null}
#include <iostream>
#include <string>

void GameLog(const std::string& levelStr, const std::string& message)
{
    std::cout << "[" << levelStr << "] " << message << std::endl;
}
```

### 追蹤回呼範例

```cpp theme={null}
#include <sstream>

void CALLBACK TraceCallback(
    const char* areaName,
    HCTraceLevel level,
    uint64_t threadId,
    uint64_t timestamp,
    const char* message)
{
    std::ostringstream oss;

    std::string levelStr;
    switch (level)
    {
        case HCTraceLevel::Error:   levelStr = "Error";   break;
        case HCTraceLevel::Verbose: levelStr = "Verbose"; break;
        default:                    levelStr = "Log";     break;
    }

    oss << "[" << areaName << "] [Thread " << threadId << "] " << message;
    GameLog(levelStr, oss.str());
}
```

### 初始化

```cpp theme={null}
void InitializePlayFabTracing()
{
    HCSettingsSetTraceLevel(HCTraceLevel::Verbose);
    HCTraceSetTraceToDebugger(true);  // Set to false to suppress VS Output pane
    HCTraceSetClientCallback(TraceCallback);
}
```

## 最佳做法

* **開發時使用 Verbose**：啟用完整追蹤以進行偵錯和 QA。
* **生產時使用 Error 或 Off**：降低效能影響和記錄量。
* **集中記錄**：使用統一的 `GameLog` 函式或類似函式，彙總來自 PlayFab 和其他系統的記錄。
* **偵錯多執行緒**：使用記錄中的執行緒識別碼來找出並行問題。

## 另請參閱

* [非同步作業](/zh-TW/services/playfab/sdks/unified-sdk/async-model)
* [記憶體管理](/zh-TW/services/playfab/sdks/unified-sdk/memory-management)
* [追蹤和診斷](/zh-TW/services/playfab/sdks/unified-sdk/debug-trace)


## Related topics

- [PlayFab Unified SDK 中的記憶體管理](/zh-TW/services/playfab/sdks/unified-sdk/memory-management.md)
- [PlayFab Party SDK 中的診斷追蹤/記錄](/zh-TW/services/playfab/multiplayer/networking/party-logging.md)
- [PlayFab Lobby 和 Matchmaking SDK 中的診斷追蹤](/zh-TW/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-matchmaking-logging.md)
- [偵錯追蹤](/zh-TW/services/playfab/sdks/c/tracing.md)
- [Game Saves 快速入門](/zh-TW/services/playfab/player-progression/game-saves/quickstart.md)