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

buildpack.md

@@ -191,6 +191,8 @@ Executable: `/bin/detect`, Working Dir: `<app[AR]>`
 | `$CNB_BUILD_PLAN_PATH`   | E          | Absolute path of the build plan                   |
 | `$CNB_BUILDPACK_DIR`     | ER         | Absolute path of the buildpack root directory     |
 | `$CNB_EXEC_ENV`          | AR         | Target execution environment ("production", "test", "development") |
+| `$CNB_OTEL_TRACEPARENT`  | AR         | W3C Trace Context traceparent for trace correlation (optional) |
+| `$CNB_OTEL_LOG_PATH`     | AR         | Path to write telemetry data in [OpenTelemetry File Exporter format](https://opentelemetry.io/docs/specs/otel/protocol/file-exporter/) (optional) |
 | `$CNB_PLATFORM_DIR`      | AR         | Absolute path of the platform directory           |
 | `$CNB_PLATFORM_DIR/env/` | AR         | User-provided environment variables for build     |
 | `$CNB_PLATFORM_DIR/#`    | AR         | Platform-specific extensions                      |
@@ -201,6 +203,7 @@ Executable: `/bin/detect`, Working Dir: `<app[AR]>`
 | Standard output        | Logs (info)                                 |
 | Standard error         | Logs (warnings, errors)                     |
 | `$CNB_BUILD_PLAN_PATH` | Contributions to the the Build Plan (TOML)  |
+| `$CNB_OTEL_LOG_PATH`   | Buildpack telemetry in [OpenTelemetry File Exporter format](https://opentelemetry.io/docs/specs/otel/protocol/file-exporter/) (optional) |
 
 ###  Build
 
@@ -213,6 +216,8 @@ Executable: `/bin/build`, Working Dir: `<app[AI]>`
 | `$CNB_BP_PLAN_PATH`      | ER         | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML) |
 | `$CNB_BUILDPACK_DIR`     | ER         | Absolute path of the buildpack root directory                                 |
 | `$CNB_EXEC_ENV`          | AR         | Target execution environment ("production", "test", "development")            |
+| `$CNB_OTEL_TRACEPARENT`  | AR         | W3C Trace Context traceparent for trace correlation (optional)                |
+| `$CNB_OTEL_LOG_PATH`     | AR         | Path to write telemetry data in [OpenTelemetry File Exporter format](https://opentelemetry.io/docs/specs/otel/protocol/file-exporter/) (optional) |
 | `$CNB_PLATFORM_DIR`      | AR         | Absolute path of the platform directory                                       |
 | `$CNB_PLATFORM_DIR/env/` | AR         | User-provided environment variables for build                                 |
 | `$CNB_PLATFORM_DIR/#`    | AR         | Platform-specific extensions                                                  |
@@ -240,6 +245,7 @@ Executable: `/bin/build`, Working Dir: `<app[AI]>`
 | `$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_OTEL_LOG_PATH`                            | Buildpack telemetry in [OpenTelemetry File Exporter format](https://opentelemetry.io/docs/specs/otel/protocol/file-exporter/) (optional) |
 
 ### Exec.d
 
@@ -402,6 +408,7 @@ The `/bin/detect` executable in each extension or buildpack, when executed:
 - MAY read the app directory.
 - MAY emit error, warning, or debug messages to `stderr`.
 - MAY augment the Build Plan by writing TOML to `<plan>`.
+- MAY write telemetry data to `$CNB_OTEL_LOG_PATH` in [OpenTelemetry File Exporter format](https://opentelemetry.io/docs/specs/otel/protocol/file-exporter/) when provided.
 - MUST set an exit status code as described in the [Buildpack Interface](#buildpack-interface) section.
 
 In order to make contributions to the Build Plan, a `/bin/detect` executable MUST write entries to `<plan>` in two sections: `requires` and `provides`.
@@ -607,6 +614,7 @@ Correspondingly, each `/bin/build` executable:
 - SHOULD write launch SBOM entries to `<layers>/launch.sbom.<ext>` describing any contributions to the application not associated with a layer.
 - SHOULD write build SBOM entries to `<layers>/build.sbom.<ext>` describing any contributions to the build environment not associated with a layer.
 - MAY write values that should persist to subsequent builds in `<layers>/store.toml`.
+- MAY write telemetry data to `$CNB_OTEL_LOG_PATH` in [OpenTelemetry File Exporter format](https://opentelemetry.io/docs/specs/otel/protocol/file-exporter/) when provided.
 - MAY modify or delete any existing `<layers>/<layer>` directories.
 - MAY modify or delete any existing `<layers>/<layer>.toml` files.
 - MAY modify or delete any existing `<layers>/<layer>.sbom.<ext>` files.

image_extension.md

@@ -100,6 +100,7 @@ Correspondingly, each `/bin/generate` executable:
   - `context.run`
   - `context.build`
 - MAY write key-value pairs to `<output>/extend-config.toml` that are provided as build args to build.Dockerfile when extending the build image.
+- MAY write telemetry data to `$CNB_OTEL_LOG_PATH` in [OpenTelemetry File Exporter format](https://opentelemetry.io/docs/specs/otel/protocol/file-exporter/) when provided.
 - MUST NOT write SBOM (Software-Bill-of-Materials) files as described in the [Software-Bill-of-Materials](#software-bill-of-materials) section.
 
 #### Context Folders