platform-tracing-configure

Platform Tracing — 配置

生成 EventSettings 元数据，以启用或禁用 Platform Tracing 开关。该开关用于控制是否按采样率发布 TraceSpanEvent。此操作仅修改现有 EventSettings 元数据类型中的单个字段（enablePlatformTracing）。

范围

• 范围内：生成包含 enablePlatformTracing 字段的 Event.settings-meta.xml，以启用或禁用 TraceSpanEvent 发布。
• 范围外：将 Agentforce Agent 跟踪发送到 Data Cloud（请使用 platform-tracing-agentforce-configure）。其他团队负责的 EventSettings 字段（enableDeleteMonitoringData、enableLoginForensics 等）。Event Log Files。Change Data Capture。

---

前提条件

生成之前，请告知用户以下要求：

1. PlatformTracing 组织权限必须处于激活状态 — 此权限用于控制该功能。该权限由系统配置（不能通过元数据设置）。如果没有此权限，设置仍会部署，但不会发布 TraceSpanEvent。
2. API 版本 68.0+ — EventSettings 中的 enablePlatformTracing 是在 Spring '25 中引入的。使用较旧 API 版本的组织或工具将无法识别该字段。如果使用较旧版本的工具，请将 sfdx-project.json 中的 sourceApiVersion 更新为 68.0 或更高版本。

如果用户反馈部署后设置不起作用，最可能的原因是缺少上述前提条件。

---

澄清问题

生成之前，如果尚不明确，请向用户确认：

• 启用还是禁用？（你希望 Platform Tracing / TraceSpanEvent 处于哪种状态？）

无需其他澄清 — 此操作仅控制一个布尔字段。

---

必需输入

继续之前，请收集或推断以下信息：

• 期望状态：true（启用）或 false（禁用）

未指定时的默认值：

• 如果用户说“启用”或“打开”：设为 true
• 如果用户说“禁用”或“关闭”：设为 false

如果用户提出了明确的请求，请立即生成，避免不必要的来回沟通。

---

工作流

1. 提醒前提条件 — 告知用户，此功能需要 PlatformTracing 组织权限和 API 版本 68.0+。

2. 读取模板 — 加载 assets/EventSettings-template.xml。

3. 生成设置文件 — 根据用户期望的状态，将 {ENABLED} 替换为 true 或 false。

4. 放置文件 — 将文件输出到项目源目录中的 settings/Event.settings-meta.xml。

---

规则 / 约束

约束	原因
生成的元数据中只能包含 enablePlatformTracing	EventSettings 中的其他字段由其他团队负责。包含这些字段可能会在部署时覆盖无关设置。
XML 命名空间必须为 http://soap.sforce.com/2006/04/metadata	使用其他命名空间会导致部署失败。
文件必须命名为 Event.settings-meta.xml	SFDX 源格式约定 — EventSettings 的类型名称前缀为 Event。
需要 PlatformTracing 组织权限	没有此权限时，设置仍会部署，但不会影响 TraceSpanEvent 的发布。
需要 API v68.0+	较旧的组织或工具会拒绝该字段。

---

注意事项

问题	解决方法
部署成功，但未发布 TraceSpanEvent	组织缺少 PlatformTracing 权限。该权限由系统配置，不能通过元数据设置。
组织或工具无法识别 enablePlatformTracing 字段	工具使用的 API 版本低于 68.0。请将 sfdx-project.json 中的 sourceApiVersion 更新为 68.0 或更高版本。
用户将此功能与 Agentforce 跟踪混淆	请说明：此功能会为平台操作发布 TraceSpanEvent。要将 Agentforce Agent span 发送到 Data Cloud，请使用 platform-tracing-agentforce-configure 技能。
用户想配置所有 Event Monitoring 设置	此功能仅涵盖 enablePlatformTracing。EventSettings 中的其他字段由其他团队负责，不由此技能管理。

---

输出要求

交付内容：

• settings/Event.settings-meta.xml

交付前，请验证：

• XML 命名空间必须为 http://soap.sforce.com/2006/04/metadata
• 文件名为 Event.settings-meta.xml
• 仅包含 enablePlatformTracing（不包含其他 EventSettings 字段）
• sfdx-project.json 中的项目 sourceApiVersion 为 68.0 或更高

---

跨技能集成

需求	委派给
启用 Agentforce Agent 对 Data Cloud 的跟踪	platform-tracing-agentforce-configure 技能
设置 Change Data Capture	integration-eventing-cdc-configure 技能
配置 ManagedEventSubscription	integration-eventing-subscription-configure 技能

---

参考文件索引

文件	阅读时机
assets/EventSettings-template.xml	步骤 2 — 用于生成设置文件的模板