Platform Tracing — Configure
Generate EventSettings metadata to enable or disable the Platform Tracing toggle, which controls whether TraceSpanEvent is published at a sample rate. This modifies a single field (enablePlatformTracing) within the existing EventSettings metadata type.
Scope
- In scope: Generating
Event.settings-meta.xmlwith theenablePlatformTracingfield to enable or disable TraceSpanEvent publishing. - Out of scope: Agentforce agent tracing to Data Cloud (use
platform-tracing-agentforce-configure). Other EventSettings fields (enableDeleteMonitoringData,enableLoginForensics, etc.) owned by other teams. Event Log Files. Change Data Capture.
Prerequisites
Before generating, inform the user of these requirements:
PlatformTracingorg permission must be active — this permission gates the feature. It is provisioned (not settable via metadata). Without it, the setting deploys but TraceSpanEvent is not published.- API version 68.0+ —
enablePlatformTracingon EventSettings was introduced in Spring '25. Orgs or tooling on older API versions will not recognize the field. Updatesfdx-project.jsonsourceApiVersionto68.0or higher if on an older tooling version.
If the user reports the setting isn't working after deploy, the most likely cause is a missing prerequisite above.
Clarifying Questions
Before generating, confirm with the user if not already clear:
- Enable or disable? (Which state do you want for Platform Tracing / TraceSpanEvent?)
No other clarification needed — this controls a single boolean field.
Required Inputs
Gather or infer before proceeding:
- Desired state:
true(enable) orfalse(disable)
Defaults unless specified:
- If user says "enable" or "turn on": set to
true - If user says "disable" or "turn off": set to
false
If the user provides a clear request, generate immediately without unnecessary back-and-forth.
Workflow
-
Warn about prerequisites — inform the user that this feature requires the
PlatformTracingorg permission and API version 68.0+. -
Read the template — load
assets/EventSettings-template.xml. -
Generate the settings file — replace
{ENABLED}withtrueorfalsebased on the user's desired state. -
Place the file — output to
settings/Event.settings-meta.xmlin the project's source directory.
Rules / Constraints
Gotchas
Output Expectations
Deliverables:
settings/Event.settings-meta.xml
Before delivering, verify:
- XML namespace is exactly
http://soap.sforce.com/2006/04/metadata - File is named
Event.settings-meta.xml - Only
enablePlatformTracingis present (no other EventSettings fields) - Project
sourceApiVersioninsfdx-project.jsonis68.0or higher
