buildkite-test_collector 2.14.0 → 2.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10535c306b5b29856f36335ba71e8f703b994605136545e9b1e3ed206ca4fe9d
-  data.tar.gz: 3c8115481fb1cfd98a7cee11e7f05347cc3398bcc81f2f7494044a48cb811d27
+  metadata.gz: de04f3cd718a70ec62965dd2e491c5eca981e9781118b3ab7c6a7c05e6ad7655
+  data.tar.gz: c4a0fdbf14634c404ff6ade3db7d639b3f22fa4c5c6e21ba083ef92313ca6743
 SHA512:
-  metadata.gz: d4188a10501a2bb5b32bde498ed360ac8bbbb733e199899c7bb51c40411f6c3ab96b6f3bef90fb79e4901168fad21f88f7e911765988df63ae47d03a120dbaef
-  data.tar.gz: 7903643c37b1b65b9f0a38612253d6c8da084b56cab623f2e3782deacdb0ba3d631b6d17e2e40c796542226b9b00b996606ef38bd67181df6bdc9f99c7594d38
+  metadata.gz: 8682918b8784f2544a3da68e0a6dfd00ce8b2ab8decd9eb24bb0d458381c402697f3d20799bff9d38bd9ebec4a4f48e5ffe5b89d80ce88c89ffc7f54130e573a
+  data.tar.gz: 2c1316f5b43bc3ea14df5aeae2e48496755edfe1892594403df6af499efe5b2aecbef4b1c3f8c5289100b4cacaeffc63da917109611cc5b84d0122a39eb8052c

data/.buildkite/pipeline.release.yml

@@ -1,12 +1,48 @@
+# Monorepo release pipeline for test-collector-ruby, uploaded by the
+# release dispatcher (.buildkite/pipeline.release.yml) running on the
+# separate bktest-release Buildkite pipeline — never by CI: as a rehearsal
+# when this project changes (no tag), and for real on a
+# test-collector-ruby/vX.Y.Z tag. Injected by `ctg gather` from the ctg
+# repo's overlay/ directory during the dry-run era; post-cutover this file
+# is maintained here, in the monorepo. It replaces the source repo's
+# .buildkite/pipeline.release.yml, which assumed the repo root was the
+# project root.
+#
+# Safety model (see docs/publishing.md in the ctg repo):
+#   - The build step is side-effect-free: it builds the gem, checks
+#     tag/version consistency, and queries RubyGems read-only. It runs on
+#     every rehearsal, so rehearsals exercise the release code. It never sees
+#     RELEASE_EXECUTE (deliberately not propagated into its container).
+#   - The publish steps mint a push token via the rubygems.org OIDC API key
+#     role, whose access policy trusts this pipeline (see the credential
+#     cut-over section of ctg docs/publishing.md).
+#   - The publish steps exist only on an exact test-collector-ruby/vX.Y.Z
+#     tag AND RELEASE_EXECUTE=true set on the build, behind a block step;
+#     the release script independently re-checks both before `gem push`.
+
 agents:
   queue: hosted
 
 steps:
-  - block: "OK to release?"
+  - label: ":rubygems: test-collector-ruby: build + rehearse release"
+    key: ruby-build
+    command: test-collector-ruby/.buildkite/steps/release
+    plugins:
+      - docker#v5.12.0:
+          image: "ruby:3.4"
+          environment:
+            - BUILDKITE_TAG
 
-  - command: ".buildkite/steps/release-gem"
-    label: ":rubygems:"
-    if: build.tag != null
+  - block: ":rocket: Publish test-collector-ruby to RubyGems?"
+    key: ruby-confirm
+    if: build.tag =~ /^test-collector-ruby\/v[0-9]+\.[0-9]+\.[0-9]+$/ && build.env("RELEASE_EXECUTE") == "true"
+
+  - label: ":rubygems: test-collector-ruby: publish to RubyGems"
+    if: build.tag =~ /^test-collector-ruby\/v[0-9]+\.[0-9]+\.[0-9]+$/ && build.env("RELEASE_EXECUTE") == "true"
+    depends_on:
+      - ruby-build
+      - ruby-confirm
+    command: test-collector-ruby/.buildkite/steps/release
     plugins:
       - rubygems-oidc#v0.2.0:
           role: "rg_oidc_akr_fy1x4px4yjwd1rdhkkda"
