Implement RFC #0131 - Build Observability telemetry specification

[Copilot]

Adds telemetry specification for lifecycle, buildpacks, and image extensions to emit OpenTelemetry traces during build operations as described in RFC #0131.

Changes

platform.md

• New Telemetry section - Specifies /layers/tracing/ directory structure for lifecycle, buildpack, and extension telemetry files using OpenTelemetry File Exporter format (JSONL)
• Context propagation - Documents CNB_OTEL_TRACEPARENT environment variable for W3C Trace Context correlation
• Telemetry path provision - Documents CNB_OTEL_LOG_PATH environment variable that platform provides to buildpacks and extensions, pointing to <layers>/tracing/buildpacks/ or <layers>/tracing/extensions/
• Privacy requirements - Telemetry must not contain PII or business-sensitive data (passwords, keys, image names, repository URLs)
• File properties - Telemetry files are group-readable, append-only during build, excluded from app image

buildpack.md

• Added CNB_OTEL_TRACEPARENT input to detect and build phases for trace correlation
• Added CNB_OTEL_LOG_PATH input to detect and build phases - platform-provided path where buildpacks write telemetry
• Added optional telemetry output to CNB_OTEL_LOG_PATH when provided
• Added MAY clauses to detect and build phase process descriptions allowing buildpacks to write telemetry data to CNB_OTEL_LOG_PATH

image_extension.md

• Added optional telemetry output capability to write to CNB_OTEL_LOG_PATH when provided

Telemetry file hierarchy

<layers>
└── tracing
    ├── buildpacks
    │   ├── [email protected]
    │   └── [email protected]
    ├── extensions
    │   └── [email protected]
    └── lifecycle
        ├── analyze.jsonl
        ├── detect.jsonl
        ├── restore.jsonl
        ├── build.jsonl
        └── export.jsonl

All telemetry emission is optional. Platform controls telemetry collection by providing CNB_OTEL_LOG_PATH to buildpacks and extensions. Platform reads files during or after build for observability purposes.

• Fixes buildpacks/lifecycle#1429

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[RFC #0131] - Build Observability Implement Lifecycle Telemetry</issue_title> <issue_description>### Summary / Proposal

As described in RFC buildpacks/lifecycle#131, lifecycle should emit buildpack telemetry as described here.

---

Related

RFC 0131 - Build Observability:

• Discussion Pull Request
• Text
• Tracking Issue

---

Context

</issue_description>

<agent_instructions>Create a PR that modifies the platform spec to describe changes required to implement the linked RFC on builds observability.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@natalieparellano @joshwlewis what is the status here?

• Fixes buildpacks/lifecycle#1429

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[jabrown85]

@copilot In the buildpack spec, CNB_OTEL_LOG_PATH is passed to buildpacks in each phase for them to write to when present. Buildpacks will no longer use CNB_LAYERS_DIR to build their own path to write jsonl The extension spec will also change to allow them to write to CNB_OTEL_LOG_PATH and not rely on a static path in the spec. In the platform spec, CNB_OTEL_LOG_PATH should be passed to buildpacks and point to a $CNB_LAYERS_DIR/tracing/buildpacks/@-.jsonl path created by the platform. Similar changes to extensions.

[Copilot]

@copilot In the buildpack spec, CNB_OTEL_LOG_PATH is passed to buildpacks in each phase for them to write to when present. Buildpacks will no longer use CNB_LAYERS_DIR to build their own path to write...

Updated in commit a75f3f3.

Changes made:

• Added CNB_OTEL_LOG_PATH as input to buildpack detect and build phases
• Added CNB_OTEL_LOG_PATH for image extensions
• Removed hardcoded telemetry paths from outputs
• Documented CNB_OTEL_LOG_PATH in platform spec pointing to <layers>/tracing/buildpacks/

[jabrown85]

@copilot The buildpack spec needs a similar "MAY write telemetry data to $CNB_OTEL_LOG_PATH in OpenTelemetry File Exporter format when provided." in all the phases

[Copilot]

@copilot The buildpack spec needs a similar "MAY write telemetry data to $CNB_OTEL_LOG_PATH in OpenTelemetry File Exporter format ...

Added in commit 5ac3690.

Changes made:

• Added "MAY write telemetry data to $CNB_OTEL_LOG_PATH in OpenTelemetry File Exporter format when provided" to detect phase (line 413)
• Added "MAY write telemetry data to $CNB_OTEL_LOG_PATH in OpenTelemetry File Exporter format when provided" to build phase (line 619)

[hone]

@jabrown85 can we split this for buildpack + platform so we can merge this into the correct branches?

[jabrown85]

@copilot split this PR into 2 distinct PRs. This PR will contain platform.md and update the target the PR to platform/0.16.

buildpack.md and image_extension.md should move to a new PR targeting buildpack/0.13

[Copilot]

@copilot split this PR into 2 distinct PRs. This PR will contain platform.md and update the target the PR to platform/0.16.

buildpack.md and image_extension.md should move to a new PR targe...

Split completed in commit 17e6edc.

This PR now contains only platform.md changes and is ready to target platform/0.16.

For the buildpack changes, a new PR will need to be created with the following changes targeting buildpack/0.13:

• buildpack.md: Add CNB_OTEL_TRACEPARENT and CNB_OTEL_LOG_PATH inputs to detect and build phases, add telemetry output entries, and add MAY clauses for writing telemetry
• image_extension.md: Add MAY clause for writing telemetry to CNB_OTEL_LOG_PATH

The reverted commits that contain these buildpack changes are: 7dfb4c8, cf88fca, a75f3f3 (partial), and 5ac3690.