Implement RFC #0131 - Build Observability telemetry specification (Platform spec) #421

Copilot · 2025-11-20T18:50:21Z

Adds telemetry specification for the platform to support lifecycle telemetry as described in RFC #0131.

Note: This PR contains only platform specification changes and targets platform/0.16. Buildpack and image extension specification changes will be submitted in a separate PR targeting buildpack/0.13.

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

Telemetry file hierarchy

<layers>
└── tracing
    ├── buildpacks
    │   ├── example-buildpack@1.0.0-detect.jsonl
    │   └── example-buildpack@1.0.0-build.jsonl
    ├── extensions
    │   └── example-extension@1.0.0-generate.jsonl
    └── 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.

Original prompt

This section details on the original issue you should resolve

<issue_title>[RFC #131] - 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 [RFC #0131] - Build Observability Implement Lifecycle Telemetry lifecycle#1429

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

- Added Telemetry section describing lifecycle and buildpack telemetry files - Documented telemetry file locations under /layers/tracing/ - Specified OpenTelemetry File Exporter format in JSONL - Added context propagation via CNB_OTEL_TRACEPARENT environment variable - Documented telemetry file properties and consumption guidelines - Added Platform-Provided Variables section for CNB_OTEL_TRACEPARENT - Updated table of contents with new sections Co-authored-by: jabrown85 <790999+jabrown85@users.noreply.github.com>

- Added CNB_OTEL_TRACEPARENT input to detect and build phases - Added telemetry file outputs to detect and build phases - Documented optional telemetry file paths using OpenTelemetry File Exporter format Co-authored-by: jabrown85 <790999+jabrown85@users.noreply.github.com>

- Documented optional telemetry file output for extensions in detect and generate phases - Extensions can write telemetry to /layers/tracing/extensions/ directory Co-authored-by: jabrown85 <790999+jabrown85@users.noreply.github.com>

jabrown85

This looks pretty good to me

edmorley · 2025-11-20T21:50:36Z

buildpack.md

 | `$CNB_LAYERS_DIR/<layer>/env.launch/<process>/` | Env vars for launch (after `env`, before `exec.d`) for the launched process                                      |
 | `$CNB_LAYERS_DIR/<layer>/env.build/`            | Env vars for subsequent buildpacks (after `env`)                                                                 |
 | `$CNB_LAYERS_DIR/<layer>/*`                     | Other content for launch and/or subsequent buildpacks                                                            |
+| `$CNB_LAYERS_DIR/tracing/buildpacks/<id>@<version>-build.jsonl` | Buildpack telemetry in [OpenTelemetry File Exporter format](https://opentelemetry.io/docs/specs/otel/protocol/file-exporter/) (optional) |


I'm a bit confused by this.

From reading the RFC, I had thought the new tracing/ subdirectory was going at the very root of the layers dir hierarchy (ie /layers/tracing/...), hence the buildpack name and ID being included the the filenames of the .jsonl files.

However, from the line above the one added here there is:

| $CNB_LAYERS_DIR/<layer>/* | Other content for launch and/or subsequent buildpacks

...which would suggest that $CNB_LAYERS_DIR is instead not /layers but /layers/<buildpack_id>, given that buildpack layers gets nested under a new directory for each buildpack? And if that were the case, then the resultant new tracing files location would resolve to /layers/<buildpack_id>/tracing/... which doesn't seem to match the spec?

Or does it just mean there is a typo in the original content of the spec here?

ie Should the existing line above instead say:

| $CNB_LAYERS_DIR/<buildpack_id>/<layer>/* | Other content for launch and/or subsequent buildpacks

If there is an existing typo, then it's unrelated to this PR (but we should fix it at some point), but it would at least explain the difference here. However, if there isn't an existing typo, then I'm wondering if the new addition for this PR is correct?

That's a good spot.

I looked earlier and thought CNB_LAYERS_DIR was the /layers in the context of both platform and buildpack - because it is /layers on the produced image. CNB_LAYERS_DIR=/layers is what is exported on the image and what is used for lifecycle itself during execution.

It makes sense though, looking at buildpack spec, that CNB_LAYERS_DIR is actually /layers/<buildpack-id> in the context of a buildpack execution. lifecycle mutates this in the execution context of each buildpack.

The spec isn't released yet so we have time to adjust this. I don't think buildpacks have access to anything that represents /layers though.

WDYT @hone @edmorley @joshwlewis?

yea, i think these are both true:

We want the tracing dir in /layers/<buildpack-id>

The CNB_LAYERS_DIR is /layers/<buildpack-id>

If those are true, then I think we have it right?

We want the tracing dir in /layers/<buildpack-id>

The RFC says says this isn't the case though?

The structure has generic things at the top (eg lifecycle otel files), and then the buildpack files are named with the ID etc.

ok, i see now. Here's one proposal to resolve this (but I also want to see an alternative from Jesse):

Location

Tracing files will be written to different locations depending on their source.

All lifecycle execution traces SHOULD be written to /layers/tracing/lifecycle/{phase}.jsonl.
Buildpack traces MAY be written to${CNB_LAYERS_DIR}/tracing-{phase}.jsonl.
Extension traces MAY be written to/layers/tracing/extensions/{id}@{version}-{phase}.jsonl.

A completed build with tracing might have a tracing file hierarchy like this:

<layers> ├── tracing ├── extensions │ ├── some-id@some-version-detect.jsonl │ └── some-id@some-version-generate.jsonl └── lifecycle ├── analyze.jsonl ├── build.jsonl ├── detect.jsonl ├── export.jsonl ├── extend.jsonl └── restore.jsonl └── <buildpack-id> ├── tracing-build.jsonl └── tracing-detect.jsonl

The drawback of this proposal is that we are polluting the CNB_LAYERS_DIR with non-layer information.

I think we should go with Jesse's proposal as it seems to be cleaner within lifecycle

WDYT @edmorley @joshwlewis?

@copilot update the spec with the following changes

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/<buildpack>@<version>-<phase>.jsonl path created by the platform. Similar changes to extensions.

How do the spec changes look @edmorley @jkutner ? I introduced the CNB_OTEL_LOG_PATH

jabrown85 · 2025-11-24T16:21:02Z

@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.

- Add CNB_OTEL_LOG_PATH as input to buildpack detect and build phases - Add CNB_OTEL_LOG_PATH as input for image extensions - Replace hardcoded telemetry output paths with CNB_OTEL_LOG_PATH - Document CNB_OTEL_LOG_PATH in platform spec as platform-provided variable - Update telemetry section to describe platform provides path to buildpacks/extensions Co-authored-by: jabrown85 <790999+jabrown85@users.noreply.github.com>

Copilot · 2025-11-24T16:24:53Z

@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 · 2025-11-24T16:28:46Z

@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

- Added "MAY write telemetry data to CNB_OTEL_LOG_PATH" to detect phase - Added "MAY write telemetry data to CNB_OTEL_LOG_PATH" to build phase - Matches the format used in image extension spec Co-authored-by: jabrown85 <790999+jabrown85@users.noreply.github.com>

Copilot · 2025-11-24T16:31:41Z

@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 · 2025-12-19T17:32:50Z

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

jabrown85 · 2025-12-19T18:11:38Z

@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

This PR now only contains platform.md changes and will target platform/0.16. buildpack.md and image_extension.md changes will be moved to a separate PR targeting buildpack/0.13. Co-authored-by: jabrown85 <790999+jabrown85@users.noreply.github.com>

Copilot · 2025-12-19T18:15:08Z

@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.

Initial plan

9a7d334

Copilot AI assigned Copilot and jabrown85 Nov 20, 2025

Copilot started work on behalf of jabrown85 November 20, 2025 18:50 View session

Copilot AI and others added 3 commits November 20, 2025 18:55

Add telemetry output to image extension specification

cf88fca

- Documented optional telemetry file output for extensions in detect and generate phases - Extensions can write telemetry to /layers/tracing/extensions/ directory Co-authored-by: jabrown85 <790999+jabrown85@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Implement lifecycle telemetry for buildpack observability~~ Implement RFC #0131 - Build Observability telemetry specification Nov 20, 2025

Copilot AI requested a review from jabrown85 November 20, 2025 19:02

Copilot finished work on behalf of jabrown85 November 20, 2025 19:02

jabrown85 approved these changes Nov 20, 2025

View reviewed changes

edmorley reviewed Nov 20, 2025

View reviewed changes

Copilot started work on behalf of jabrown85 November 24, 2025 16:18 View session

Copilot AI requested a review from jabrown85 November 24, 2025 16:19

Copilot finished work on behalf of jabrown85 November 24, 2025 16:19

Copilot started work on behalf of jabrown85 November 24, 2025 16:21 View session

Copilot finished work on behalf of jabrown85 November 24, 2025 16:27

Copilot started work on behalf of jabrown85 November 24, 2025 16:29 View session

Copilot finished work on behalf of jabrown85 November 24, 2025 16:33

jkutner approved these changes Nov 24, 2025

View reviewed changes

jabrown85 marked this pull request as ready for review December 1, 2025 20:52

jabrown85 requested a review from a team as a code owner December 1, 2025 20:52

Copilot started work on behalf of jabrown85 December 19, 2025 18:12 View session

Copilot AI changed the title ~~Implement RFC #0131 - Build Observability telemetry specification~~ Implement RFC #0131 - Build Observability telemetry specification (Platform spec) Dec 19, 2025

Copilot finished work on behalf of jabrown85 December 19, 2025 18:18

jabrown85 changed the base branch from main to platform/0.16 December 19, 2025 22:35

jabrown85 approved these changes Dec 20, 2025

View reviewed changes

Implement RFC #0131 - Build Observability telemetry specification (Platform spec) #421

Are you sure you want to change the base?

Implement RFC #0131 - Build Observability telemetry specification (Platform spec) #421

Uh oh!

Conversation

Copilot AI commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

platform.md

Telemetry file hierarchy

Related

Context

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

Uh oh!

jabrown85 left a comment

Choose a reason for hiding this comment

Uh oh!

edmorley Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Location

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jabrown85 commented Nov 24, 2025

Uh oh!

Copilot AI commented Nov 24, 2025

Uh oh!

jabrown85 commented Nov 24, 2025

Uh oh!

Copilot AI commented Nov 24, 2025

Uh oh!

hone commented Dec 19, 2025

Uh oh!

jabrown85 commented Dec 19, 2025

Uh oh!

Copilot AI commented Dec 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Copilot AI commented Nov 20, 2025 •

edited

Loading

edmorley Nov 20, 2025 •

edited

Loading