diff --git a/text/0000-build-observability.md b/text/0000-build-observability.md index c385e9589..17b1f945b 100644 --- a/text/0000-build-observability.md +++ b/text/0000-build-observability.md @@ -66,9 +66,9 @@ Format](https://opentelemetry.io/docs/specs/otel/protocol/file-exporter/). In this solution, each lifecycle phase would write a `.jsonl` file with tracing data for that phase. For example, `lifecycle detector --telemetry` -would write to `/layers/lifecycle-detect.jsonl`. Additionally each +would write to `/layers/tracing/lifecycle/detect.jsonl`. Additionally each buildpack may also write tracing data to it's own `.jsonl` files (at -`/layers/#{buildpack-id}@#{buildpack-version}.jsonl`). +`/layers/tracing/buildpacks/#{id}@#{version}-#{phase}.jsonl`). These `.jsonl` files may be read by platform operators for consumption, transformation, enrichment, and/or export to an OpenTelemetry backend. Given @@ -93,7 +93,7 @@ inherit `trace-id` and `parent-id` from platform systems. If `lifecycle` is provided the telemetry opt-in flag (such as `--telemetry`), `lifecycle` phases (such as `detect`, `build`, `export`) may emit an OpenTelemetry File Export with tracing data to a known location, such as -`/layers/lifecycle-detect.jsonl` with contents like this: +`/layers/tracing/lifecycle/detect.jsonl` with contents like this: ```json { @@ -148,8 +148,8 @@ OpenTelemetry File Export with tracing data to a known location, such as ### Buildpack telemetry files -During a buildpack's `detect` or `build` execution, a buildpack may emit -an OpenTelemetry File Export with tracing data to `/layers/#{buildpack-id}@#{buildpack-version}.jsonl` +During a buildpack's `detect` and/or `build` execution, a buildpack may emit +an OpenTelemetry File Export with tracing data to `/layers/tracing/buildpacks/#{id}@#{version}-#{phase}.jsonl` with contents like this: ```json @@ -202,6 +202,36 @@ with contents like this: } ``` +### Location + +All tracing files should be written to `/layers/tracing/`. Lifecycle execution +traces should be written to `/layers/tracing/lifecycle/{phase}.jsonl`. +Buildpack traces may be written to +`/layers/tracing/buildpacks/{id}@{version}-{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: + +``` + +└── tracing + ├── buildpacks + │ ├── other-id@other-version-detect.jsonl + │ ├── some-id@some-version-build.jsonl + │ └── some-id@some-version-detect.jsonl + ├── 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 +``` + ### Lifetime Telemetry files may be written at any point during the build, so that they