logtail-rails 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c5828f2141c9b70b0f47591b7dcf8855a648c0297477637fd7029cfd5e39a8d
-  data.tar.gz: 0a88a29844cdbbc76a20a827f0575fc3f3aa4befe32dde404315bb55a733cfa2
+  metadata.gz: 5ce3c0d5b067b69401f94dd38e671d089ec35acdc64fcf02aff7b77360c7f268
+  data.tar.gz: 134e79823c37bc41fea97a49946cc964b58c19729261ceffc137a05ff837987c
 SHA512:
-  metadata.gz: 9238c31e5e7945f99fdc3acae8a7006f6f0568e3e2269469a0498da0d5010718d2a3dc884bfd64cc471be0c7a54283e32ff327f8fa1dd11d70b76d1baf84dc2c
-  data.tar.gz: 76f5185abcdc9efafbe564d65a543cb924dcfb75326686645f346a7e30201b053cad5380701f8abe3d0ed01db85f0a54b631522dca449bf4aba2164967f6d840
+  metadata.gz: 922aa5b53d2217e240d44b663c7a5993e45186bd94a1bbaa24892c23dba05fb81efe55a6fd0e24709417cb5192d73a373a7cfb1210b714da206b8d74836e76f3
+  data.tar.gz: d96272725a31d29a68b9d859e621098ef0066c7e89328f445bb9970eaa91adafb3bc4fefa67d11fa0680cbabc3db241631b441e569fee35b4e66673a4a7e0ba1

data/.github/actions/cleanup-sources/action.yml

@@ -0,0 +1,33 @@
+# Deletes the run's source and stale sources of earlier runs of the same test, and never fails the job.
+# The logic is in run.sh, which reads only environment variables, so it runs the same way outside of Actions.
+name: "Clean up Better Stack sources"
+description: "Deletes this run's source and sources of earlier runs, named with the same prefix, that are older than stale-hours"
+
+inputs:
+  api-token:
+    description: "Telemetry API token of the team the sources are in"
+    required: true
+  prefix:
+    description: "Name prefix of this test's sources, only those are swept"
+    required: true
+  id:
+    description: "Id of this run's source, deleted whatever its age"
+    default: ""
+  stale-hours:
+    description: "Sources with the prefix older than this many hours are left over from earlier runs"
+    default: "3"
+  out:
+    description: "Directory for cleanup.md"
+    default: out
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      env:
+        INPUT_API_TOKEN: ${{ inputs.api-token }}
+        INPUT_PREFIX: ${{ inputs.prefix }}
+        INPUT_ID: ${{ inputs.id }}
+        INPUT_STALE_HOURS: ${{ inputs.stale-hours }}
+        INPUT_OUT: ${{ inputs.out }}
+      run: bash "${{ github.action_path }}/run.sh"

