diff --git a/platform.md b/platform.md index a8365db..33df32c 100644 --- a/platform.md +++ b/platform.md @@ -62,6 +62,11 @@ Examples of a platform might include: - [Run Image Resolution](#run-image-resolution) - [Registry Authentication](#registry-authentication) - [Experimental Features](#experimental-features) + - [Telemetry](#telemetry) + - [Telemetry Files](#telemetry-files) + - [Telemetry File Properties](#telemetry-file-properties) + - [Context Propagation](#context-propagation) + - [Telemetry Consumption](#telemetry-consumption) - [Buildpacks](#buildpacks) - [Buildpacks Directory Layout](#buildpacks-directory-layout) - [Image Extensions](#image-extensions) @@ -74,6 +79,7 @@ Examples of a platform might include: - [POSIX Path Variables](#posix-path-variables) - [User-Provided Variables](#user-provided-variables) - [Operator-Defined Variables](#operator-defined-variables) + - [Platform-Provided Variables](#platform-provided-variables) - [Launch Environment](#launch-environment) - [Caching](#caching) - [Build Reproducibility](#build-reproducibility) @@ -1141,6 +1147,63 @@ When an experimental feature is invoked, the lifecycle: - SHALL fail if `CNB_EXPERIMENTAL_MODE=error` - SHALL continue without warning if `CNB_EXPERIMENTAL_MODE=silent` +### Telemetry + +The lifecycle and buildpacks MAY emit telemetry data during build operations to enable observability of build performance and behavior. + +#### Telemetry Files + +Telemetry data MUST be written using the [OpenTelemetry File Exporter format](https://opentelemetry.io/docs/specs/otel/protocol/file-exporter/) in JSONL format. + +The platform MUST provide `CNB_OTEL_LOG_PATH` to buildpacks and extensions when telemetry collection is desired. The value SHOULD point to a location under `/tracing/buildpacks/` for buildpacks or `/tracing/extensions/` for extensions. + +Lifecycle telemetry files SHOULD be written to the following locations: +- Lifecycle telemetry: `/tracing/lifecycle/.jsonl` + - Where `` is one of: `analyze`, `detect`, `restore`, `extend`, `build`, `export` + +Example telemetry file hierarchy: +``` + +└── 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 +``` + +#### Telemetry File Properties + +Telemetry files: +- MAY be written at any point during the build to ensure telemetry is persisted in case of failures, process terminations, or crashes +- MUST NOT be truncated or deleted during the build to allow telemetry processing by the platform during or after the build +- MUST NOT be included in the exported app image +- MUST be group-readable to allow analysis by the user and/or platform +- SHOULD only be read and written by the component that created them (lifecycle or individual buildpack/extension) + +#### Context Propagation + +The platform MAY set `CNB_OTEL_TRACEPARENT` in the lifecycle execution environment to enable correlation of lifecycle and buildpack traces with platform traces. + +When `CNB_OTEL_TRACEPARENT` is provided: +- The value MUST conform to the [W3C Trace Context specification for traceparent field values](https://www.w3.org/TR/trace-context/#traceparent-header-field-values) +- The lifecycle and buildpacks SHOULD use the provided `trace-id` and `parent-id` when generating traces + +#### Telemetry Consumption + +The platform MAY read telemetry files during or after the build for observability purposes. + +Telemetry files: +- MUST NOT be used as an API, contract, or communication mechanism between buildpacks or between the lifecycle and buildpacks +- MUST NOT contain personally identifiable information (e.g., usernames, email addresses, IP addresses) +- MUST NOT contain business-sensitive information (e.g., passwords, access keys, image names, URLs, source code repository names) + ## Buildpacks ### Buildpacks Directory Layout @@ -1220,6 +1283,17 @@ however the operator-defined value is always applied after the buildpack-provide The platform SHOULD NOT set operator-provided environment variables directly in the lifecycle execution environment. +##### Platform-Provided Variables + +The platform MAY set the following environment variables in the lifecycle execution environment: + +| Env Variable | Description | +|-------------------------|-------------------------------------------------------------------------------------------------------| +| `CNB_OTEL_TRACEPARENT` | W3C Trace Context traceparent value for correlating lifecycle and buildpack traces with platform traces. See [Telemetry](#telemetry). | +| `CNB_OTEL_LOG_PATH` | Path where buildpacks and extensions should write telemetry data. When provided, it SHOULD point to a location under `/tracing/buildpacks/`. See [Telemetry](#telemetry). | + +These variables SHALL be directly inherited by buildpacks without modification. + #### Launch Environment User-provided modifications to the process execution environment SHOULD be set directly in the lifecycle execution environment.