@@ -15,4 +51,4 @@ steps:
           environment:
             - GEM_HOST_API_KEY
             - BUILDKITE_TAG
-
+            - RELEASE_EXECUTE

data/.buildkite/pipeline.yml

@@ -0,0 +1,30 @@
+# Monorepo pipeline for test-collector-ruby, uploaded by the top-level
+# dispatcher when this project changes. Injected by `ctg gather` from the
+# ctg repo's overlay/ directory during the dry-run era; post-cutover this
+# file is maintained here, in the monorepo.
+#
+# Dry-run-safe: pure test steps only, derived from the source repo's
+# buildkite.yaml with credentialed plugins (OIDC role assumption, ECR)
+# removed, Docker Hub images, and a trimmed matrix.
+#
+# Jobs check out the monorepo root, so commands cd into this project.
+
+agents:
+  queue: hosted
+
+steps:
+  - group: ":ruby: test-collector-ruby"
+    steps:
+      - label: ":rspec: Ruby {{matrix}}"
+        command:
+          - "cd test-collector-ruby"
+          - "gem install bundler:2.3.25"
+          - "bundle"
+          - "bundle exec rake"
+          - "bundle exec cucumber"
+        plugins:
+          - docker#v3.7.0:
+              image: "ruby:{{matrix}}"
+        matrix:
+          - "latest"
+          - "3.3"

data/.buildkite/steps/release

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Monorepo release script for test-collector-ruby: build the gem, check
+# tag/version consistency and RubyGems state, then publish — but the publish
+# side effect only happens when RELEASE_EXECUTE=true (set explicitly on the
+# release build; see pipeline.release.yml). Everything before the push runs
+# in rehearsals too, so dry-runs exercise this code.
+#
+# Injected by `ctg gather` from the ctg repo's overlay/ directory during the
+# dry-run era; post-cutover this file is maintained here, in the monorepo.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/../.." # this project's root, wherever the checkout cwd is
+
+PROJECT="test-collector-ruby"
+GEM_NAME="buildkite-test_collector"
+TAG_PATTERN="^${PROJECT}/v([0-9]+\.[0-9]+\.[0-9]+)$"
+
+echo "--- Determining version"
+if [ -n "${BUILDKITE_TAG:-}" ]; then
+  if [[ ! "${BUILDKITE_TAG}" =~ ${TAG_PATTERN} ]]; then
+    echo "BUILDKITE_TAG '${BUILDKITE_TAG}' does not match ${PROJECT}/vX.Y.Z; refusing" >&2
+    exit 1
+  fi
+  VERSION="${BASH_REMATCH[1]}"
+  echo "version ${VERSION} (from tag ${BUILDKITE_TAG})"
+else
+  VERSION="$(ruby -Ilib -rbuildkite/test_collector/version -e 'puts Buildkite::TestCollector::VERSION')"
+  echo "version ${VERSION} (from lib/buildkite/test_collector/version.rb; no tag)"
+fi
+
+GEM_FILENAME="${GEM_NAME}-${VERSION}.gem"
+
+echo "--- Building gem"
+gem build "${GEM_NAME}.gemspec"
+if [ ! -f "${GEM_FILENAME}" ]; then
+  echo "ERROR: expected ${GEM_FILENAME}; does the gemspec/version.rb say ${VERSION}?" >&2
+  echo "gem files found:" >&2
+  ls -- *.gem >&2 || true
+  exit 1
+fi
+
+echo "--- Checking rubygems.org for existing version ${VERSION} (read-only)"
+STATUS="$(curl -s -o /dev/null -w "%{http_code}" "https://rubygems.org/api/v2/rubygems/${GEM_NAME}/versions/${VERSION}.json")"
+if [ "${STATUS}" = "200" ]; then
+  ALREADY_PUBLISHED=true
+  echo "${GEM_NAME} ${VERSION} is already on rubygems.org"
+else
+  ALREADY_PUBLISHED=false
+  echo "${GEM_NAME} ${VERSION} is not on rubygems.org (HTTP ${STATUS})"
+fi
+
+if [ "${RELEASE_EXECUTE:-}" != "true" ]; then
+  echo "--- Rehearsal only"
+  echo "RELEASE_EXECUTE is not 'true': stopping before 'gem push ${GEM_FILENAME}'."
+  exit 0
+fi
+
+echo "--- Publishing ${GEM_FILENAME} to RubyGems"
+if [ -z "${BUILDKITE_TAG:-}" ]; then
+  echo "RELEASE_EXECUTE=true without a ${PROJECT}/vX.Y.Z tag; refusing" >&2
+  exit 1
+fi
+if [ "${ALREADY_PUBLISHED}" = "true" ]; then
+  echo "version ${VERSION} already published; refusing" >&2
+  exit 1
+fi
+if [ -z "${GEM_HOST_API_KEY:-}" ]; then
+  echo "GEM_HOST_API_KEY not set (rubygems-oidc plugin missing or failed)" >&2
+  exit 1
+fi
+gem push "${GEM_FILENAME}"

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # CHANGELOG
 