data/.github/actions/cleanup-sources/run.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Deletes this run's source, then what earlier runs of the same test left behind (a cancelled job never reaches its
+# cleanup): every source whose name starts with the prefix and that is older than stale-hours. Younger sources may
+# belong to a run still in progress and stay. Writes <out>/cleanup.md, one line per deletion, and always exits 0:
+# a failed deletion shows in the report, but never hides the test result.
+# Env: INPUT_API_TOKEN, INPUT_PREFIX, INPUT_ID (optional), INPUT_STALE_HOURS (default 3), INPUT_OUT (default out).
+set -euo pipefail
+# A native jq.exe, as on Windows runners, ends its output lines with CRLF unless given -b.
+if [ "${OS:-}" = Windows_NT ]; then jq() { command jq -b "$@"; }; fi
+
+API=https://telemetry.betterstack.com
+OUT=${INPUT_OUT:-out}
+mkdir -p "$OUT"
+: > "$OUT/cleanup.md"
+say() { echo "$1"; echo "$1" >> "$OUT/cleanup.md"; }
+trap 'status=$?; [ "$status" = 0 ] || say "- ❌ cleanup stopped on an error, see the log of this step"; exit 0' EXIT
+
+delete() {
+  local code
+  code=$(curl -sS -m 60 -o /dev/null -w '%{http_code}' -X DELETE "$API/api/v1/sources/$1" -H "Authorization: Bearer $INPUT_API_TOKEN") || code=000
+  case "$code" in
+    204) say "- deleted $2" ;;
+    404) say "- $2 was already gone" ;;
+    *) say "- ❌ could not delete $2 (HTTP $code)" ;;
+  esac
+}
+
+say "### Cleanup"
+say ""
+[ -z "${INPUT_ID:-}" ] || delete "$INPUT_ID" "this run's source $INPUT_ID"
+
+# An empty prefix would sweep every source of the team.
+[ -n "$INPUT_PREFIX" ] || { say "- ❌ no prefix given, so stale sources were not looked for"; exit 0; }
+# The name filter matches anywhere in the name, so the prefix is checked again. The next-page link the API returns
+# drops the filter, so pages are counted here instead of following it.
+STALE=""
+for ((page = 1; ; page++)); do
+  RES=$(curl -sS -m 60 -G "$API/api/v1/sources" --data-urlencode "name=$INPUT_PREFIX" -d per_page=250 -d "page=$page" -H "Authorization: Bearer $INPUT_API_TOKEN") || RES=""
+  jq -e '.data | type == "array"' <<<"$RES" >/dev/null 2>&1 || { say "- ❌ could not list sources, so stale ones were not deleted: $(head -c 300 <<<"${RES:-no response}")"; STALE=""; break; }
+  STALE+=$(jq -r --arg prefix "$INPUT_PREFIX" --arg id "${INPUT_ID:-}" --argjson hours "${INPUT_STALE_HOURS:-3}" '.data[]
+    | select((.attributes.name | startswith($prefix)) and .id != $id)
+    | select((.attributes.created_at | sub("\\.[0-9]+"; "") | fromdateiso8601) < now - $hours * 3600)
+    | "\(.id) \(.attributes.created_at) \(.attributes.name)"' <<<"$RES")$'\n'
+  [ "$(jq -r '.pagination.next' <<<"$RES")" != null ] || break
+done
+while read -r id created_at name; do
+  [ -n "$id" ] || continue
+  delete "$id" "stale source $id \`$name\` (created $created_at)"
+done <<<"$STALE"
+
+[ "$(wc -l < "$OUT/cleanup.md")" -gt 2 ] || say "- nothing to delete"

data/.github/actions/create-source/action.yml

@@ -0,0 +1,46 @@
+# Creates a Better Stack source through the Telemetry API and waits until ingest reliably accepts its token.
+# The logic is in run.sh, which reads only environment variables, so it runs the same way outside of Actions.
+name: "Create a Better Stack source"
+description: "Creates a source, warms it up until ingest accepts its token and outputs where to send and read logs"
+
+inputs:
+  api-token:
+    description: "Telemetry API token of the team the source is created in"
+    required: true
+  name:
+    description: "Name of the new source"
+    required: true
+  platform:
+    description: "Platform of the new source, as the Telemetry API names it"
+    required: true
+
+outputs:
+  id:
+    description: "Source id"
+    value: ${{ steps.run.outputs.id }}
+  token:
+    description: "Source token for ingest (masked in the logs)"
+    value: ${{ steps.run.outputs.token }}
+  ingesting-host:
+    description: "Host to send logs to"
+    value: ${{ steps.run.outputs.ingesting-host }}
+  data-region:
+    description: "Data region the source stores its logs in"
+    value: ${{ steps.run.outputs.data-region }}
+  collection:
+    description: "Collection name for the SQL API, t<team id>_<table name>"
+    value: ${{ steps.run.outputs.collection }}
+  connect-host:
+    description: "SQL API host that reads this source"
+    value: ${{ steps.run.outputs.connect-host }}
+
+runs:
+  using: composite
+  steps:
+    - id: run
+      shell: bash
+      env:
+        INPUT_API_TOKEN: ${{ inputs.api-token }}
+        INPUT_NAME: ${{ inputs.name }}
+        INPUT_PLATFORM: ${{ inputs.platform }}
+      run: bash "${{ github.action_path }}/run.sh"

data/.github/actions/create-source/run.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Creates a source and warms it up. A fresh source drops what it receives in its first seconds, and every ingest
+# process picks up a new token on its own schedule, so one accepted line proves nothing: the source counts as ready
+# after 20 probe lines in a row were accepted, plus a short pause to settle. Probe lines carry the message
+# "e2e warm-up <source name>", which verify-logs ignores.
+# Env: INPUT_API_TOKEN, INPUT_NAME, INPUT_PLATFORM, GITHUB_OUTPUT.
+set -euo pipefail
+# A native jq.exe, as on Windows runners, ends its output lines with CRLF unless given -b.
+if [ "${OS:-}" = Windows_NT ]; then jq() { command jq -b "$@"; }; fi
+
+API=https://telemetry.betterstack.com
+
+BODY=$(jq -nc --arg name "$INPUT_NAME" --arg platform "$INPUT_PLATFORM" '{name: $name, platform: $platform}')
+RES=$(curl -sS -m 60 -X POST "$API/api/v1/sources" -H "Authorization: Bearer $INPUT_API_TOKEN" -H 'Content-Type: application/json' -d "$BODY") || true
+ID=$(jq -er '.data.id' <<<"$RES" 2>/dev/null) || { echo "::error::creating source $INPUT_NAME failed: ${RES:-no response}"; exit 1; }
+TOKEN=$(jq -r '.data.attributes.token' <<<"$RES")
+INGESTING_HOST=$(jq -r '.data.attributes.ingesting_host' <<<"$RES")
+DATA_REGION=$(jq -r '.data.attributes.data_region' <<<"$RES")
+echo "::add-mask::$TOKEN"
+{
+  echo "id=$ID"
+  echo "token=$TOKEN"
+  echo "ingesting-host=$INGESTING_HOST"
+  echo "data-region=$DATA_REGION"
+  echo "collection=t$(jq -r '.data.attributes.team_id' <<<"$RES")_$(jq -r '.data.attributes.table_name' <<<"$RES")"
+  echo "connect-host=$DATA_REGION-connect.betterstackdata.com"
+} >> "$GITHUB_OUTPUT"
+echo "created source $ID \`$INPUT_NAME\` in data region $DATA_REGION"
+
+PROBE=$(jq -nc --arg message "e2e warm-up $INPUT_NAME" '{message: $message}')
+STREAK=0
+DEADLINE=$((SECONDS + 300))
+while [ "$STREAK" -lt 20 ]; do
+  CODE=$(curl -sS -m 10 -o /dev/null -w '%{http_code}' -X POST "https://$INGESTING_HOST/" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d "$PROBE") || true
+  if [ "$CODE" = 202 ]; then STREAK=$((STREAK + 1)); else echo "ingest answered HTTP $CODE after $STREAK accepted in a row"; STREAK=0; fi
+  [ "$SECONDS" -lt "$DEADLINE" ] || { echo "::error::ingest did not accept the token of source $ID 20 times in a row within 5 min"; exit 1; }
+  sleep 1
+done
+sleep 15
+echo "ingest accepted 20 probe lines in a row, source $ID is ready"

data/.github/actions/verify-logs/action.yml

@@ -0,0 +1,47 @@
+# Reads a source's logs back through the team's SQL API connection and checks them exactly against an expected file.
+# The logic is in run.sh, which reads only environment variables, so it runs the same way outside of Actions.
+name: "Verify stored logs"
+description: "Polls a source's stored logs until the expected rows arrive, then checks each one is stored exactly once"
+
+inputs:
+  connection-username:
+    description: "Username of the team's SQL API connection"
+    required: true
+  connection-password:
+    description: "Password of the team's SQL API connection"
+    required: true
+  connect-host:
+    description: "SQL API host, the connect-host output of create-source"
+    required: true
+  collection:
+    description: "Collection to read, the collection output of create-source"
+    required: true
+  expected:
+    description: >-
+      Path to a JSON array of the rows that must be stored, each {"level": ..., "message": ...} or
+      {"level": ..., "message_prefix": ...}, optionally with "contains": an object the stored row must contain
+    required: true
+  out:
+    description: "Directory for rows.json and summary.md"
+    default: out
+  deadline-seconds:
+    description: "How long to wait for the expected number of rows"
+    default: "300"
+  ignore-message-prefix:
+    description: "Rows whose message starts with this are not counted (the warm-up lines of create-source)"
+    default: "e2e warm-up"
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      env:
+        INPUT_CONNECTION_USERNAME: ${{ inputs.connection-username }}
+        INPUT_CONNECTION_PASSWORD: ${{ inputs.connection-password }}
+        INPUT_CONNECT_HOST: ${{ inputs.connect-host }}
+        INPUT_COLLECTION: ${{ inputs.collection }}
+        INPUT_EXPECTED: ${{ inputs.expected }}
+        INPUT_OUT: ${{ inputs.out }}
+        INPUT_DEADLINE_SECONDS: ${{ inputs.deadline-seconds }}
+        INPUT_IGNORE_MESSAGE_PREFIX: ${{ inputs.ignore-message-prefix }}
+      run: bash "${{ github.action_path }}/run.sh"

data/.github/actions/verify-logs/run.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# Reads a source's logs back through the team's SQL API connection and checks them against an expected file: as
+# many rows as expected, each expected entry matched by exactly one row, no row left unmatched. Rows land in hot
+# storage first and are copied to cold storage later, so both are read and a cold row counts only when hot storage
+# lacks it. Once enough rows arrived it reads again 30 s later, so a duplicate delivery fails instead of slipping
+# through. Writes <out>/rows.json and <out>/summary.md on every exit path: the summary is what a failure report shows.
+# Env: INPUT_CONNECTION_USERNAME, INPUT_CONNECTION_PASSWORD, INPUT_CONNECT_HOST, INPUT_COLLECTION, INPUT_EXPECTED,
+#      INPUT_OUT (default out), INPUT_DEADLINE_SECONDS (default 300), INPUT_IGNORE_MESSAGE_PREFIX (default "e2e warm-up").
+set -euo pipefail
+# A native jq.exe, as on Windows runners, ends its output lines with CRLF unless given -b.
+if [ "${OS:-}" = Windows_NT ]; then jq() { command jq -b "$@"; }; fi
+
+OUT=${INPUT_OUT:-out}
+IGNORE=${INPUT_IGNORE_MESSAGE_PREFIX-e2e warm-up}
+# jq: the warm-up lines of create-source, rows whose message starts with the ignore prefix.
+IGNORED='def ignored: $ignore != "" and (.raw.message | type) == "string" and (.raw.message | startswith($ignore));'
+CHECKS=""
+FAILURE=""
+COUNTS=""
+mkdir -p "$OUT"
+echo '[]' > "$OUT/rows.json"
+
+fail() { FAILURE="$1"; echo "::error::$1"; exit 1; }
+
+summarize() {
+  local status=$?
+  {
+    echo "Read back through \`$INPUT_CONNECT_HOST\` from \`$INPUT_COLLECTION\`${COUNTS:+: $COUNTS}"
+    echo
+    if [ -n "$CHECKS" ]; then printf '%s' "$CHECKS"; else echo "- ❌ ${FAILURE:-stopped on an error, see the log of this step}"; fi
+    if [ "$(jq length "$OUT/rows.json")" -gt 0 ]; then
+      echo
+      echo "<details><summary>One stored row</summary>"
+      echo
+      echo '```json'
+      jq --arg ignore "$IGNORE" "$IGNORED"' (map(select(ignored | not)) | max_by(.raw | keys | length)) // .[0]' "$OUT/rows.json"
+      echo '```'
+      echo
+      echo "</details>"
+    fi
+  } > "$OUT/summary.md"
+  exit "$status"
+}
+trap summarize EXIT
+
+jq -e 'type == "array" and length > 0 and all(.[]; type == "object" and has("level") and (has("message") or has("message_prefix")))' "$INPUT_EXPECTED" >/dev/null 2>&1 \
+  || fail "$INPUT_EXPECTED is not a JSON array of {\"level\", \"message\" or \"message_prefix\", optional \"contains\"} objects"
+WANT=$(jq length "$INPUT_EXPECTED")
+
+# Writes the rows as JSONEachRow into $2, or nothing while the collection does not exist: it is created with the
+# source's first stored row.
+sql() {
+  local code
+  code=$(curl -sS -m 60 -o "$2" -w '%{http_code}' -u "$INPUT_CONNECTION_USERNAME:$INPUT_CONNECTION_PASSWORD" \
+    -H 'Content-Type: plain/text' --data-binary "$1 FORMAT JSONEachRow" "https://$INPUT_CONNECT_HOST/") || code=000
+  if [ "$code" = 500 ] && grep -qE 'CLUSTER_DOESNT_EXIST|NAMED_COLLECTION_DOESNT_EXIST|UNKNOWN_TABLE' "$2"; then : > "$2"; return; fi
+  [ "$code" = 200 ] || fail "the SQL API on $INPUT_CONNECT_HOST answered HTTP $code: $(head -c 300 "$2" 2>/dev/null)"
+}
+
+read_rows() {
+  sql "SELECT dt, raw FROM remote(${INPUT_COLLECTION}_logs)" "$OUT/hot.ndjson"
+  sql "SELECT dt, raw FROM s3Cluster(primary, ${INPUT_COLLECTION}_s3) WHERE _row_type = 1" "$OUT/cold.ndjson"
+  jq -n --slurpfile hot "$OUT/hot.ndjson" --slurpfile cold "$OUT/cold.ndjson" \
+    '($hot | map({dt, raw})) as $h | $h + ($cold | map({dt, raw}) | map(select(IN($h[]) | not))) | map(.raw |= fromjson) | sort_by(.dt)' > "$OUT/rows.json"
+  local all hot
+  all=$(jq length "$OUT/rows.json")
+  hot=$(jq -s length "$OUT/hot.ndjson")
+  GOT=$(jq --arg ignore "$IGNORE" "$IGNORED"' map(select(ignored | not)) | length' "$OUT/rows.json")
+  COUNTS="$hot rows in hot storage, $((all - hot)) more in cold storage, $((all - GOT)) of them ignored as \"$IGNORE\" lines"
+}
+
+DEADLINE=$((SECONDS + ${INPUT_DEADLINE_SECONDS:-300}))
+while :; do
+  read_rows
+  [ "$GOT" -lt "$WANT" ] || break
+  [ "$SECONDS" -lt "$DEADLINE" ] || { echo "deadline passed with $GOT of $WANT rows"; break; }
+  echo "$GOT of $WANT rows so far, reading again in 10 s"
+  sleep 10
+done
+echo "$GOT of $WANT rows, reading once more in 30 s to catch duplicate delivery"
+sleep 30
+read_rows
+
+# One check per line: the row count, each expected entry (exactly one row matches it), each row no entry matches.
+# "contains" is jq's contains: objects and arrays may hold more than expected, strings match as substrings.
+RESULT=$(jq -c --arg ignore "$IGNORE" --slurpfile expected "$INPUT_EXPECTED" "$IGNORED"'
+  def text: tostring | gsub("\\s+"; " ") | if length > 100 then .[0:100] + "..." else . end;
+  def message_matches($e): (.message | type) == "string" and if $e | has("message") then .message == $e.message else .message | startswith($e.message_prefix) end;
+  def matches($e): .level == $e.level and message_matches($e) and (($e | has("contains") | not) or contains($e.contains));
+  def describe: "`\(.level)` " + (if has("message") then "\"\(.message | text)\"" else "message starting with \"\(.message_prefix | text)\"" end)
+    + (if has("contains") then " containing `\(.contains | tojson | text)`" else "" end);
+  def near($e): [.[] | select(message_matches($e)) | if .level != $e.level then "a row with this message has level `\(.level)`" else "a row with this message lacks part of what it should contain" end] | unique;
+  map(select(ignored | not) | .raw) as $rows | $expected[0] as $expected
+  | [{ok: (($rows | length) == ($expected | length)), text: "\($rows | length) rows stored, \($expected | length) expected"}]
+  + [$expected[] as $e | ([$rows[] | select(matches($e))] | length) as $n | ($rows | near($e)) as $near
+      | {ok: ($n == 1), text: (($e | describe) + if $n == 1 then " stored once" elif $n > 1 then " stored \($n) times"
+          elif $near == [] then " missing" else " missing (\($near | join(", ")))" end)}]
+  + [$rows[] | select(. as $r | any($expected[]; . as $e | $r | matches($e)) | not) | {ok: false, text: "unexpected row: `\(.level)` \"\(.message | text)\""}]
+' "$OUT/rows.json")
+CHECKS=$(jq -r '.[] | "- \(if .ok then "✅" else "❌" end) \(.text)"' <<<"$RESULT")$'\n'
+printf '%s' "$CHECKS"
+PROBLEMS=$(jq -r 'map(select(.ok | not) | .text) | join("; ")' <<<"$RESULT")
+[ -z "$PROBLEMS" ] || fail "the stored rows differ from $INPUT_EXPECTED: $PROBLEMS"
+echo "every expected row is stored exactly once"

data/.github/workflows/e2e.yml

@@ -0,0 +1,275 @@
+name: E2E
+
+# Proves that the gem still delivers a Rails app's logs to Better Stack. Every job creates its own ruby source through
+# the Telemetry API, warms it up, starts the example project (example-project/, a Rails app) with that source's token
+# and ingesting host the way its README tells customers to (bin/rails server), requests /send_logs and /raise_error,
+# stops the server with Ctrl-C, reads the stored rows back through the testing team's SQL API connection, checks them
+# exactly against e2e/expected.json (nothing missing, extra or duplicated), and deletes the source again, together with
+# sources of earlier runs left behind for more than 3 hours. e2e/plan.sh plans four legs:
+#   floor   the oldest Rails the example runs on (its config.load_defaults, 7.1) at its newest patch, on the oldest Ruby
+#           that release allows, with logtail and logtail-rack at logtail-rails.gemspec's floors. The gemspec allows
+#           Rails 5.0 and Ruby 2.5, which only the unit tests (main.yml) cover.
+#   rails7  the newest Rails 7 on Ruby 3.2, with the newest logtail and logtail-rack
+#   latest  the newest stable Ruby that ruby/setup-ruby can install, with the newest Rails, logtail and logtail-rack
+#           releases; Bundler failing to install exactly those fails the job
+#   canary  ruby-head with the current commit of Rails' main branch
+# The floor and the Rails 7 leg run on the oldest Ubuntu image GitHub offers, latest and canary on ubuntu-latest, so a
+# new runner image is covered as well.
+# Every job checks, before it creates a source, that the Ruby running, the client (the gem built here, or rubygems.org
+# on the schedule), Rails, logtail and logtail-rack are the planned ones, and writes them into its summary. Which rows
+# the example logs depends on the Rails version: e2e/expected.json marks the ones a newer Rails adds with since_rails.
+# Pushes to main and pull requests install the gem built from the checkout. The daily schedule installs the newest
+# release from rubygems.org, which is what a customer gets today. A failure on main or on the schedule files a Linear
+# issue (notify_linear_failure.yml), at low priority when only the canary failed.
+# Pull requests from forks run only the plan: they get no secrets, so they cannot create a source.
+#
+# Secrets: TEST_TEAM_TELEMETRY_API, TEST_TEAM_CONNECTION_USERNAME, TEST_TEAM_CONNECTION_PASSWORD (Better Stack's E2E
+# testing team), LINEAR_* (see notify_linear_failure.yml).
+#
+# One leg, or exact versions: Actions → E2E → Run workflow, pick the leg and optionally set ruby-version (e.g. 3.3.6 or
+# head) or rails-version (a release such as 8.0.3, or a commit of Rails' main branch such as 3ba9e53), which replace
+# the planned versions of every leg that runs. That is how a failure is bisected to one release or commit.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: '15 7 * * *'
+  workflow_dispatch:
+    inputs:
+      leg:
+        description: 'Leg to run'
+        type: choice
+        options: [all, floor, rails7, latest, canary]
+        default: all
+      source:
+        description: 'checkout: the gem built from this checkout, as the Release workflow builds it. rubygems: its newest release on rubygems.org, what a customer installs'
+        type: choice
+        options: [checkout, rubygems]
+        default: checkout
+      ruby-version:
+        description: 'One exact Ruby version (e.g. 3.3.6 or head) instead of the planned one'
+        type: string
+      rails-version:
+        description: 'One exact Rails release (e.g. 8.0.3) or commit of its main branch (e.g. 3ba9e53) instead of the planned one'
+        type: string
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    # -eo pipefail: a failed command in front of a pipe fails the step.
+    shell: bash
+
+jobs:
+  plan:
+    runs-on: ubuntu-24.04
+    outputs:
+      matrix: ${{ steps.plan.outputs.matrix }}
+
+    steps:
+      - name: "[Setup] Checkout code"
+        uses: actions/checkout@v7
+
+      - name: "[Setup] Plan the legs"
+        id: plan
+        env:
+          LEG: ${{ inputs.leg || 'all' }}
+          RUBY_VERSION_INPUT: ${{ inputs.ruby-version }}
+          RAILS_VERSION_INPUT: ${{ inputs.rails-version }}
+          # The schedule tests what a customer installs today, pushes and pull requests test the checkout.
+          CLIENT_FROM: ${{ github.event_name == 'schedule' && 'rubygems' || inputs.source || 'checkout' }}
+        run: |
+          MATRIX=$(bash e2e/plan.sh)
+          echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
+          jq . <<<"$MATRIX"
+
+  test:
+    needs: plan
+    name: ${{ matrix.name }}
+    # Forks and Dependabot get no repository secrets, so their pull requests run only the plan.
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]') }}
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJSON(needs.plan.outputs.matrix) }}
+
+    env:
+      LEG: ${{ matrix.leg }}
+      PLANNED_RUBY: ${{ matrix.ruby }}
+      RAILS: ${{ matrix.rails }}
+      RAILS_REF: ${{ matrix.rails_ref }}
+      SQLITE3: ${{ matrix.sqlite3 }}
+      LOGTAIL: ${{ matrix.logtail }}
+      LOGTAIL_RACK: ${{ matrix.logtail_rack }}
+      CLIENT_FROM: ${{ matrix.source }}
+      CLIENT: ${{ matrix.client }}
+
+    steps:
+      - name: "[Setup] Checkout code"
+        uses: actions/checkout@v7
+
+      - name: "[Setup] Ruby ${{ matrix.ruby }}"
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+
+      - name: "[Setup] Build and install the client"
+        run: |
+          if [ "$CLIENT_FROM" = rubygems ]; then
+            echo "The example takes logtail-rails $CLIENT, its newest release, from rubygems.org."
+          else
+            # The gem the Release workflow builds and pushes to rubygems.org, installed without its dependencies: the
+            # next step installs those at the leg's versions, and Bundler takes this gem as it is installed.
+            gem build logtail-rails.gemspec
+            gem install --local --ignore-dependencies "logtail-rails-$CLIENT.gem"
+          fi
+
+      - name: "[Setup] Install the example's gems at the leg's versions"
+        run: bash e2e/example.sh install
+
+      - name: "[Verify] Installed versions are the planned ones"
+        working-directory: example-project
+        run: |
+          bundle exec ruby ../e2e/installed.rb > ../out/installed.txt
+          installed() { sed -n "s/^$1=//p" ../out/installed.txt; }
+          if [ "$CLIENT_FROM" = checkout ]; then FROM="the gem built here"; else FROM="rubygems.org"; fi
+          RAILS_FROM=$(installed rails)
+          [ "$RAILS" != main ] || RAILS_FROM="$RAILS_FROM from main at $(installed rails_ref | cut -c 1-7)"
+          echo "- $(installed ruby_description), Rails $RAILS_FROM, logtail-rails $(installed client) from $FROM, logtail $(installed logtail), logtail-rack $(installed logtail_rack), sqlite3 $(installed sqlite3)" | tee -a ../out/versions.md "$GITHUB_STEP_SUMMARY"
+          # The rows to expect depend on the Rails version, see since_rails in e2e/expected.json.
+          echo "RAILS_INSTALLED=$(installed rails)" >> "$GITHUB_ENV"
+          FAILED=0
+          # The planned Ruby is a minor (3.2), an exact version (4.0.9) or head, which reports patch level -1.
+          RUBY=$(installed ruby)
+          case "$PLANNED_RUBY" in
+            head) [ "$(installed ruby_dev)" = true ] || { echo "::error::Ruby $RUBY is running, but the $LEG leg plans ruby-head."; FAILED=1; } ;;
+            *) case "$RUBY" in
+                 "$PLANNED_RUBY" | "$PLANNED_RUBY".*) ;;
+                 *) echo "::error::Ruby $RUBY is running, but the $LEG leg plans $PLANNED_RUBY."; FAILED=1 ;;
+               esac ;;
+          esac
+          if [ "$RAILS" = main ]; then
+            case "$(installed rails_ref)" in
+              "$RAILS_REF"*) ;;
+              *) echo "::error::Rails $(installed rails) at '$(installed rails_ref)' is installed, but the $LEG leg plans Rails' main branch at $RAILS_REF."; FAILED=1 ;;
+            esac
+          elif [ "$(installed rails)" != "$RAILS" ]; then
+            echo "::error::Rails $(installed rails) is installed, but the $LEG leg plans $RAILS."; FAILED=1
+          fi
+          # Empty for the canary, which takes whatever Bundler picks and only reports it.
+          for check in "logtail $(installed logtail) $LOGTAIL" "logtail-rack $(installed logtail_rack) $LOGTAIL_RACK" "logtail-rails $(installed client) $CLIENT"; do
+            read -r name got want <<<"$check"
+            if [ -n "$want" ] && [ "$got" != "$want" ]; then
+              echo "::error::$name $got is installed, but the $LEG leg plans $want."
+              FAILED=1
+            fi
+          done
+          # And the installed client is the gem built here, not a release of the same version from rubygems.org:
+          # RubyGems keeps the .gem it installed from in its cache, and the installed lib/ is the checkout's, file for file.
+          if [ "$CLIENT_FROM" = checkout ]; then
+            if ! cmp -s "../logtail-rails-$CLIENT.gem" "$(installed client_gem)"; then
+              echo "::error::logtail-rails was not installed from the gem built here: $(installed client_gem) differs from logtail-rails-$CLIENT.gem."
+              FAILED=1
+            fi
+            if ! diff -r ../lib "$(installed client_dir)/lib" > ../out/client.diff; then
+              head -n 20 ../out/client.diff
+              echo "::error::The installed gem's lib/ in $(installed client_dir) differs from the checkout's lib/ directory."
+              FAILED=1
+            fi
+          fi
+          exit "$FAILED"
+
+      # Before a source is created: an app that cannot even boot with these versions needs no round trip. Without a
+      # source token the gem logs to STDOUT.
+      - name: "[Verify] The example app boots with these versions"
+        working-directory: example-project
+        run: |
+          if ! bin/rails runner 'puts "Rails #{Rails.version} booted the example app"' > ../out/boot.log 2>&1; then
+            cat ../out/boot.log
+            echo "::error::The example app does not boot: $(grep -m 1 -E 'Error|error' ../out/boot.log || tail -n 1 ../out/boot.log)"
+            exit 1
+          fi
+          cat ../out/boot.log
+
+      - name: "[Setup] Create a source"
+        id: source
+        uses: ./.github/actions/create-source
+        with:
+          api-token: ${{ secrets.TEST_TEAM_TELEMETRY_API }}
+          name: e2e-rails-gh${{ github.run_id }}a${{ github.run_attempt }}-${{ matrix.leg }}
+          platform: ruby
+
+      - name: "[Test] Run the example project"
+        env:
+          BETTER_STACK_SOURCE_TOKEN: ${{ steps.source.outputs.token }}
+          BETTER_STACK_INGESTING_HOST: ${{ steps.source.outputs.ingesting-host }}
+        run: bash e2e/example.sh run
+
+      - name: "[Setup] The rows Rails ${{ env.RAILS_INSTALLED }} logs"
+        run: |
+          # The rows marked since_rails that this Rails is too old for are left out.
+          jq --arg rails "$RAILS_INSTALLED" 'def minor: split(".")[0:2] | map(tonumber);
+            map(select((.since_rails // "0") | minor <= ($rails | minor)) | del(.since_rails))' e2e/expected.json > out/expected.json
+          echo "$(jq length out/expected.json) of $(jq length e2e/expected.json) rows in e2e/expected.json"
+
+      - name: "[Verify] Read the rows back"
+        uses: ./.github/actions/verify-logs
+        with:
+          connection-username: ${{ secrets.TEST_TEAM_CONNECTION_USERNAME }}
+          connection-password: ${{ secrets.TEST_TEAM_CONNECTION_PASSWORD }}
+          connect-host: ${{ steps.source.outputs.connect-host }}
+          collection: ${{ steps.source.outputs.collection }}
+          expected: out/expected.json
+
+      - name: "[Cleanup] Delete this job's source and stale ones of earlier runs"
+        if: ${{ always() }}
+        uses: ./.github/actions/cleanup-sources
+        with:
+          api-token: ${{ secrets.TEST_TEAM_TELEMETRY_API }}
+          prefix: e2e-rails-
+          id: ${{ steps.source.outputs.id }}
+
+      - name: "[Report] Job summary"
+        if: ${{ always() }}
+        run: |
+          if [ -f out/summary.md ]; then
+            { echo; cat out/summary.md; } >> "$GITHUB_STEP_SUMMARY"
+            # The Linear issue names the job and links the run, so it gets the versions, the read-back and the
+            # cleanup only when that left something behind. Without a read-back summary the notifier takes the
+            # job's ::error:: lines instead.
+            mkdir -p report
+            { cat out/versions.md; echo; cat out/summary.md; } > report/summary.md
+            if grep -q '❌' out/cleanup.md 2>/dev/null; then { echo; cat out/cleanup.md; } >> report/summary.md; fi
+          else
+            { echo; echo "❌ Stopped before the rows were read back, see the failed step."; } >> "$GITHUB_STEP_SUMMARY"
+          fi
+          if [ -f out/cleanup.md ]; then { echo; cat out/cleanup.md; } >> "$GITHUB_STEP_SUMMARY"; fi
+
+      - name: "[Report] Hand the summary to the Linear issue"
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: e2e-summary-${{ matrix.name }}
+          path: report/summary.md
+          if-no-files-found: ignore
+          retention-days: 7
+          # A re-run attempt uploads under the same name.
+          overwrite: true
+
+  notify-linear:
+    if: ${{ failure() && (github.ref == 'refs/heads/main' || github.event_name == 'schedule') }}
+    needs: [test]
+    # The notifier reads the failed jobs, their summary artifacts and their annotations.
+    permissions:
+      contents: read
+      actions: read
+      checks: read
+    uses: ./.github/workflows/notify_linear_failure.yml
+    with:
+      job_summaries: true
+    secrets: inherit