> ## 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 统一 SDK 中进行调试跟踪

> 在 PlayFab 统一 SDK 中启用和配置调试跟踪：设置 HCTraceLevel 详细程度、将输出路由到 Visual Studio 或转发到自定义游戏日志。

PlayFab 统一 SDK 提供了一个可扩展的调试跟踪系统，帮助开发者监控内部 API 行为、跟踪错误，并将 PlayFab 日志集成到游戏的日志基础设施中。调试输出还可以在开发期间路由到 Visual Studio 输出窗格。

## 概述

调试跟踪对以下场景很有用：

* 监控 PlayFab SDK 请求和响应
* 诊断 API 调用失败
* 与自定义日志系统集成
* 按环境（开发与生产）调整日志详细程度
* 通过线程 ID 跟踪调试多线程问题

## 启用和配置跟踪

您可以使用以下 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 和其他系统的日志。
* **调试多线程**：使用日志中的线程 ID 来识别并发问题。

## 另请参阅

* [异步操作](/services/playfab/sdks/unified-sdk/async-model)
* [内存管理](/services/playfab/sdks/unified-sdk/memory-management)
* [跟踪与诊断](/services/playfab/sdks/unified-sdk/debug-trace)