+## v2.15.0
+
+* Add [experimental, opt-in OpenTelemetry trace export](docs/opentelemetry.md)
+  for RSpec suites. Both modes share execution spans and run resources while
+  preserving execution roots; `otel_only` skips legacy trace capture and JSON
+  uploads. Standard OTLP header environment variables are supported for export
+  authentication. Export requires Ruby 3.3 or newer and the OpenTelemetry SDK
+  and OTLP exporter gems.
+
+* Automatically tag executions with `ci.worker.id` from `BUILDKITE_AGENT_ID`,
+  so failures can be grouped by the agent that ran them. An explicit
+  caller-supplied `ci.worker.id` tag still takes precedence.
+
+* Drop support for Ruby 2.x. Ruby 3.0 or newer is now required.
+
 ## v2.14.0
 
 * Send `location_prefix` in `run_env`

data/Gemfile

@@ -8,3 +8,8 @@ gemspec
 gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
+
+if Gem.ruby_version >= Gem::Version.new("3.3")
+  gem "opentelemetry-exporter-otlp", "~> 0.34"
+  gem "opentelemetry-sdk", "~> 1.13"
+end

data/README.md

@@ -83,6 +83,102 @@ BUILDKITE_ANALYTICS_TOKEN=xyz cucumber
 
 Add the `BUILDKITE_ANALYTICS_TOKEN` secret to your CI, push your changes to a branch, and open a pull request 🎉
 
+### OpenTelemetry export (experimental)
+
+RSpec suites can also send an OpenTelemetry trace per test execution to Buildkite,
+showing what each test did and where it spent its time. Each trace is rooted in a
+`test.execution` span carrying its name, location, result, and any failure detail.
+Tags passed to `configure` appear as resource attributes, while `tag_execution`
+adds attributes to the current test's root span.
+
+This feature is still under development and may change. This first release is
+intended for suites that do not already configure OpenTelemetry. It may work
+with an existing OpenTelemetry setup, but that configuration is not yet
+supported or guaranteed to work.
+
+OpenTelemetry export is off by default. Opt in when you configure the collector:
+
+```ruby
+Buildkite::TestCollector.configure(hook: :rspec, otel_enabled: true)
+```
+
+Execution roots use a private AlwaysOn provider so a suite's sampling policy
+cannot remove them.
+
+The collector configures a global provider for child spans and installs all
+applicable instrumentation registered when the suite starts. Because export is
+optional and its dependencies require Ruby 3.3+, the collector does not install
+them automatically. Add the OpenTelemetry SDK and OTLP exporter, plus any
+instrumentation you want to use:
+
+```ruby
+# Gemfile
+gem "opentelemetry-exporter-otlp", "~> 0.34", require: false
+gem "opentelemetry-sdk", "~> 1.13", require: false
+gem "opentelemetry-instrumentation-pg", require: false
+
+# spec/spec_helper.rb
+require "opentelemetry-instrumentation-pg"
+require "buildkite/test_collector"
+
+Buildkite::TestCollector.configure(hook: :rspec, otel_enabled: true)
+```
+
+Adding a gem to the Gemfile may auto-require it in applications that call
+`Bundler.require`, but that is not guaranteed. An explicit `require` is the
+recommended setup. To disable instrumentations and export only root
+`test.execution` spans, set `otel_instrumentations: []`. Any other value is
+reserved for a future release and disables span export with a warning. See the
+[OpenTelemetry guide](docs/opentelemetry.md#choosing-instrumentation) for more.
+
+Export needs Ruby 3.3 or newer, which is what the OpenTelemetry gems require. If
+those gems are unavailable, the option is accepted and export remains disabled.
+
+The collector honors standard `OTEL_EXPORTER_OTLP_TRACES_HEADERS` (or the
+generic `OTEL_EXPORTER_OTLP_HEADERS`) and gives them precedence over its own
+headers, including `Authorization`. bktec's OTLP relay uses this to provide its
+local credential without changing `BUILDKITE_ANALYTICS_TOKEN`, which remains
+available for normal JSON uploads in `otel_enabled` mode. Without an OTLP
+Authorization header, spans use `BUILDKITE_ANALYTICS_TOKEN`, which must be an
+agent OIDC token with the `write_uploads` scope; a suite API token still uploads
+executions, but its spans are rejected.
+
+Export failures never fail a test or block the normal Test Engine upload. See the
+[OpenTelemetry guide](docs/opentelemetry.md) for setup details and current
+limitations.
+
+### OTLP-only submission (experimental)
+
+RSpec suites can go one step further and submit results *only* over OTLP, with
+no JSON upload at all. It exports the same spans as `otel_enabled` and adds
+`buildkite.execution.via=otlp`, which tells Buildkite to synthesize each test
+execution from its span server-side:
+
+```ruby
+Buildkite::TestCollector.configure(hook: :rspec, otel_only: true)
+```
+
+In this mode the collector's legacy machinery is switched off: nothing is
+uploaded to `/v1/uploads`, and `Net::HTTP` and `Object` are left unpatched. The
+gem's whole job is to configure OpenTelemetry so each test gets a suitable span:
+
+- `Buildkite::TestCollector.annotate` adds a `test.annotation` event to the
+  current span.
+- `Buildkite::TestCollector.tag_execution` sets attributes on the test span.
+- `tags:` given to `configure` become resource attributes on every span.
+- Instrumentation works exactly as it does with `otel_enabled`: everything you
+  require and register installs, and `otel_instrumentations: []` exports only
+  the `test.execution` spans. See
+  [choosing instrumentation](docs/opentelemetry.md#choosing-instrumentation).
+- Your code can also talk to OpenTelemetry directly — the collector configures
+  the global tracer provider, so
+  `OpenTelemetry::Trace.current_span.set_attribute(...)` works during a test,
+  and any instrumentation joins the test's trace.
+
+`otel_only` is currently RSpec-only and has the same Ruby 3.3+ and OpenTelemetry
+gem requirements as `otel_enabled`. It's an alternative to `otel_enabled`; the
+two are mutually exclusive, and passing both (either value) raises
+`ArgumentError`.
 
 ## More information
 
@@ -112,16 +208,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/buildk
 
 ## 🚀 Releasing
 
-1. Bump the version in `version.rb` and run `bundle` to update the `Gemfile.lock`.
-2. Update the CHANGELOG.md with your new version and a description of your changes.
-3. Once your PR is merged to `main` git tag the merge commit and push:
-
-```
-git tag vX.X.X
-git push origin vX.X.X
-```
-4. Visit the [release pipeline](https://buildkite.com/buildkite/test-collector-ruby-release) to unblock it and confirm the new version is pushed to rubygems.org
-5. Create a [new release in github](https://github.com/buildkite/test-collector-ruby/releases).
+See the monorepo's [collector release guide](../RELEASING.md#ruby-rubygems).
 
 ## 📜 MIT License
 

data/buildkite-test_collector.gemspec

@@ -22,17 +22,13 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
 
   spec.add_dependency "concurrent-ruby"
 
   spec.add_development_dependency "activesupport", ">= 4.2"
+  spec.add_development_dependency "cucumber", '~> 9.0'
   spec.add_development_dependency "ostruct"
   spec.add_development_dependency "rspec-core", '~> 3.10'
   spec.add_development_dependency "rspec-expectations", '~> 3.10'
-
-  # When running the legacy CI builds against versions of Ruby pre 2.7 we cannot include cucumber 9 as it's not supported.
-  if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.7')
-    spec.add_development_dependency "cucumber", '~> 9.0'
-  end
 end

data/buildkite.yaml

@@ -27,36 +27,29 @@ steps:
       - "latest"
       - "3.4"
       - "3.3"
+
+  - label: ":rspec: Tests (EOL Ruby) :ruby: {{matrix}}"
+    command:
+      - "gem install bundler:2.3.25"
+      - "bundle"
+      - "bundle exec rake"
+      - "bundle exec cucumber"
+    plugins:
+      - aws-assume-role-with-web-identity#v1.2.0:
+          role-arn: "${OIDC_ASSUME_ROLE_ARN:-arn:aws:iam::445615400570:role/pipeline-buildkite-test-collector-ruby-build}"
+          session-tags:
+            - organization_slug
+            - organization_id
+            - pipeline_slug
+            - build_branch
+
+      - ecr#v2.9.0:
+          login: true
+          account_ids: "public.ecr.aws"
+          region: "us-east-1"
+      - docker#v3.7.0:
+          image: "public.ecr.aws/docker/library/ruby:{{matrix}}"
+    matrix:
       - "3.2"
       - "3.1"
       - "3.0"
-      - "2.7"
-
-  - group: ":rspec: Legacy Ruby :ruby:"
-    steps:
-      - label: ":rspec: Tests :ruby: {{matrix}}"
-        command:
-          - "gem install bundler:2.3.25"
-          - "bundle"
-          - "bundle exec rake"
-        plugins:
-          - aws-assume-role-with-web-identity#v1.2.0:
-              role-arn: "${OIDC_ASSUME_ROLE_ARN:-arn:aws:iam::445615400570:role/pipeline-buildkite-test-collector-ruby-build}"
-              session-tags:
-                - organization_slug
-                - organization_id
-                - pipeline_slug
-                - build_branch
-          - ecr#v2.9.0:
-              login: true
-              account_ids: "public.ecr.aws"
-              region: "us-east-1"
-          - docker#v3.7.0:
-              # Images for older Ruby versions aren't available on AWS ECR
-              # so fall back to Docker Hub
-              image: "ruby:{{matrix}}"
-        matrix:
-          - "2.6"
-          - "2.5"
-          - "2.4"
-          - "2.3"

data/docs/opentelemetry.md

@@ -0,0 +1,247 @@
+# OpenTelemetry export (experimental)
+
+> **This feature is still under development and may change.**
+> This first release is intended for suites that do not already configure
+> OpenTelemetry. Existing OpenTelemetry setups may work, but are not yet
+> supported or guaranteed to work.
+
+This page describes `otel_enabled`, where spans are exported *alongside* the
+normal JSON upload and linked to it by trace ID. There is also an OTLP-only
+mode (`otel_only`) that exports the same spans but adds
+`buildkite.execution.via=otlp`. That marker makes the span itself the
+submission: Buildkite synthesizes the execution from it server-side, with
+nothing sent to `/v1/uploads`. In both modes the run's details (run key, branch,
+commit, and any `tags:` you configure) travel as OpenTelemetry resource
+attributes on the spans the collector exports. See the
+[README](../README.md#otlp-only-submission-experimental) for how to turn it on,
+and [OTLP-only attributes](#otlp-only-attributes) below for what's sent.
+
+Every RSpec example gets an OpenTelemetry `test.execution` root. The collector
+can configure a provider and export instrumented child spans showing what the
+test did and where its time went. The traces are sent to Buildkite and shown
+against the test's execution.
+
+It is off by default. See the [README](../README.md#opentelemetry-export-experimental)
+for how to turn it on.
+
+Export requires Ruby 3.3 or newer and the `opentelemetry-sdk` and
+`opentelemetry-exporter-otlp` gems. These optional dependencies are not installed
+with `buildkite-test_collector`; add them to your bundle as shown in
+[Choosing instrumentation](#choosing-instrumentation). This requirement applies
+to both `otel_enabled` and `otel_only`.
+
+## What a trace looks like
+
+Each example gets a `test.execution` span of its own, with the instrumented work
+it did underneath:
+
+```text
+test.execution  "Buildkite::Pipeline creates a build"   12.4ms
+├── GET         api.example.com                          8.1ms
+└── SELECT      pipelines                                1.2ms
+```
+
+One example is one trace. The span is never nested under anything else, so a
+trace always belongs to exactly one test. On Buildkite Agent v3.110 or newer,
+the root span links to the Agent's propagated job trace when tracing is enabled,
+letting you navigate between them without combining every test into one trace.
+
+## What's on the span
+
+Each `tags:` entry passed to `configure` is attached to the root as a
+`buildkite.tag.<key>` resource attribute. Per-execution tags use the same prefix
+as span attributes.
+
+| Attribute | Value |
+| --- | --- |
+| `buildkite.test.scope` | the example group |
+| `buildkite.test.name` | the example's description |
+| `test.case.name` | the example's full description |
+| `test.suite.name` | the example group |
+| `code.file.path` | the file the test is in |
+| `code.line.number` | the line, or the call site for a shared example |
+| `test.case.result.status` | `pass`, `fail` or `skipped` |
+| `buildkite.test.execution.external_id` | the ID of the matching Test Engine execution |
+| `buildkite.tag.<key>` | each `tag_execution` tag |
+
+A failed test also sets the span's status to error with the failure summary as
+its description. Each failure is recorded as a semconv `exception` event with
+`exception.message` and `exception.stacktrace` attributes.
+
+Two things worth knowing:
+
+- An example skipped with `skip` produces no span at all. RSpec doesn't run its
+  hooks, so there is nothing to time. `skipped` on a span means a `pending`
+  example that failed as expected.
+- The execution's duration is whatever the span timed, so the two always agree.
+  With the export off, the collector times the example itself as it always has.
+- The result is RSpec's final verdict, read after every `around` hook has
+  unwound: an `around` hook that raises after the example ran counts as a
+  failure, and an example a hook marks `pending` before deliberately raising
+  stays skipped.
+
+## OTLP-only attributes
+
+Both modes use the same resource and span attributes. With `otel_only`, the
+`buildkite.execution.via=otlp` marker opts the span into execution synthesis.
+Buildkite attributes are flat (`buildkite.run_key`, `buildkite.build_id`, ...),
+matching the agent's own OpenTelemetry attributes; everything else follows
+OpenTelemetry semantic conventions.
+
+Run-level details travel once, as resource attributes on every span:
+
+| Resource attribute | Value | Execution field |
+| --- | --- | --- |
+| `buildkite.run_key` | the run key (required) | run key |
+| `buildkite.run_url` | the build URL | URL |
+| `vcs.ref.head.name` | the branch (or tag) name | branch |
+| `vcs.ref.head.revision` | the commit SHA | commit |
+| `vcs.ref.head.type` | `branch` or `tag` | — |
+| `buildkite.build_number` | the build number | number |
+| `buildkite.build_id` | the build's UUID | build ID |
+| `buildkite.job_id` | the job's UUID | job ID |
+| `buildkite.step_id` | the step's UUID | step ID |
+| `buildkite.message` | the commit message | message |
+| `buildkite.collector.name` | this gem's name | collector |
+| `buildkite.collector.version` | this gem's version | version |
+| `buildkite.tag.<key>` | each `tags:` entry from `configure` | run tag `<key>` |
+
+The resource also names the suite for any other OpenTelemetry backend looking
+at the same spans: `service.name` (the suite slug), `service.namespace` (the
+organization slug), `service.instance.id` (the job UUID), and
+`buildkite.test.framework.name`/`.version`. Buildkite doesn't use these.
+
+Each test's span carries the execution itself:
+
+| Span attribute | Value | Execution field |
+| --- | --- | --- |
+| `buildkite.execution.via` | `otlp` in OTLP-only mode — opts this span in to synthesis | — |
+| `buildkite.test.scope` | the example group | scope |
+| `buildkite.test.name` | the example's description | name |
+| `test.suite.name` | the example group | — |
+| `test.case.name` | the example's full description | — |
+| `code.file.path` | the file the test is in | file name, location |
+| `code.line.number` | the line number | location |
+| `test.case.result.status` | `pass`, `fail`, `skipped` | result |
+| `buildkite.test.execution.external_id` | the execution's collector-generated ID | external ID |
+| `buildkite.tag.<key>` | each `tag_execution` tag | execution tag `<key>` |
+
+In OTLP-only mode the server maps the span's failure status and exception events
+back to the execution's failure reason and expanded failure detail.
+
+## Finding a test's trace
+
+With `otel_enabled`, the trace's ID is sent in the JSON execution so Buildkite
+can show the two together. With `otel_only`, the span is the execution. Child
+spans share the root's trace ID through normal context propagation, so one trace
+holds everything the test did.
+
+## Recommended setup: suites without OpenTelemetry
+
+The collector configures a global SDK provider for child spans and installs the
+applicable instrumentation registered when the suite starts. The private
+provider still owns `test.execution`; instrumented spans use the
+collector-created provider's normal sampling. The same forwarding filter
+excludes setup, teardown, detached traces, and other spans outside an active
+execution.
+
+## Choosing instrumentation
+
+Instrumentation selection applies only when the collector configures the global
+provider, and works the same with `otel_enabled` and `otel_only`.
+Add the OpenTelemetry SDK and OTLP exporter, plus the instrumentation you want,
+to your bundle. Require each instrumentation explicitly:
+
+```ruby
+# Gemfile
+group :test do
+  gem "opentelemetry-exporter-otlp", "~> 0.34", require: false
+  gem "opentelemetry-sdk", "~> 1.13", require: false
+  gem "opentelemetry-instrumentation-pg", require: false
+  gem "opentelemetry-instrumentation-redis", require: false
+end
+```
+
+```ruby
+# spec/spec_helper.rb
+require "opentelemetry-instrumentation-pg"
+require "opentelemetry-instrumentation-redis"
+require "buildkite/test_collector"
+
+Buildkite::TestCollector.configure(
+  hook: :rspec,
+  otel_enabled: true,
+)
+```
+
+A Gemfile entry makes the gem available but does not always load it. Some
+applications call `Bundler.require` and auto-require their gems, but that is
+host-dependent and can be disabled with `require: false`. Explicitly requiring
+each instrumentation is the recommended setup.
+
+Requiring an instrumentation gem registers its definition; it does not install
+the instrumentation immediately. The collector defers OpenTelemetry setup until
+RSpec's `before(:suite)` hooks and asks the SDK to install all registered
+instrumentation. The SDK skips instrumentation whose target library is absent
+or incompatible and reports individual installation failures without stopping
+the remaining installations.
+
+To prevent the collector from installing registered instrumentation, pass an
+empty list. Manually created spans under an execution are still forwarded:
+
+```ruby
+Buildkite::TestCollector.configure(
+  hook: :rspec,
+  otel_enabled: true,
+  otel_instrumentations: [],
+)
+```
+
+For this release, omitting `otel_instrumentations` and setting it to `[]` are the
+only supported choices. Any other value is reserved for a future release and
+disables span export with a warning, in every path. The collector does not
+inspect instrumentation patches, so compatibility between customer-selected
+instrumentation and other APM or test-library patches remains the customer's
+responsibility.
+
+## What gets sent
+
+The collector merges standard `OTEL_EXPORTER_OTLP_TRACES_HEADERS` (or, when it
+is absent, `OTEL_EXPORTER_OTLP_HEADERS`) over its own OTLP headers. Header names
+are matched case-insensitively, so a standard `authorization` entry takes
+precedence over the credential sourced from `BUILDKITE_ANALYTICS_TOKEN`. Empty
+header environment variables are treated as unset.
+
+bktec's OTLP relay uses the trace-specific header variable to provide its local
+credential. bktec forwards spans to Buildkite with its OIDC credential while
+`BUILDKITE_ANALYTICS_TOKEN` remains available for normal JSON uploads in
+`otel_enabled` mode. Without an OTLP Authorization header, spans go directly to
+Buildkite using `BUILDKITE_ANALYTICS_TOKEN`, which must be an agent OIDC token
+with the `write_uploads` scope; a suite API token uploads test results as normal
+but its spans are rejected.
+
+OpenTelemetry's SDK owns batching, retries, and transport. `test.execution`
+spans have a reserved, faster-draining queue and exporter. Forwarded children
+use a separate queue and exporter, so a child flood or invalid child request
+cannot displace or poison execution roots. When the suite finishes, both queues
+share one 30-second flush budget, roots first. A hard exit or sustained endpoint
+failure can still lose spans because the queues live in process memory.
+
+One process reports one run. Export survives repeated suite runs in the same
+process (warm workers), and a refreshed token is picked up when the collector
+is reconfigured, but run identity is fixed when export starts: reconfiguring
+with a different run key warns and keeps attributing results to the original
+run. Reporting a new run requires a new process.
+
+## When something goes wrong
+
+Export never fails a test. If root setup fails, the collector warns and the
+normal test result upload continues without spans. If optional child setup or
+attachment fails, the collector warns, cleans up that path, and continues
+exporting roots. The suite-end flush and the process-exit shutdown each give
+the OpenTelemetry SDK a 30-second budget to export buffered spans; the SDK's
+own retry backoff can run past it when the endpoint keeps failing.
+
+Export failures are reported through OpenTelemetry's own logger. The collector
+also warns if its reserved root queue drops any `test.execution` spans; normal
+child-span queue overflow is not logged by the OpenTelemetry SDK.

data/lib/buildkite/test_collector/ci.rb

@@ -67,10 +67,14 @@ class Buildkite::TestCollector::CI
   end
 
   def github_actions
+    repository = ENV["GITHUB_REPOSITORY"]
+    run_id = ENV["GITHUB_RUN_ID"]
+    url = File.join("https://github.com", repository, "actions/runs", run_id) if repository && run_id
+
     {
       "CI" => "github_actions",
       "key" => "#{ENV["GITHUB_ACTION"]}-#{ENV["GITHUB_RUN_NUMBER"]}-#{ENV["GITHUB_RUN_ATTEMPT"]}",
-      "url" => File.join("https://github.com", ENV["GITHUB_REPOSITORY"], "actions/runs", ENV["GITHUB_RUN_ID"]),
+      "url" => url,
       "branch" => ENV["GITHUB_REF_NAME"],
       "commit_sha" => ENV["GITHUB_SHA"],
       "number" => ENV["GITHUB_RUN_NUMBER"],