@uknows/setup 0.0.0-stage → 0.2.0

package/lib/contract-docs.mjs

@@ -0,0 +1,2736 @@
+// GENERATED from src/docs/install.ts by tools/sync-contract.mjs. Do not edit.
+// Change the docs file, then run: node tools/sync-contract.mjs
+/*
+ * UKNOWS install content: the single source for the /docs page and for
+ * /llms.txt (built by tools/build-installation-docs.mjs).
+ *
+ * Keep this file data only. It has no imports, so the docs build can load it
+ * with a plain TypeScript transpile.
+ *
+ * Copy rules: plain simple English, one instruction per sentence, active
+ * voice, sentence case, digits for numbers, UKNOWS brand only, no em dashes.
+ */
+
+/**
+ * The site, app and ingest addresses are build settings. A test build sets
+ * VITE_UKNOWS_SITE_URL (for example https://test.example.com),
+ * VITE_UKNOWS_APP_URL (for example https://app-test.example.com) and
+ * VITE_UKNOWS_INGEST_HOST (for example ingest-test.example.com). Without them,
+ * the production names below apply. Vite reads import.meta.env. The Node tools
+ * that build llms.txt and the setup CLI contract read process.env.
+ *
+ * The site has the docs, llms.txt and the key check. The app is where people
+ * sign in and see their data. The ingest address gets the data.
+ */
+export const DEFAULT_SITE_URL = 'https://uknows.my'
+export const DEFAULT_APP_URL = 'https://app.uknows.my'
+export const DEFAULT_INGEST_HOST = 'ingest.uknows.my'
+export const DEFAULT_DOCS_URL = `${DEFAULT_SITE_URL}/docs`
+
+// Written as import.meta.env exactly, so Vite and Vitest replace it. Node has no import.meta.env.
+export const BUILD_ENV = {}
+
+/** A build setting without spaces around it or a trailing slash, or the default. A bad value stops the build. */
+export function buildSetting(name, fallback, valid, env = BUILD_ENV) {
+  const raw = env[name]
+  const value = typeof raw === 'string' ? raw.trim().replace(/\/+$/, '') : ''
+  if (!value) return fallback
+  if (!valid.test(value)) throw new Error(`${name} is not a valid address: ${value}`)
+  return value
+}
+
+/** https with a host name, or http on this computer for a local test. No path. */
+export const ORIGIN = /^(?:https:\/\/[a-z0-9]([a-z0-9.-]*[a-z0-9])?|http:\/\/(?:localhost|127\.0\.0\.1))(?::\d{1,5})?$/i
+export const SITE_URL = buildSetting('VITE_UKNOWS_SITE_URL', DEFAULT_SITE_URL, ORIGIN)
+/**
+ * Where people sign in and see their data: the app. A test build sets
+ * VITE_UKNOWS_APP_URL (for example https://app-test.example.com), the same rule
+ * as the site address. Without it: the production app with the production
+ * site, or the site address itself with any other site (a copy on 1 address).
+ */
+export const APP_URL = buildSetting('VITE_UKNOWS_APP_URL', SITE_URL === DEFAULT_SITE_URL ? DEFAULT_APP_URL : SITE_URL, ORIGIN)
+/** A host name only, with an optional port. The apps always send over https. */
+export const HOST = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(?::\d{1,5})?$/i
+export const INGEST_HOST = buildSetting('VITE_UKNOWS_INGEST_HOST', DEFAULT_INGEST_HOST, HOST)
+/** Sign-in and the Station. */
+export const LIVE_URL = `${APP_URL}/live`
+/** The Connect page: open it with ?app=<the app name> to watch that app send its first data. */
+export const CONNECT_URL = `${APP_URL}/live/connect`
+/**
+ * The owner's yes to the scan and revoked-key P1 alerts: the same values the
+ * server reads (UKNOWS_ALERT_SCAN_P1 and UKNOWS_ALERT_REVOKED_KEY_P1). The
+ * release passes both. "on" turns a switch on; unset, empty or "off" leaves it
+ * off. Anything else stops the build. These comments go into the setup package
+ * through its contract sync, so they name no internal code or file.
+ */
+export function buildSwitch(name) {
+  const raw = BUILD_ENV[name]
+  const value = typeof raw === 'string' ? raw.trim().toLowerCase() : ''
+  if (value === 'on') return true
+  if (value === '' || value === 'off') return false
+  throw new Error(`${name} must be on or off`)
+}
+/** A scan is a P1 alert. Off: probing is a count for the last hour. */
+export const SCAN_ALERT = buildSwitch('VITE_UKNOWS_ALERT_SCAN_P1')
+/** Uploads with a revoked or retired key are a P1 alert. Off: they are a count, a fact. */
+export const REVOKED_KEY_ALERT = buildSwitch('VITE_UKNOWS_ALERT_REVOKED_KEY_P1')
+export const DOCS_URL = `${SITE_URL}/docs`
+export const LLMS_URL = DOCS_URL.replace(/\/docs$/, '/llms.txt')
+export const INGEST_ENDPOINT = `https://${INGEST_HOST}/otlp`
+/** The route that tells whether a key works. The site serves it, not the ingest host. */
+export const PING_URL = `${SITE_URL}/api/v1/ingest/ping`
+export const EXAMPLE_SERVICE = 'orders-api'
+/**
+ * The example names in the key scripts and the GitHub Actions steps. The setup tool replaces each one with the
+ * name that it finds in the deploy files of the repo, and says plainly when a name is still an example.
+ */
+export const EXAMPLE_NAMES = {
+  resourceGroup: 'orders-prod',
+  apps: `${EXAMPLE_SERVICE} payments`,
+  repo: 'my-org/orders-api',
+  org: 'my-org',
+  environment: 'production',
+}
+/**
+ * "See your data" and the last line of the setup tool say this. Applications lists an app a few minutes after its
+ * first data (Settings › Applications shows it go from Awaiting first data to Sending). The setup tool passes the app
+ * address of its run (UKNOWS_APP_URL, else the one of this build), so a run against a test copy never names the
+ * production app.
+ */
+export function openLive(appUrl) {
+  return `Sign in at ${appUrl.replace(/^https?:\/\//, '')} and go to Applications. Your app shows there a few minutes after it sends its first data.`
+}
+export const OPEN_LIVE = openLive(APP_URL)
+/** The titles of the 4 steps. Texts name a step by its title, never by its number. */
+export const STEP_TITLES = { key: 'Get your key', install: 'Install', secret: 'Set your key once', data: 'See your data' }
+
+/** The 5 plain settings. Commit them in the repo of each app. */
+export const SETTINGS = [
+  { name: 'OTEL_SERVICE_NAME', value: EXAMPLE_SERVICE, summary: 'The name of this app in UKNOWS. Use a different name for each app.' },
+  { name: 'OTEL_EXPORTER_OTLP_ENDPOINT', value: INGEST_ENDPOINT, summary: 'The UKNOWS address that gets your data.' },
+  { name: 'OTEL_EXPORTER_OTLP_PROTOCOL', value: 'http/protobuf', summary: 'Send data in the OTLP format over HTTPS.' },
+  { name: 'OTEL_METRICS_EXPORTER', value: 'none', summary: 'Send no metrics. UKNOWS takes traces and logs.', standardOnly: true },
+  { name: 'OTEL_LOGS_EXPORTER', value: 'otlp', summary: 'Send the logs of the app too. A log line written during a request carries the trace id of that request.', standardOnly: true },
+]
+
+/**
+ * The 3 settings for an app that already uses OpenTelemetry or Azure Monitor.
+ * They leave its metrics and logs where they go now.
+ */
+export const SHARED_SETTINGS = SETTINGS.filter((setting) => !setting.standardOnly)
+
+/** The 1 secret. Set it once for each environment on the platform, never in the repo. */
+export const SECRET = {
+  name: 'OTEL_EXPORTER_OTLP_HEADERS',
+  header: 'x-uknows-key',
+  placeholder: '<key>',
+  value: 'x-uknows-key=<key>',
+  summary: 'Set your key as a secret on your platform, once for each environment. Keep it out of your repo.',
+}
+
+export const SETTINGS_ENV = SETTINGS.map((setting) => `${setting.name}=${setting.value}`).join('\n')
+export const SECRET_ENV = `${SECRET.name}=${SECRET.value}`
+
+export function dockerEnv(extra = [], settings = SETTINGS) {
+  const pairs = [...settings.map((setting) => `${setting.name}=${setting.value}`), ...extra]
+  return `ENV ${pairs.join(' \\\n    ')}`
+}
+
+/** The ENV lines for the final stage of a Dockerfile. */
+export const SETTINGS_DOCKERFILE = dockerEnv()
+/** The ENV lines for an app that already uses OpenTelemetry or Azure Monitor. */
+export const SHARED_SETTINGS_DOCKERFILE = dockerEnv([], SHARED_SETTINGS)
+
+/**
+ * The 5 settings as an env file, for apps that do not run from a Dockerfile.
+ * It has no key, so it is safe to commit. SETTINGS_FILE_LOADERS shows how to
+ * load it.
+ */
+export const SETTINGS_FILE = {
+  path: 'otel.env',
+  language: 'sh',
+  summary: 'Use this file when your app does not start from a Dockerfile. It has no key, so it is safe to commit.',
+  content: SETTINGS_ENV,
+}
+
+/**
+ * The setup tool, npx @uknows/setup (packages/uknows-setup). A build with
+ * test addresses puts them in front of the command, so the test copy of the
+ * page gives a command that writes and checks the test addresses, and signs in
+ * at the app of that copy. Production gives the plain command.
+ */
+/** The version of the setup tool that these pages describe, the newest on npm. */
+export const SETUP_VERSION = '0.2.0'
+/**
+ * Setup 0.2.0 is the first version that knows the production addresses. An older one writes and checks addresses that
+ * UKNOWS no longer uses, so with it every setup command gives the production addresses in front too.
+ */
+export const PRODUCTION_NAMES_SINCE = '0.2.0'
+/** major, minor and patch of a version, as numbers */
+export function versionParts(version) {
+  return version.split('.').map((part) => Number.parseInt(part, 10) || 0)
+}
+/** True when version a is version b or later (major.minor.patch). */
+export function versionAtLeast(a, b) {
+  const [x, y] = [versionParts(a), versionParts(b)]
+  for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) > (y[i] ?? 0)
+  return true
+}
+/** The site and ingest addresses in front of a setup command: none for the production names, from 0.2.0 on. */
+export function frontAddresses(site, ingestHost, known) {
+  return [
+    ...(site === DEFAULT_SITE_URL && known ? [] : [`UKNOWS_SITE_URL=${site}`]),
+    ...(ingestHost === DEFAULT_INGEST_HOST && known ? [] : [`UKNOWS_INGEST_ENDPOINT=https://${ingestHost}/otlp`]),
+  ]
+}
+/**
+ * The key check needs only the site and the ingest address. Setup also signs in at the app. With a test address, it
+ * signs in only when UKNOWS_APP_URL names the app of that copy, so the command names the app then too. A version
+ * before 0.2.0 has no sign-in.
+ */
+export function commandAddresses(site, app, ingestHost, known) {
+  const front = frontAddresses(site, ingestHost, known)
+  return [...front, ...(known && (front.length || app !== DEFAULT_APP_URL) ? [`UKNOWS_APP_URL=${app}`] : [])]
+}
+export const NAMES_KNOWN = versionAtLeast(SETUP_VERSION, PRODUCTION_NAMES_SINCE)
+export const SETUP_ADDRESSES = frontAddresses(SITE_URL, INGEST_HOST, NAMES_KNOWN)
+export const SETUP_COMMAND_ADDRESSES = commandAddresses(SITE_URL, APP_URL, INGEST_HOST, NAMES_KNOWN)
+const setupCommand = (args = '')         => [...SETUP_COMMAND_ADDRESSES, `npx @uknows/setup${args}`].join(' ')
+/**
+ * The setup command of a build with these build settings, for a version of the setup tool: the command that the pages
+ * of that build give. The plain command with the production names from 0.2.0 on, and the addresses in front for a
+ * test copy or an older version. The static pages of the site take it at build time, so they give the same command.
+ */
+export function setupCommandFor(env, version = SETUP_VERSION) {
+  const site = buildSetting('VITE_UKNOWS_SITE_URL', DEFAULT_SITE_URL, ORIGIN, env)
+  const app = buildSetting('VITE_UKNOWS_APP_URL', site === DEFAULT_SITE_URL ? DEFAULT_APP_URL : site, ORIGIN, env)
+  const ingestHost = buildSetting('VITE_UKNOWS_INGEST_HOST', DEFAULT_INGEST_HOST, HOST, env)
+  return [...commandAddresses(site, app, ingestHost, versionAtLeast(version, PRODUCTION_NAMES_SINCE)), 'npx @uknows/setup'].join(' ')
+}
+
+/** The prompt line, exactly. bash only: zsh reads -p as a coprocess. */
+export const KEY_PROMPT = "read -rsp 'Paste your UKNOWS key: ' UKNOWS_KEY; echo"
+/** Stops the script, not the terminal, when no key was pasted. */
+export const KEY_EMPTY_GUARD = '[ -n "$UKNOWS_KEY" ] || { echo "No key entered. Nothing changed."; exit 1; }'
+
+/**
+ * The key check of the setup tool as 1 line, so it is safe to paste at once: read takes the key from the next line
+ * you type, never from a pasted line. The key goes to the check only, as a setting of that 1 command, and the shell
+ * forgets it at the end. Nothing stays exported. vars: the test addresses of this run, if any.
+ */
+export function keyCheckLine(vars = SETUP_ADDRESSES) {
+  return `${KEY_PROMPT}; ${[...vars, `${SECRET.name}="${SECRET.header}=$UKNOWS_KEY"`, 'npx @uknows/setup check'].join(' ')}; unset UKNOWS_KEY`
+}
+export const KEY_CHECK_LINE = keyCheckLine()
+
+/** Said wherever the docs say that no code from your project runs. */
+export const RESOLVER_NOTE = "uv lock, poetry lock and dotnet restore can run your own project's build code to read its metadata."
+
+/**
+ * What the setup tool says when it runs the resolver of a project (uv lock,
+ * poetry lock, dotnet restore), when it cannot, and when it picks older
+ * OpenTelemetry versions for Python. The tool fills in each {name}. The page
+ * does not show these.
+ */
+export const RESOLVE = {
+  /** Plan sentence for a lock refresh. */
+  update: 'Update {lock} with {command}.',
+  /** RESOLVER_NOTE for the lock commands of 1 run only. The tool fills in {commands}, such as "dotnet restore". */
+  buildCode: "{commands} can run your own project's build code to read its metadata.",
+  /** What a lock refresh writes, said in the plan before it runs. */
+  writes: '{command} writes only {files} in your repo.',
+  restoreWrites: 'dotnet restore updates {files}. It also downloads the packages to the NuGet folder on this computer, and it writes the obj/ folders of the projects. remove gives back {files}, not the obj/ folders.',
+  again: 'Then run npx @uknows/setup again.',
+  tool: {
+    title: 'Install {tool}{version}, then run setup again',
+    why: '{lock} needs {tool} to add {packages}.',
+    missing: 'This tool did not find {tool} on this computer, so it changed nothing.',
+    version: '{file} needs {tool} {need}. This computer has {tool} {have}, so this tool changed nothing.',
+    image: '{file} line {line} uses {tool} {need} in the image. The {tool} on this computer must be the same version, so the image reads the lock it writes. This computer has {tool} {have}, so this tool changed nothing.',
+    install: 'Install {tool}{version} on this computer.',
+  },
+  outside: {
+    title: 'Run setup from the repo root',
+    lines: [
+      '{lock} is above this folder. {command} must run in {dir}, so this tool changed nothing here.',
+      'Run npx @uknows/setup in the repo root without --path, and pick this service.',
+    ],
+  },
+  failed: {
+    title: '{tool} found no versions that fit',
+    lines: [
+      '{command} found no versions of the packages that fit the limits of your app. This tool put every file back. Nothing changed.',
+      'It names {package}. Change or remove the limit on it, then run npx @uknows/setup again.',
+    ],
+  },
+  python: {
+    /** Why the plan uses an older OpenTelemetry set than the newest. */
+    olderPython: 'The image uses Python {python}. OpenTelemetry {newest} needs Python {need} or later, so this tool uses OpenTelemetry {core} and {contrib}.',
+    olderLimit: '{file} line {line} has {value}. So this tool uses OpenTelemetry {core} and {contrib}, the newest versions that fit.',
+    /** For uv and Poetry: the resolver picks the versions, and the set decides which instrumentation packages exist. */
+    floorPython: 'The project supports Python {python}. OpenTelemetry {newest} needs Python {need} or later, so this tool adds only the packages that OpenTelemetry {contrib} has. {tool} picks the versions.',
+    floorLimit: '{file} line {line} has {value}. So this tool adds only the packages that OpenTelemetry {contrib} has. {tool} picks the versions.',
+    noSet: {
+      title: 'Pick the OpenTelemetry versions by hand',
+      lines: [
+        '{file} line {line} has {value}. No OpenTelemetry versions that this tool knows fit it, so this tool changed nothing.',
+        'Add opentelemetry-distro, opentelemetry-exporter-otlp-proto-http and the instrumentation packages at versions that fit. pip install, then pip freeze, shows the versions.',
+      ],
+    },
+    procfile: {
+      title: 'Start the app with opentelemetry-instrument',
+      lines: [
+        '{file} starts the app on its web line. This tool does not change a Procfile, because the hosts it supports do not read it.',
+        'If your platform starts the app from {file}, change the web line to the line below.',
+      ],
+    },
+  },
+  dotnet: {
+    sdk: {
+      title: 'Install the .NET {need} SDK, then run setup again',
+      lines: [
+        '{lock} needs dotnet restore to add the packages.',
+        'This computer has no .NET SDK {need} or later, so this tool changed nothing. It found: {have}.',
+        'Install the .NET {need} SDK on this computer.',
+      ],
+    },
+    offline: {
+      title: 'Add the packages to the source that your build restores from',
+      lines: [
+        '{file} line {line} restores the packages with --network=none, so new packages cannot arrive in the image. This tool changed nothing.',
+        'Add these packages to the package source that your build uses. Then add them to {csproj}, update packages.lock.json and start the app with instrument.sh, as below.',
+      ],
+    },
+    runtimes: {
+      title: 'Update packages.lock.json by hand',
+      lines: [
+        '{file} line {line} restores for {value}. This tool refreshes the lock for 1 known runtime only, so it changed nothing.',
+        'Add the packages below. Run dotnet restore --force-evaluate with the runtime options of your build. Commit packages.lock.json. Then start the app with instrument.sh.',
+      ],
+      /** Instead of the first line, when packages.lock.json has packages for more than 1 runtime. */
+      lock: '{lock} has packages for {value}. This tool refreshes the lock for 1 runtime only, so it changed nothing.',
+    },
+    /**
+     * Another project references the app project, such as a test project, and has its own packages.lock.json. That
+     * lock lists the packages of the app too, so a locked restore of the solution fails (NU1004) unless it is updated
+     * as well. The tool fills in {lock}, {project}, {csproj} and {command}.
+     */
+    dependent: '{lock} also locks the packages of {csproj}, because {project} references it. This tool updates it with {command}.',
+    /** The plan sentence for that refresh. */
+    dependentUpdate: 'Update {lock} with {command}, because {project} references {csproj}.',
+    /** That project is above the --path folder, so this tool cannot write its lock. */
+    dependentOutside: {
+      title: 'Run setup from the repo root',
+      lines: [
+        '{project} references {csproj} and has its own {lock}. It is above this folder, so this tool cannot update that lock, and it changed nothing.',
+        'Run npx @uknows/setup in the repo root without --path, and pick this service.',
+      ],
+    },
+    /**
+     * The publish names a runtime for another C library than the final image: glibc (linux-x64) on Alpine, or musl
+     * (linux-musl-x64) on a glibc image. Then the native profiler of OpenTelemetry does not load. Without -r, the publish
+     * holds the native files of every platform and instrument.sh picks the right one, so that needs no step. Advice,
+     * not a required step: the startup hook still traces the requests. The tool fills in {where}, {rid}, {libc},
+     * {image}, {imageLibc} and {want}.
+     */
+    libc: {
+      title: 'Publish for the C library of the final image',
+      lines: [
+        '{where} publishes with -r {rid}, for {libc}. The final image {image} uses {imageLibc}.',
+        'So the native part of OpenTelemetry does not load. Requests still show in UKNOWS, but libraries that need the native part, such as StackExchange.Redis and Microsoft.Data.Sqlite, get no spans.',
+        'Publish with -r {want}. If the project has a packages.lock.json, add {want} to its RuntimeIdentifiers and run dotnet restore --force-evaluate first, so the lock has the packages for it.',
+      ],
+    },
+    /** A note when the tool runs dotnet restore and no .dockerignore keeps obj/ out of the image. */
+    dockerignore: 'dotnet restore writes obj/ folders in your repo. A docker build on this computer copies them into the image and the build can fail. Add bin/ and obj/ to .dockerignore.',
+    assets: {
+      title: 'Run setup again for {package}',
+      lines: [
+        '{assets} shows that the app uses {library} {version} through {via}. The build also needs {package} {need}. This tool put every file back. Nothing changed.',
+        'Run npx @uknows/setup again. It reads that file now and adds {package}.',
+      ],
+    },
+  },
+  /**
+   * npm on this computer writes the lock that npm ci in the image reads. A newer npm than the one in the image can
+   * write a lock that the older npm refuses. The tool fills in {file}, {line}, {image}, {need} and {have}.
+   */
+  npm: {
+    title: 'Use npm {need} on this computer, then run setup again',
+    lines: [
+      '{file} line {line} builds with {image}, which comes with npm {need}. This computer has npm {have}. A newer npm can write a package-lock.json that npm ci in the image refuses, so this tool changed nothing.',
+      'Install npm {need} on this computer with npm install -g npm@{need}, or use the Node.js version of the image, which comes with npm {need}.',
+    ],
+  },
+}
+
+/**
+ * The Windows tip for a bash terminal. It is the same everywhere, and the welcome email of the product says the same.
+ * Only the steps of a cloud name its own shell too: Azure Cloud Shell in the Azure steps, AWS CloudShell in the AWS steps.
+ */
+export const WINDOWS_TIP = 'On Windows, use WSL.'
+export const MACOS_TIP = 'On macOS, type bash first.'
+
+/**
+ * What the setup tool needs on your computer. The tool updates the lock files of your app with the tools of your app,
+ * so it needs them too. The page and the --help of the tool show these lines.
+ */
+export const SETUP_NEEDS = [
+  'Node.js 18 or later, and git.',
+  'For a Node.js app: its package tool, npm, pnpm or yarn. npm must not be newer than the npm of your Node.js image.',
+  'For a Python app with uv or Poetry: that tool, at the version that your Dockerfile uses.',
+  'For a .NET app with packages.lock.json: the .NET SDK of global.json.',
+  `A bash terminal for the key steps. ${MACOS_TIP} ${WINDOWS_TIP}`,
+]
+
+/**
+ * Setup runs once on a computer, never in a pipeline. The /docs page and
+ * llms.txt show this section, and the setup tool prints it when it stops in a
+ * pipeline (exit 2).
+ */
+export const CI_CD = {
+  id: 'ci-cd',
+  title: 'CI/CD and pipelines',
+  summary: 'Run setup once, on your computer, in your repo. Do not run it in your pipeline.',
+  steps: [
+    'Run npx @uknows/setup in your repo. Review the diff. Commit the change and open a pull request.',
+    'Your pipeline builds and deploys the change as usual. It needs no UKNOWS step to build.',
+    'Store your key in the secret store of your pipeline, once for each environment. In GitHub Actions, use a secret named UKNOWS_KEY that holds the key only.',
+    'In your deploy job, check that the secret is not empty. Set the key on your app before the deploy that uses it.',
+    'If your deploy replaces all environment variables, add the key to that list. This includes --replace-env-vars, the environmentVariables of the deploy action, and Bicep or Terraform templates. Otherwise each deploy removes the key.',
+  ],
+  check: 'Setup stops when it runs in a pipeline. To check that a repo is set up, run the command below in the pipeline. It changes nothing. The repo is set up when the JSON says "status": "nothing-to-change" and "exitCode": 0, and the command fails otherwise. In a monorepo, it checks the services that setup set up. The command uses jq, which GitHub Actions and Azure Pipelines runners have.',
+  snippet: { caption: 'Check in your pipeline that the repo is set up', language: 'bash', code: `${setupCommand(' --dry-run --json')} | jq -e '.status == "nothing-to-change" and .exitCode == 0'` },
+  /** What the setup tool prints when it stops in a pipeline: what happened, then 1 next step. It fills in {docs}. */
+  stop: 'This runs in a pipeline, so the tool changes nothing.',
+  next: 'Run npx @uknows/setup once on your computer and commit the change. To check in a pipeline that a repo is set up, see {docs}.',
+  allowCi: 'A bot or an AI agent that opens a pull request can add --allow-ci.',
+}
+
+/**
+ * What the setup tool prints when a run has nothing to change. A repo counts as set up ("nothing-to-change", exit 0)
+ * when .uknows/setup.json lists every service, or when no required step is left. Otherwise the status is
+ * "needs-steps" with exit 3: the tool could plan nothing, and the steps are yours. The tool fills in {count} and
+ * {manifest}. The page does not show these.
+ */
+export const SETUP_STATUS = {
+  done: 'Already set up. Nothing to change.',
+  doneSteps: 'Steps that this tool cannot check in your repo. Do them if you have not done them yet:',
+  steps: 'Nothing for this tool to change. The steps below are yours.',
+  recorded: 'Planning the {count} that {manifest} lists. To plan other services, use --all or --path <folder>.',
+  /** Set up earlier, but steps in the repo that this tool can check are not done yet ("steps-left", exit 3). */
+  stepsLeft: 'Set up earlier, but {count} in your repo {verb} not done yet. This tool checks {pronoun} each time it runs:',
+  /** Nothing to change, but the services are not in the record yet: the run writes only the record. */
+  record: 'This run writes only {manifest}, so the pipeline check and remove know this service. It changes no file of your app.',
+}
+
+/**
+ * The last line of a setup run. It fills in {count} and {open}. "data" only when the repo needs nothing more from you
+ * and the key check did not fail. {open} is openLive with the app address of the run, or "testCopy" when the run
+ * goes to a test copy of UKNOWS and does not know its app address.
+ */
+export const SETUP_NEXT = {
+  data: 'Next: commit, open a pull request and deploy as usual. {open}',
+  testCopy: 'Then sign in to your test copy of UKNOWS. To see its address here, set UKNOWS_APP_URL to the address of its app.',
+  steps: 'Next: do the {count} above first. Then commit, open a pull request and deploy as usual.',
+  rejected: 'Next: fix the key first. An Admin or an Engineer of your workspace can show the key again, or create a new one, in Settings › Keys. Then check it with this 1 line in bash:',
+  network: 'Next: check the network as the lines above say. You can commit the change already. Then check the key again with this 1 line in bash:',
+  skipped: 'To check your key, run this 1 line in bash and paste your key. Nothing stays set in your terminal:',
+}
+
+const hostOf = (url        )         => url.replace(/^https?:\/\//, '')
+/** The store of the UKNOWS agent images (the agent channel): the host of DEFAULT_AGENT_REGISTRY in the setup tool. */
+export const AGENT_REGISTRY_HOST = 'registry.uknows.my'
+
+/**
+ * Every address that UKNOWS uses, and who connects to it. OpenTelemetry for Node.js asks the metadata addresses of
+ * the clouds when the app starts (169.254.169.254 on port 80, and the Kubernetes API on EKS), unless
+ * OTEL_NODE_RESOURCE_DETECTORS leaves those detectors out. Each cloud detector (alibaba, aws, azure, gcp) also asks a
+ * metadata address, so the Node.js steps keep only the local ones. Checked on 18 Oct 2026.
+ */
+export const NETWORK = {
+  host: INGEST_HOST,
+  port: 443,
+  text: `Allow outbound HTTPS from your apps to ${INGEST_HOST} on port 443. Your apps send data to UKNOWS. UKNOWS never connects to your apps.`,
+  hosts: [
+    { host: INGEST_HOST, who: 'Your apps send their traces and logs here, over HTTPS on port 443.' },
+    { host: hostOf(APP_URL), who: 'Your team signs in here in the browser. The setup tool asks here for its sign-in link, and gets the key here after you approve.' },
+    { host: hostOf(SITE_URL), who: 'The docs are here. The setup tool asks here which workspace and environment a key sends to.' },
+    { host: AGENT_REGISTRY_HOST, who: 'The Docker builds of Java, .NET and Node.js apps copy the UKNOWS agent from here, over HTTPS on port 443, with no sign-in.' },
+    { host: 'registry.npmjs.org, pypi.org, files.pythonhosted.org and api.nuget.org', who: 'npm, uv, Poetry and dotnet restore download packages from their registry when the setup tool updates the lock file of your app, on your computer.' },
+  ],
+  node: 'A Node.js app that you set up with these steps asks no cloud metadata address when it starts. OTEL_NODE_RESOURCE_DETECTORS keeps only the detectors that read the app and its host. Without it, OpenTelemetry for Node.js asks the metadata addresses of the clouds, such as 169.254.169.254 on port 80.',
+}
+
+/** The settings that a stack commits: its own list, or the 5. */
+export function stackSettings(stack) {
+  return stack.settings ?? SETTINGS
+}
+
+/** Extra steps that the page can show folded, under the title. */
+
+/**
+ * The upstream OpenTelemetry Java agent, pinned. Checksum from the release
+ * checksums.txt. The OpenTelemetry Operator image holds the same jar at
+ * /javaagent.jar. The digest is the image index, for every platform.
+ */
+export const JAVA_AGENT = {
+  version: '2.32.0',
+  file: 'opentelemetry-javaagent.jar',
+  url: 'https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.32.0/opentelemetry-javaagent.jar',
+  sha256: 'f787eb6c7f3d18e69a431e108a15278d25ee37f83d68b678f621e063f3988f82',
+  image: 'ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.32.0',
+  digest: 'sha256:9dad1c6e3e2ecee48fc164a19bcfde703510bee972c8cb421689fde89b5f89e9',
+  /** Where the jar is in the image. */
+  imagePath: '/javaagent.jar',
+}
+
+/** The Dockerfile line that copies the agent from the pinned image. It needs no BuildKit feature. */
+export const JAVA_COPY_LINE = `COPY --from=${JAVA_AGENT.image}@${JAVA_AGENT.digest} ${JAVA_AGENT.imagePath} /otel/${JAVA_AGENT.file}`
+
+/** For networks that block ghcr.io: a build stage that downloads the agent from GitHub and checks it. */
+export const JAVA_AGENT_STAGE = [
+  '# A build stage, before your final stage',
+  'FROM alpine:3.20 AS otel-agent',
+  `RUN wget -q -O /${JAVA_AGENT.file} ${JAVA_AGENT.url} \\`,
+  ` && echo "${JAVA_AGENT.sha256}  /${JAVA_AGENT.file}" | sha256sum -c -`,
+  '',
+  '# Final stage: use this line instead of the COPY line from ghcr.io',
+  `COPY --from=otel-agent /${JAVA_AGENT.file} /otel/${JAVA_AGENT.file}`,
+].join('\n')
+
+export const NODE_REGISTER = '@opentelemetry/auto-instrumentations-node/register'
+/** For ES modules: the loader hook gives each request its route. No space after = so 1 value holds both options. */
+export const NODE_ESM_OPTIONS = `--experimental-loader=@opentelemetry/instrumentation/hook.mjs --import=${NODE_REGISTER}`
+
+/**
+ * A small start file for Node.js. It starts OpenTelemetry like the upstream
+ * register. On SIGTERM it sends the last data, then stops the app as Node
+ * does, unless the app has its own SIGTERM handler. A missing package only
+ * prints a warning. The setup tool writes the same file.
+ *
+ * As PID 1 in a container (CMD ["node", ...] without an init), Linux ignores
+ * a signal that has no handler, so the SIGTERM that the file sends again does
+ * not stop node. Then the file exits with code 143, the code of SIGTERM.
+ * Checked with docker stop on 18 Oct 2026: 10 seconds and a kill before, under
+ * 1 second after.
+ */
+export const NODE_REGISTER_FILE = {
+  path: 'uknows-otel.cjs',
+  language: 'javascript',
+  summary: 'Add this file next to package.json.',
+  content: `'use strict'
+// Added for UKNOWS. Starts standard OpenTelemetry for Node.js.
+// OTEL_SDK_DISABLED=true turns it off. On SIGTERM it sends the last data, then
+// stops the app as Node does, unless the app has its own SIGTERM handler.
+if (String(process.env.OTEL_SDK_DISABLED || '').trim().toLowerCase() !== 'true') {
+  const before = new Set(process.listeners('SIGTERM'))
+  try {
+    require(require.resolve('${NODE_REGISTER}', { paths: [__dirname, process.cwd()] }))
+  } catch (error) {
+    console.warn(\`OpenTelemetry did not start: \${error.message}\`)
+  }
+  for (const listener of process.listeners('SIGTERM')) {
+    if (before.has(listener)) continue
+    process.removeListener('SIGTERM', listener)
+    process.on('SIGTERM', function stopAfterFlush(signal) {
+      const alone = process.listenerCount('SIGTERM') === 1
+      let stopping = false
+      const stop = () => {
+        if (!alone || stopping) return
+        stopping = true
+        process.removeListener('SIGTERM', stopAfterFlush)
+        process.kill(process.pid, 'SIGTERM')
+        // As PID 1 in a container, Linux ignores that signal. Then exit with the code of SIGTERM.
+        setTimeout(() => process.exit(143), 100)
+      }
+      setTimeout(stop, 5000).unref()
+      Promise.resolve(listener(signal)).then(stop, stop)
+    })
+  }
+}`,
+}
+/** Where the setup tool and the steps put the start file in an image. */
+export const NODE_REGISTER_PATH = `/app/${NODE_REGISTER_FILE.path}`
+
+/**
+ * What the setup tool says about the start file. It fills in {file}, {dockerfile}, {ignore} and {dockerfiles}. When
+ * it cannot be sure that the file reaches the running app, it loads the register line instead and says why. The page does not show these.
+ */
+export const NODE_START_FILE = {
+  add: 'Add {file}. It starts OpenTelemetry and stops the app cleanly on SIGTERM.',
+  copy: 'Copy the start file into the image.',
+  keep: '{file} is there already. This tool keeps it as it is.',
+  noContext: 'This tool cannot tell the build context of {dockerfile} from its COPY lines.',
+  noWorkdir: 'The final stage of {dockerfile} has no WORKDIR with a full path, so this tool does not know where the app is in the image.',
+  outside: '{file} is outside the build context of {dockerfile}.',
+  ignored: '{ignore} leaves {file} out of the build context.',
+  gitignored: '.gitignore leaves {file} out of git, so a fresh checkout and the build in your pipeline do not have it.',
+  dockerfiles: 'This tool did not pick a Dockerfile for this service. It saw {dockerfiles}. An image built from them would not have {file}.',
+  fallback: 'So this tool loads the OpenTelemetry register line instead of the start file. The app works, but it does not stop on SIGTERM by itself. Docker, Kubernetes and systemd then wait for their time limit and kill it. To stop cleanly, add the start file yourself.',
+}
+
+/** .NET writes its own OpenTelemetry log files. The default folder is not writable on macOS or as a user that is not root. */
+export const DOTNET_LOG_DIRECTORY = 'OTEL_DOTNET_AUTO_LOG_DIRECTORY=/tmp/otel-dotnet'
+
+/**
+ * .NET sends an ILogger line as its message template, such as "Served order {Id}", with the values beside it. UKNOWS
+ * keeps the text of a log line and not those values (DATA_FACTS logs), so the text must be the formatted message.
+ */
+export const DOTNET_LOGS_MESSAGE = 'OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE=true'
+
+/**
+ * Node.js: only the resource detectors that read the app and its host (NETWORK.node). env goes last, so a value in
+ * OTEL_RESOURCE_ATTRIBUTES wins over a detected one.
+ */
+export const NODE_DETECTORS = 'OTEL_NODE_RESOURCE_DETECTORS=host,os,serviceinstance,container,env'
+
+/**
+ * Python: the host name and the operating system of the app, as Node.js sends them. Python sends no host name without
+ * it, so UKNOWS could not tell which revision or pod of the app the data comes from. Neither detector asks a network
+ * address. OTEL_RESOURCE_ATTRIBUTES still wins over a detected value.
+ */
+export const PYTHON_DETECTORS = 'OTEL_EXPERIMENTAL_RESOURCE_DETECTORS=host,os'
+
+/**
+ * Python: the OpenTelemetry logging package stays off the root logger. On the root logger it changes what the app
+ * prints: Python's last-resort output, logging.warning() before any setup and Flask's own handler all stop (install
+ * proof, 22 Oct 2026). The UKNOWS log bridge sends the log records instead.
+ */
+export const PYTHON_LOG_HANDLER_OFF = 'OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=false'
+
+/** Where the UKNOWS log bridge for Python goes: a folder next to the dependency file, copied into the image. */
+export const PYTHON_BRIDGE_DIR = 'uknows-otel'
+export const PYTHON_BRIDGE_IMAGE = '/opt/uknows-otel'
+
+/**
+ * The UKNOWS log bridge for Python. opentelemetry-instrument finds its entry point on PYTHONPATH and calls install()
+ * after it starts OpenTelemetry. The bridge sends each log record that the app's own logging handles, without a
+ * handler on the root logger, so the app prints exactly what it printed before.
+ */
+export const PYTHON_LOG_BRIDGE = {
+  dir: PYTHON_BRIDGE_DIR,
+  image: PYTHON_BRIDGE_IMAGE,
+  files: [
+    {
+      path: 'uknows_logs.py',
+      language: 'python',
+      summary: 'The bridge.',
+      content: `# Added for UKNOWS. Sends the log records of this app to UKNOWS with OpenTelemetry, and changes nothing in what the
+# app prints: no handler goes on the root logger, so Python's last-resort output, logging.basicConfig, Flask's own
+# handler and every check for handlers work as before. opentelemetry-instrument calls install() after it starts
+# OpenTelemetry. OTEL_LOGS_EXPORTER=none turns it off.
+import logging
+import os
+
+def install():
+    try:
+        _install()
+    except Exception:  # never stop the app, never print in its output
+        pass
+
+def _install():
+    if "otlp" not in [name.strip() for name in os.environ.get("OTEL_LOGS_EXPORTER", "").split(",")]:
+        return
+    if getattr(logging.Logger.callHandlers, "_uknows", False):
+        return
+    from opentelemetry._logs import get_logger_provider
+
+    try:
+        from opentelemetry.instrumentation.logging import LoggingInstrumentor
+        from opentelemetry.instrumentation.logging.handler import LoggingHandler
+    except ImportError:
+        return
+    # The logging package puts its handler on the root logger, which changes what the app prints. Take it off.
+    root = logging.getLogger()
+    other = getattr(LoggingInstrumentor, "_logging_handler", None)
+    if other is not None and other in root.handlers:
+        root.removeHandler(other)
+    handler = LoggingHandler(logger_provider=get_logger_provider())
+    handler.handleError = lambda record: None
+    call_handlers = logging.Logger.callHandlers
+
+    def callHandlers(self, record):
+        call_handlers(self, record)
+        if record.name.startswith("opentelemetry"):
+            return
+        try:
+            handler.handle(record)
+        except Exception:
+            pass
+
+    callHandlers._uknows = True
+    logging.Logger.callHandlers = callHandlers`,
+    },
+    {
+      path: 'uknows_logs-1.0.dist-info/METADATA',
+      language: 'text',
+      summary: 'Its name, so Python finds the entry point.',
+      content: `Metadata-Version: 2.1
+Name: uknows-logs
+Version: 1.0
+Summary: Added for UKNOWS. Sends the log records of the app without changing what the app prints.`,
+    },
+    {
+      path: 'uknows_logs-1.0.dist-info/entry_points.txt',
+      language: 'ini',
+      summary: 'The entry point that opentelemetry-instrument calls.',
+      content: `[opentelemetry_post_instrument]
+uknows_logs = uknows_logs:install`,
+    },
+  ],
+}
+
+/** PYTHONPATH with the bridge folder of the image after the value that the image has, if any. */
+export const PYTHON_BRIDGE_PATH = 'PYTHONPATH=${PYTHONPATH:+${PYTHONPATH}:}' + PYTHON_BRIDGE_IMAGE
+
+/** The Dockerfile line that copies the bridge folder into the image. */
+export const PYTHON_BRIDGE_COPY = `COPY ${PYTHON_BRIDGE_DIR} ${PYTHON_BRIDGE_IMAGE}`
+
+export const GO_INIT = `package main
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"strings"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// setupOTel sends traces to the address in the OTEL_ settings.
+// Call the returned function when the app stops. It sends the last data.
+func setupOTel(ctx context.Context) (func(context.Context) error, error) {
+	if os.Getenv("OTEL_SDK_DISABLED") == "true" {
+		return func(context.Context) error { return nil }, nil
+	}
+	exporter, err := otlptracehttp.New(ctx)
+	if err != nil {
+		return nil, err
+	}
+	// The OTEL_ settings and the host name: UKNOWS tells the instances of the app apart by the host name.
+	// A detector that fails leaves only its own part out.
+	res, _ := resource.New(ctx, resource.WithFromEnv(), resource.WithTelemetrySDK(), resource.WithHost())
+	provider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter), sdktrace.WithResource(res))
+	otel.SetTracerProvider(provider)
+	otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
+		propagation.TraceContext{}, propagation.Baggage{},
+	))
+	return provider.Shutdown, nil
+}
+
+// withRoute adds the route of each request, such as /orders/{id}, to its
+// trace, after the net/http ServeMux picks the route. Without it, UKNOWS
+// shows all requests of the app as 1 endpoint.
+func withRoute(mux http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mux.ServeHTTP(w, r)
+		// r.Pattern is, for example, "GET /orders/{id}". The route starts at the first /.
+		if i := strings.IndexByte(r.Pattern, '/'); i >= 0 {
+			setRoute(r, r.Pattern[i:])
+		}
+	})
+}
+
+// setRoute adds a route to the trace of the request and names the trace
+// after it, for example GET /orders/{id}.
+func setRoute(r *http.Request, route string) {
+	if route != "" {
+		span := trace.SpanFromContext(r.Context())
+		span.SetName(r.Method + " " + route)
+		span.SetAttributes(attribute.String("http.route", route))
+	}
+}`
+
+/** The part of main.go before the router lines. */
+export const GO_MAIN_HEAD = `// Imports for this code: "context", "errors", "log", "net/http",
+// "os", "os/signal", "syscall" and "time".
+
+// 1. Start OpenTelemetry at the start of main.
+shutdown, err := setupOTel(context.Background())
+if err != nil {
+	log.Fatal(err)
+}`
+
+/** The middleware of each router. Each one sets handler. echoOlder is Echo v4 with Go below 1.25. */
+export const GO_ROUTERS = {
+  nethttp: `// net/http: wrap the ServeMux. withRoute is in otel.go.
+// import "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
+handler = otelhttp.NewHandler(withRoute(mux), "http.server")`,
+  chi: `// chi: add this middleware before your routes. Then wrap the router.
+// import "github.com/go-chi/chi/v5" and otelhttp
+router.Use(func(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		next.ServeHTTP(w, r)
+		setRoute(r, chi.RouteContext(r.Context()).RoutePattern())
+	})
+})
+handler = otelhttp.NewHandler(router, "http.server")`,
+  gin: `// Gin: add the middleware. Then use the router as the handler.
+// import "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
+router.Use(otelgin.Middleware(os.Getenv("OTEL_SERVICE_NAME")))
+handler = router`,
+  echo: `// Echo v4: add the middleware. Then use e as the handler.
+// import echootel "github.com/labstack/echo-otel/v4"
+e.Use(echootel.NewMiddleware(""))
+handler = e`,
+  echoOlder: `// Echo v4: add the middleware. Then use e as the handler.
+// import "go.opentelemetry.io/contrib/instrumentation/github.com/labstack/echo/otelecho"
+e.Use(otelecho.Middleware(os.Getenv("OTEL_SERVICE_NAME")))
+handler = e`,
+}
+
+/**
+ * main.go with the middleware of the given routers and the address the server listens on. The page shows every
+ * router and :8080. The setup tool shows the router it found and the port of the app.
+ */
+export function goMain(routers = ['nethttp', 'chi', 'gin', 'echo'], address = ':8080') {
+  const keep = routers.length === 1 ? '' : ' Keep only the lines for your router.'
+  return `${GO_MAIN_HEAD}
+
+// 2. Add the middleware for your router.${keep}
+var handler http.Handler
+
+${routers.map((router) => GO_ROUTERS[router]).join('\n\n')}
+
+// 3. Run the server. On Ctrl+C or SIGTERM, stop the server.
+ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+defer stop()
+srv := &http.Server{Addr: "${address}", Handler: handler}
+serveErr := make(chan error, 1)
+go func() { serveErr <- srv.ListenAndServe() }()
+select {
+case err = <-serveErr:
+case <-ctx.Done():
+	stopCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	err = srv.Shutdown(stopCtx)
+	cancel()
+}
+
+// 4. Send the last data before the app exits.
+flushCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+_ = shutdown(flushCtx)
+cancel()
+if err != nil && !errors.Is(err, http.ErrServerClosed) {
+	log.Fatal(err)
+}`
+}
+
+export const GO_MAIN = goMain()
+
+/**
+ * OpenTelemetry Go for an app that builds with an older Go. For each Go version: the newest OpenTelemetry Go
+ * release whose go.mod allows it, and the contrib release made with it.
+ * Checked on proxy.golang.org on 18 Oct 2026, and built with each Go in Docker. otel.go needs Go 1.23 or later,
+ * because it reads http.Request.Pattern.
+ */
+export const GO_RELEASES = [
+  { go: '1.25', otel: 'v1.46.0', contrib: 'v0.71.0' },
+  { go: '1.24', otel: 'v1.41.0', contrib: 'v0.66.0' },
+  { go: '1.23', otel: 'v1.38.0', contrib: 'v0.63.0' },
+]
+
+/** echo-otel needs Go 1.25. With an older Go, Echo v4 uses the older contrib middleware otelecho. */
+export const GO_ECHO = { module: 'github.com/labstack/echo-otel/v4', go: '1.25', older: 'go.opentelemetry.io/contrib/instrumentation/github.com/labstack/echo/otelecho' }
+export const GO_GORM = 'gorm.io/plugin/opentelemetry'
+export const GO_REDIS = 'github.com/redis/go-redis/extra/redisotel/v9'
+const goOlder = (release           ) => Number(release.go.split('.')[1]) < Number(GO_ECHO.go.split('.')[1])
+
+/** The go get lines. Without a release, go get takes the newest modules. With one, each module gets its version. */
+export function goInstall(release) {
+  const otel = (module        ) => (release ? `${module}@${release.otel}` : module)
+  const contrib = (module        ) => (release ? `${module}@${release.contrib}` : module)
+  const echo = !release ? GO_ECHO.module : goOlder(release) ? contrib(GO_ECHO.older) : `${GO_ECHO.module}@v4.0.0`
+  return [
+    `go get ${otel('go.opentelemetry.io/otel')} \\`,
+    `  ${otel('go.opentelemetry.io/otel/sdk')} \\`,
+    `  ${otel('go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp')} \\`,
+    `  ${contrib('go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp')}`,
+    '# Gin only',
+    `go get ${contrib('go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin')}`,
+    '# Echo v4 only',
+    `go get ${echo}`,
+  ].join('\n')
+}
+
+/** The go-redis version of go.mod, for the redisotel line of the docs. The setup tool prints the version itself. */
+export const GO_REDIS_VERSION = "$(go list -m -f '{{.Version}}' github.com/redis/go-redis/v9)"
+
+/**
+ * Spans for each database query and each Redis command. The setup tool prints the one that the app uses, at a
+ * version that does not raise the gorm or go-redis of go.mod. Checked on proxy.golang.org on 18 Oct 2026, with go get,
+ * go mod tidy and go build in golang:1.24-alpine: the plugin raises gorm to the gorm in its module graph.
+ */
+export const GO_LIBRARIES = {
+  gorm: {
+    module: GO_GORM,
+    /** Newest first: each plugin version, the lowest gorm it works with (it raises gorm to that), and its Go. */
+    versions: [
+      { version: 'v0.1.16', gorm: 'v1.30.0', go: '1.22' },
+      { version: 'v0.1.14', gorm: 'v1.25.10', go: '1.22' },
+      { version: 'v0.1.12', gorm: 'v1.25.1', go: '1.22' },
+    ],
+    note: `For gorm, run go get ${GO_GORM} at the version for the gorm of your go.mod: v0.1.16 for gorm v1.30.0 or later, v0.1.14 for gorm v1.25.10 or later, and v0.1.12 for gorm v1.25.1 or later. A newer plugin version also raises the gorm version in go.mod. After gorm.Open, call db.Use(tracing.NewPlugin(tracing.WithoutMetrics())). Import ${GO_GORM}/tracing. Each query then gets its own span.`,
+    /** The setup tool adds this when it cannot read the gorm version of go.mod. It fills in {gorm}. */
+    raises: 'This also raises gorm in go.mod to {gorm}.',
+    /** The setup tool says this instead of the go get line when the gorm of go.mod is older than every row. */
+    tooOld: 'This app uses gorm {gorm}. The gorm plugin needs gorm v1.25.1 or later, so this tool leaves it out. The other spans work without it. To get a span for each query, raise gorm to v1.25.1 or later first. Then run npx @uknows/setup again.',
+  },
+  redis: {
+    module: GO_REDIS,
+    /**
+     * The redisotel/v9 versions on proxy.golang.org, oldest first. redisotel v9.X needs go-redis v9.X, and some
+     * go-redis releases have no redisotel tag. The setup tool takes the newest one at or below the go-redis of go.mod.
+     */
+    versions: ['v9.0.0', 'v9.0.1', 'v9.0.2', 'v9.0.4', 'v9.0.5', 'v9.5.3', 'v9.5.5', 'v9.6.2', 'v9.6.3', 'v9.7.0', 'v9.7.1', 'v9.7.2', 'v9.7.3',
+      'v9.8.0', 'v9.9.0', 'v9.10.0', 'v9.11.0', 'v9.12.0', 'v9.12.1', 'v9.13.0', 'v9.14.0', 'v9.14.1', 'v9.15.1', 'v9.16.0', 'v9.17.0', 'v9.17.1',
+      'v9.17.2', 'v9.17.3', 'v9.18.0', 'v9.19.0', 'v9.20.0', 'v9.20.1', 'v9.21.0', 'v9.22.0', 'v9.23.0'],
+    note: `For go-redis v9, run go get ${GO_REDIS} at the go-redis version of your go.mod, as in go get ${GO_REDIS}@${GO_REDIS_VERSION}. A newer redisotel also raises the go-redis version in go.mod. For example, go-redis v9.18.0 sends an extra command when it connects, and Redis 7 answers it with an error, so each new connection shows an error span. After redis.NewClient, call redisotel.InstrumentTracing(rdb). Each Redis command then gets its own span.`,
+  },
+}
+
+/** The Echo v4 code for Go below 1.25. */
+export const GO_ECHO_OLDER = `For Echo v4 with Go below ${GO_ECHO.go}, use otelecho instead of echo-otel. echo-otel needs Go ${GO_ECHO.go}. Import ${GO_ECHO.older}. Then use e.Use(otelecho.Middleware(os.Getenv("OTEL_SERVICE_NAME"))).`
+
+/** The step for an app that builds with Go 1.23, 1.24 or 1.25. The setup tool prints the lines for the Go of the app. */
+export const GO_OLDER = {
+  title: 'Your app builds with Go 1.23, 1.24 or 1.25?',
+  summary: 'The newest OpenTelemetry Go modules need Go 1.26. Use the versions for your Go instead. Then go get does not raise the go line of go.mod, and the build works with the Go of your image.',
+  steps: [
+    'Use the go get lines for the Go version of your build image.',
+    'The code in otel.go and main.go stays the same.',
+    GO_ECHO_OLDER,
+    'For gorm and go-redis, add the versions that fit your go.mod, as the notes for gorm and go-redis say.',
+  ],
+  echo: GO_ECHO_OLDER,
+  /** What the setup tool says in its plan. It fills in {version}. */
+  plan: 'This app builds with Go {version}. The newest OpenTelemetry Go modules need Go 1.26, so the go get lines name the versions for Go {version}.',
+}
+
+const GO_OLDER_OPTION             = {
+  title: GO_OLDER.title,
+  summary: GO_OLDER.summary,
+  steps: GO_OLDER.steps,
+  snippets: GO_RELEASES.map((release) => ({
+    caption: `Go ${release.go}`,
+    language: 'bash',
+    code: [goInstall(release), '# go-redis v9 only: redisotel at the go-redis version of go.mod', `go get ${GO_REDIS}@${GO_REDIS_VERSION}`].join('\n'),
+  })),
+}
+
+export const RUBY_INITIALIZER = `# UKNOWS monitoring. The OTEL_ settings configure it.
+unless ENV["OTEL_SDK_DISABLED"] == "true"
+  require "opentelemetry/sdk"
+  require "opentelemetry/exporter/otlp"
+  require "opentelemetry/instrumentation/all"
+
+  OpenTelemetry::SDK.configure do |c|
+    c.use_all
+  end
+end`
+
+/** Adds UKNOWS beside the exporters that a Collector has now. otlphttp adds /v1/traces to the endpoint. */
+export const COLLECTOR_CONFIG = [
+  'exporters:',
+  '  otlphttp/uknows:',
+  `    endpoint: ${INGEST_ENDPOINT}`,
+  '    headers:',
+  '      x-uknows-key: ${env:UKNOWS_KEY}',
+  '',
+  'service:',
+  '  pipelines:',
+  '    traces:',
+  '      # Keep your exporters. otlp/current stands for the one you have now.',
+  '      exporters: [otlp/current, otlphttp/uknows]',
+].join('\n')
+
+/** UKNOWS counts the spans it gets. It does not scale them up by a sample rate. */
+export const SAMPLING_NOTE = 'Keep sampling off. UKNOWS counts the requests that it gets. With OTEL_TRACES_SAMPLER=traceidratio and OTEL_TRACES_SAMPLER_ARG=0.1, UKNOWS shows 1 in 10 of your requests. Remove both settings, or set OTEL_TRACES_SAMPLER=parentbased_always_on.'
+
+/** Every OTLP exporter in the app reads OTEL_EXPORTER_OTLP_HEADERS, and Phoenix falls back to it. */
+export const OTHER_EXPORTERS_NOTE = 'Every OTLP exporter in your app reads OTEL_EXPORTER_OTLP_HEADERS, so it gets your UKNOWS key. If your app also sends traces to Phoenix, set PHOENIX_COLLECTOR_ENDPOINT and PHOENIX_API_KEY for it. Then Phoenix gets its own address and key.'
+
+/**
+ * What the setup tool says when the app uses Phoenix and the repo does not give Phoenix its own address. Phoenix
+ * register() falls back to OTEL_EXPORTER_OTLP_ENDPOINT. Seen on 18 Oct 2026 with arize-phoenix-otel 0.17.2: it
+ * then sent to the UKNOWS host on port 4317, and each span end waited about 20 seconds. The page does not show this.
+ */
+export const PHOENIX_STEP = {
+  title: 'Give Phoenix its own address',
+  lines: [
+    'Phoenix sends its traces to OTEL_EXPORTER_OTLP_ENDPOINT when PHOENIX_COLLECTOR_ENDPOINT is not set. After this setup, that is the UKNOWS address, which refuses them, and your app can wait for each span.',
+    'Set PHOENIX_COLLECTOR_ENDPOINT to the address of your Phoenix where the app runs, and set PHOENIX_API_KEY for it. Or pass the address to register() in your code.',
+  ],
+}
+
+/**
+ * Phoenix register() with no headers and no PHOENIX_API_KEY makes its exporter read the OTLP headers settings, which
+ * hold the UKNOWS key after this setup. Seen in the bench review of 18 Oct 2026. The page does not show this.
+ */
+export const PHOENIX_KEY_STEP = {
+  title: 'Give Phoenix its own key',
+  lines: [
+    'When the app gives Phoenix no key, Phoenix sends its traces with the headers in OTEL_EXPORTER_OTLP_TRACES_HEADERS or OTEL_EXPORTER_OTLP_HEADERS. After this setup, that is your UKNOWS key, so your Phoenix server would get it.',
+    'Set PHOENIX_API_KEY where the app runs, or pass headers to register() in your code.',
+  ],
+}
+
+/** For an app that already uses OpenTelemetry: send only its traces to UKNOWS. */
+export const TRACES_ONLY_NOTE = `For Node.js, Python and Java, set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=${INGEST_ENDPOINT}/v1/traces and OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf instead of OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_PROTOCOL. Their OpenTelemetry SDKs can send metrics and logs over OTLP by default, and UKNOWS refuses metrics. Then your metrics and logs keep going where they go now. Set your key as OTEL_EXPORTER_OTLP_TRACES_HEADERS instead of OTEL_EXPORTER_OTLP_HEADERS too, so only the traces exporter sends it. Do the same in other languages when your app also sends metrics or logs over OTLP.`
+
+/**
+ * What the setup tool says when it uses the traces-only settings. It fills in {where} and {lang}. The page does
+ * not show these.
+ */
+export const TRACES_ONLY_PLAN = {
+  code: '{where} also sends metrics or logs over OTLP.',
+  sdk: 'The OpenTelemetry SDK for {lang} can send metrics and logs over OTLP by default.',
+  set: 'This tool sets OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, so only traces go to UKNOWS. Your metrics and logs keep their current address.',
+  /** The key name for these apps, and the advice that goes with it. */
+  key: 'Your key goes in OTEL_EXPORTER_OTLP_TRACES_HEADERS, not in OTEL_EXPORTER_OTLP_HEADERS, so only the traces exporter sends it. The key steps below use that name.',
+  keyTitle: 'Keep your UKNOWS key on the traces exporter',
+  keyCheck: 'If your code gives the OTLP exporter of metrics or logs its own headers, check that they never hold the UKNOWS key.',
+  /** For a .NET, Go, PHP or Ruby app with no metrics or logs over OTLP in its code. It fills in {endpoint}. */
+  none: 'If your app also sends metrics or logs over OTLP, set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT={endpoint}/v1/traces and OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf instead of OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_PROTOCOL, and set your key as OTEL_EXPORTER_OTLP_TRACES_HEADERS. UKNOWS refuses metrics.',
+}
+
+/**
+ * .NET AddOtlpExporter() reads only the general OTLP settings, not the OTEL_EXPORTER_OTLP_TRACES_ ones (only
+ * UseOtlpExporter() reads those). With the traces-only settings, the traces exporter takes the address in code.
+ */
+export const DOTNET_TRACES_ONLY = {
+  note: 'For .NET, AddOtlpExporter() does not read the OTEL_EXPORTER_OTLP_TRACES_ settings. UseOtlpExporter() reads them. If your app uses AddOtlpExporter(), pass the traces address and the key on in the code of the traces exporter.',
+  code: `using OpenTelemetry.Exporter;
+
+// In WithTracing(...):
+.AddOtlpExporter(otlp =>
+{
+    // AddOtlpExporter does not read the OTEL_EXPORTER_OTLP_TRACES_ settings, so pass the address and the key on.
+    if (Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT") is { Length: > 0 } endpoint)
+    {
+        otlp.Endpoint = new Uri(endpoint);
+        otlp.Protocol = OtlpExportProtocol.HttpProtobuf;
+        otlp.Headers = Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_TRACES_HEADERS") ?? string.Empty;
+    }
+})`,
+}
+
+/**
+ * The block for configure_azure_monitor at module level: 2 blank lines before the call, as PEP 8 wants.
+ * The ${'\n'} line keeps them, because tools/sync-contract.mjs folds 3 new lines into 2. A nested
+ * function, so it never shadows the os or trace names of the app. Inside a function, indent it to the call.
+ */
+export const AZURE_PYTHON_BLOCK = `# Also send these traces to UKNOWS.
+def _send_traces_to_uknows():
+    import os
+
+    if not os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT"):
+        return
+    from opentelemetry import trace
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+        OTLPSpanExporter,
+    )
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    provider = trace.get_tracer_provider()
+    if hasattr(provider, "add_span_processor"):
+        exporter = OTLPSpanExporter()
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+${'\n'}
+_send_traces_to_uknows()`
+
+export const AZURE_NODE_CODE = `// Also send these traces to UKNOWS. Keep your other options.
+const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base')
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto')
+
+useAzureMonitor({
+  // ...your options, such as azureMonitorExporterOptions
+  spanProcessors: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ? [new BatchSpanProcessor(new OTLPTraceExporter())] : [],
+})`
+
+/**
+ * Apps that use Azure Monitor (App Insights) keep it. UKNOWS adds 1 OTLP
+ * exporter to the same tracer provider, so nothing is traced twice. The setup
+ * tool inserts this code and these settings word for word.
+ */
+export const AZURE_MONITOR = {
+  /** Setup only, after the .NET note of the otel stack: the pages name UKNOWS only. */
+  otelNote: 'If your app uses Azure Monitor, keep it. Setup adds UKNOWS beside it.',
+  title: 'Your app uses Azure Monitor? Keep it and add UKNOWS',
+  summary: 'Your App Insights setup stays as it is. UKNOWS adds 1 exporter to the same traces, so nothing is traced twice. Add 1 package and a few lines of code for your language, and 3 settings.',
+  steps: [
+    'Add the OTLP exporter package for your language. Use the OpenTelemetry version that your app has now.',
+    'Add the code for your language after the line that starts Azure Monitor.',
+    'Add the 3 settings. Set OTEL_SERVICE_NAME only if your app does not set it now.',
+    'Keep APPLICATIONINSIGHTS_CONNECTION_STRING. Do not add opentelemetry-instrument, NODE_OPTIONS or instrument.sh.',
+  ],
+  python: {
+    /** The call that starts Azure Monitor. The block goes after its statement. */
+    call: 'configure_azure_monitor(',
+    package: 'opentelemetry-exporter-otlp-proto-http',
+    code: AZURE_PYTHON_BLOCK,
+    /** The web frameworks whose requests azure-monitor-opentelemetry traces. */
+    traced: ['django', 'fastapi', 'flask'],
+    /**
+     * Web frameworks that it does not trace, the requirement names that show them, and the OpenTelemetry
+     * instrumentation to add. FastMCP and the mcp SDK serve HTTP with Starlette.
+     */
+    servers: [
+      { label: 'Starlette', names: ['starlette', 'fastmcp', 'mcp'], package: 'opentelemetry-instrumentation-starlette', module: 'opentelemetry.instrumentation.starlette', instrumentor: 'StarletteInstrumentor' },
+      { label: 'aiohttp', names: ['aiohttp'], package: 'opentelemetry-instrumentation-aiohttp-server', module: 'opentelemetry.instrumentation.aiohttp_server', instrumentor: 'AioHttpServerInstrumentor' },
+      { label: 'Tornado', names: ['tornado'], package: 'opentelemetry-instrumentation-tornado', module: 'opentelemetry.instrumentation.tornado', instrumentor: 'TornadoInstrumentor' },
+      { label: 'Falcon', names: ['falcon'], package: 'opentelemetry-instrumentation-falcon', module: 'opentelemetry.instrumentation.falcon', instrumentor: 'FalconInstrumentor' },
+      { label: 'Pyramid', names: ['pyramid'], package: 'opentelemetry-instrumentation-pyramid', module: 'opentelemetry.instrumentation.pyramid', instrumentor: 'PyramidInstrumentor' },
+    ],
+    /** The required step for those apps. The setup tool fills in each {name}. */
+    untraced: {
+      title: 'Trace the requests of your {label} app',
+      found: '{file} line {line} lists {name}.',
+      builtOn: '{name} serves HTTP with {label}.',
+      why: 'Azure Monitor traces the requests of Django, FastAPI and Flask apps only. Without the step below, App Insights and UKNOWS get no spans for the requests of this app.',
+      add: 'Add {package} to {manifest}. Use the version of your other opentelemetry-instrumentation packages{version}.',
+      call: 'Put the code below at the top of the file that starts the app, before its other imports. instrument() must run before the app imports {name}, or it does not trace the requests.',
+      caption: 'Python: at the top of the file that starts the app',
+    },
+  },
+  dotnet: {
+    call: 'UseAzureMonitor(',
+    package: 'OpenTelemetry.Exporter.OpenTelemetryProtocol',
+    using: 'using OpenTelemetry.Trace;',
+    /** The 1 line goes after this line. */
+    after: 'var builder = WebApplication.CreateBuilder(args);',
+    /**
+     * The overload without the service provider. It runs when the services are added, so AddOtlpExporter can add
+     * its own services. With (sp, tracing) the app stops at start: services cannot be added after the provider is built.
+     * Only with OTEL_EXPORTER_OTLP_ENDPOINT, as the Python and Node.js code: without it, AddOtlpExporter would send to
+     * localhost, for example in tests. Removing that setting turns UKNOWS off and keeps App Insights.
+     */
+    line: 'if (System.Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT") is { Length: > 0 }) builder.Services.ConfigureOpenTelemetryTracerProvider(tracing => tracing.AddOtlpExporter());',
+  },
+  node: {
+    call: 'useAzureMonitor(',
+    packages: ['@opentelemetry/exporter-trace-otlp-proto', '@opentelemetry/sdk-trace-base'],
+    code: AZURE_NODE_CODE,
+    /** For apps that start Azure Monitor with the applicationinsights 3.x package. */
+    shim: 'The applicationinsights 3.x package runs on @azure/monitor-opentelemetry. To add the UKNOWS processor, start Azure Monitor with useAzureMonitor from @azure/monitor-opentelemetry, as in the code.',
+  },
+  /** The 3 settings. OTEL_SERVICE_NAME only when the app does not set it. */
+  settings: SHARED_SETTINGS,
+  roleName: 'OTEL_SERVICE_NAME also sets the Cloud Role Name in App Insights. Alerts and the application map use that name. Set it only when your app does not set it now.',
+  sampling: 'Azure Monitor samples traces, by default 5 traces a second. UKNOWS gets the same traces, so it shows fewer requests for a busy app. A sampling_ratio or traces_per_second in your code, or OTEL_TRACES_SAMPLER, sets other sampling. To send every trace, set OTEL_TRACES_SAMPLER=parentbased_always_on. Then App Insights gets every trace too, which can cost more.',
+  notes: [
+    'Your metrics and logs keep going to App Insights. These settings do not turn them off.',
+    'To turn UKNOWS off and keep App Insights, remove OTEL_EXPORTER_OTLP_ENDPOINT and restart the app. The code above sends to UKNOWS only when that setting is there. Do not use OTEL_SDK_DISABLED=true: App Insights uses the same OpenTelemetry, so it stops too.',
+    'For Python, Azure Monitor traces the requests of Django, FastAPI and Flask apps only. For Starlette, FastMCP, aiohttp, Tornado, Falcon or Pyramid, add the OpenTelemetry instrumentation of that framework. Call its instrument() at the top of the file that starts the app, before the app imports the framework.',
+    'For Node.js, the code shows the spanProcessors option. If your code already passes spanProcessors, add the UKNOWS processor to that list.',
+    'For .NET, the line needs the OpenTelemetry.Trace namespace. Put the using line with the other using lines.',
+  ],
+  /**
+   * What the setup tool says in its plan for these apps. It fills in {name}, {file}, {line} and {value}.
+   * The page does not show these.
+   */
+  plan: {
+    /** 1 sentence on this mode, in the plan of each Azure Monitor app. */
+    mode: 'This app uses Azure Monitor (App Insights). This tool keeps it and adds 1 exporter beside it, so the same traces also go to UKNOWS. App Insights keeps getting the traces, metrics and logs that it gets now.',
+    roleName: {
+      title: 'App Insights Cloud Role Name',
+      set: [
+        'This tool sets OTEL_SERVICE_NAME={name}. Azure Monitor uses that name as the Cloud Role Name of this app, so App Insights shows the app as {name}.',
+        'Alerts, workbooks and the application map that use the current role name stop matching when the name changes. To see the current name, run the query below in Logs in your App Insights resource.',
+        'To keep the current name, run npx @uknows/setup again with --service-name and that name. It takes lowercase letters, digits and -.',
+      ],
+      query: 'requests | summarize count() by cloud_RoleName',
+      kept: '{where} sets the service name already. This tool keeps it, so the Cloud Role Name in App Insights stays the same.',
+    },
+    /** For the Keep line of AZURE_MONITOR.steps, per stack. The tool fills in {start}. */
+    keep: 'Keep APPLICATIONINSIGHTS_CONNECTION_STRING. Do not add {start}.',
+    start: { python: 'opentelemetry-instrument', dotnet: 'instrument.sh', node: 'NODE_OPTIONS' },
+    samplingDefault: 'This app uses the default sampling of Azure Monitor: 5 traces a second.',
+    samplingCode: '{file} line {line} sets the sampling of Azure Monitor: {value}.',
+    samplingEnv: '{file} sets OTEL_TRACES_SAMPLER to {value}.',
+    /** The rest of the sampling advice, per stack. The tool fills in {options}. */
+    sampling: [
+      'UKNOWS gets the same sampled traces, so it shows fewer requests than a busy app gets.',
+      '{options} in your code, or OTEL_TRACES_SAMPLER, sets other sampling.',
+      'To send every trace, set OTEL_TRACES_SAMPLER=parentbased_always_on. Then App Insights gets every trace too, which can cost more.',
+    ],
+    samplingOptions: { python: 'A sampling_ratio or traces_per_second', dotnet: 'A SamplingRatio or TracesPerSecond option', node: 'A samplingRatio or tracesPerSecond option' },
+    /**
+     * How the exporter version follows the SDK. A uv or Poetry project gets a lower limit, so its resolver keeps the
+     * exporter at the SDK version, also after a later Azure Monitor upgrade. A requirements file gets the exact pin
+     * of its other lines. The tool fills in {file}, {package}, {version} and {tool}.
+     */
+    floor: '{file} gets {package}>={version}, a lower limit, so {tool} keeps it at the opentelemetry-sdk version of the app, also when you upgrade Azure Monitor later.',
+    pin: '{file} gets {package}=={version}, the opentelemetry-sdk version of the app. When you upgrade Azure Monitor later, raise {package} to the new opentelemetry-sdk version too. They have the same version.',
+    /** The plan sentence for the Python code. The tool fills in {count}, {call}, {file} and {line}. */
+    pythonCode: 'Also send the Azure Monitor traces to UKNOWS: add {count} lines of code after the {call}...) call in {file} line {line}. The diff below shows them.',
+    browser: '{file} uses {value}. It runs in the browser, so the setup tool does not change it.',
+    connectionString: '{file} sets APPLICATIONINSIGHTS_CONNECTION_STRING, but the app has no Azure Monitor package. The setup tool adds standard OpenTelemetry.',
+    autoAttach: '{file} sets AZURE_MONITOR_AUTO_ATTACH. It attaches Azure Monitor only on Azure App Service, so the setup tool adds standard OpenTelemetry.',
+  },
+}
+
+export const STACKS = [
+  {
+    id: 'node',
+    label: 'Node.js',
+    summary: 'Add the OpenTelemetry Node.js packages. Load them when the app starts.',
+    manifests: ['package.json'],
+    frameworks: ['Express', 'Fastify', 'NestJS', 'Koa', 'Hapi'],
+    install: 'npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node',
+    files: [],
+    dockerfile: [
+      '# Final stage, after your app files and node_modules',
+      `ENV NODE_OPTIONS="--require ${NODE_REGISTER}"`,
+      dockerEnv([NODE_DETECTORS]),
+      'CMD ["node", "server.js"]',
+    ].join('\n'),
+    start: `node --require ${NODE_REGISTER} server.js`,
+    // --require= has no space. With a space, a shell that loads otel.env runs the package path as a command.
+    platformEnv: [`NODE_OPTIONS=--require=${NODE_REGISTER}`],
+    extraSettings: {
+      lines: [NODE_DETECTORS],
+      why: 'OpenTelemetry then asks no cloud metadata address when the app starts.',
+    },
+    options: [
+      {
+        title: 'Your app uses ES modules?',
+        summary: 'Use these lines when package.json has "type": "module", or when your app starts from an .mjs file. With the --require line alone, UKNOWS gets each request without its route.',
+        steps: [
+          'Add 1 more package: @opentelemetry/instrumentation.',
+          'Load OpenTelemetry with the 2 options below, in your Dockerfile, your start line or the NODE_OPTIONS setting on your platform.',
+          'Node prints an ExperimentalWarning about --experimental-loader when the app starts. You can ignore it.',
+        ],
+        snippets: [
+          { caption: 'Terminal: 1 more package', language: 'bash', code: 'npm install --save @opentelemetry/instrumentation' },
+          { caption: 'Dockerfile for ES modules', language: 'dockerfile', code: `ENV NODE_OPTIONS="${NODE_ESM_OPTIONS}"` },
+          { caption: 'Start line for ES modules', language: 'bash', code: `node ${NODE_ESM_OPTIONS} server.mjs` },
+          { caption: 'NODE_OPTIONS on your platform', language: 'text', code: NODE_ESM_OPTIONS },
+        ],
+      },
+      {
+        title: 'Stops cleanly on SIGTERM: add a start file',
+        summary: 'OpenTelemetry listens for SIGTERM to send the last data. Because of that, Node no longer stops on SIGTERM by itself, and Docker, Kubernetes and systemd wait for their time limit and then kill the app. This start file sends the last data, then stops the app as Node does. An app with its own SIGTERM handler keeps it. The setup tool adds the same file.',
+        steps: [
+          `Add the file ${NODE_REGISTER_FILE.path} next to package.json.`,
+          'In the final stage of your Dockerfile, copy the file into the folder of your app. Load it with --require instead of the register line.',
+          `Without Docker, start the app with node --require ./${NODE_REGISTER_FILE.path} server.js.`,
+          `For ES modules, keep the loader option. Use --import=${NODE_REGISTER_PATH} instead of --import=${NODE_REGISTER}.`,
+          'If a package is missing, the app still starts. It prints the warning "OpenTelemetry did not start".',
+        ],
+        snippets: [
+          { caption: NODE_REGISTER_FILE.path, language: NODE_REGISTER_FILE.language, code: NODE_REGISTER_FILE.content },
+          {
+            caption: 'Dockerfile, final stage',
+            language: 'dockerfile',
+            code: ['WORKDIR /app', `COPY ${NODE_REGISTER_FILE.path} ./`, `ENV NODE_OPTIONS="--require ${NODE_REGISTER_PATH}"`].join('\n'),
+          },
+          { caption: 'Start line', language: 'bash', code: `node --require ./${NODE_REGISTER_FILE.path} server.js` },
+          { caption: 'NODE_OPTIONS on your platform', language: 'text', code: `--require=${NODE_REGISTER_PATH}` },
+        ],
+      },
+    ],
+    notes: [
+      'Replace server.js with the file that starts your server.',
+      'Install the packages as normal dependencies. Your production image must include them.',
+      'If your image already sets NODE_OPTIONS, add the --require option to that value.',
+      'If your app uses ES modules, use the steps in "Your app uses ES modules?". The --require line alone loses the route of each request.',
+      'If your repo uses yarn or pnpm, add the same packages with that tool.',
+      // OpenTelemetry for Node.js sends the log records of pino and bunyan (instrumentation-pino, instrumentation-bunyan:
+      // "log sending"). It does not read console.log, and winston needs @opentelemetry/winston-transport, which the UKNOWS
+      // agent image does not have (checked on registry.uknows.my/uknows/agent-node:stable 1.1.1, 25 Oct 2026).
+      'UKNOWS gets the logs that your app writes with pino or bunyan, with the trace id of each request. Lines that your app writes with console.log stay in its own output only.',
+      'With the register line, Node no longer stops on SIGTERM by itself. To stop cleanly, use the start file in "Stops cleanly on SIGTERM".',
+      `Keep ${NODE_DETECTORS} with the 5 settings. Without it, OpenTelemetry asks the metadata addresses of the clouds when the app starts, such as 169.254.169.254 on port 80, and logs a MetadataLookupWarning outside Google Cloud.`,
+    ],
+  },
+  {
+    id: 'python',
+    label: 'Python',
+    summary: 'Add the OpenTelemetry packages for Python and for the libraries that your app uses. Start the app with opentelemetry-instrument.',
+    manifests: ['requirements.txt', 'pyproject.toml', 'Pipfile'],
+    frameworks: ['Django', 'Flask', 'FastAPI', 'Starlette', 'Falcon', 'Tornado'],
+    install: [
+      '[ -z "$(tail -c1 requirements.txt)" ] || echo >> requirements.txt',
+      'pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http',
+      "pip freeze | grep -E '^opentelemetry-(distro|exporter-otlp-proto-http)==' >> requirements.txt",
+      'opentelemetry-bootstrap -a requirements >> requirements.txt',
+      'pip install -r requirements.txt',
+    ].join('\n'),
+    files: [],
+    dockerfile: [
+      '# requirements.txt now lists the OpenTelemetry packages',
+      'RUN pip install --no-cache-dir -r requirements.txt',
+      PYTHON_BRIDGE_COPY,
+      dockerEnv([PYTHON_LOG_HANDLER_OFF, PYTHON_DETECTORS, PYTHON_BRIDGE_PATH]),
+      'CMD ["opentelemetry-instrument", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]',
+    ].join('\n'),
+    start: 'opentelemetry-instrument uvicorn main:app --host 0.0.0.0 --port 8000',
+    startRequired: 'Python still needs the start line. The settings alone do not start monitoring. Start the app with opentelemetry-instrument, also under systemd, Docker and SAE.',
+    extraSettings: {
+      lines: [PYTHON_LOG_HANDLER_OFF, PYTHON_DETECTORS],
+      why: 'The OpenTelemetry logging package then stays off the root logger, so the app prints what it printed before, and the app sends its host name.',
+    },
+    options: [
+      {
+        title: 'Send the logs: add the UKNOWS log bridge',
+        summary: `The OpenTelemetry logging package sends logs from the root logger, and that changes what your app prints: warnings of a logger with no handler, logging.warning() before any setup and the error lines of Flask stop showing. The bridge sends the same log records and changes nothing in the app output. opentelemetry-instrument loads it from PYTHONPATH. The setup tool adds the same files.`,
+        steps: [
+          `Add the folder ${PYTHON_BRIDGE_DIR} next to requirements.txt or pyproject.toml, with the 3 files below.`,
+          `In the final stage of your Dockerfile, copy the folder to ${PYTHON_BRIDGE_IMAGE} and add it to PYTHONPATH, with ${PYTHON_LOG_HANDLER_OFF}.`,
+          `Without Docker, set PYTHONPATH to the full path of the folder, and keep ${PYTHON_LOG_HANDLER_OFF}.`,
+          'Without the bridge, the app sends no logs. Its output stays as it is.',
+        ],
+        snippets: [
+          ...PYTHON_LOG_BRIDGE.files.map((file) => ({ caption: `${PYTHON_BRIDGE_DIR}/${file.path}`, language: file.language, code: file.content })),
+          { caption: 'Dockerfile, final stage', language: 'dockerfile', code: [PYTHON_BRIDGE_COPY, dockerEnv([PYTHON_LOG_HANDLER_OFF, PYTHON_BRIDGE_PATH], [])].join('\n') },
+        ],
+      },
+    ],
+    notes: [
+      'Use Python 3.10 or later. The OpenTelemetry packages need it.',
+      'Run the install commands in the virtual environment of the app. Install the app packages first, because opentelemetry-bootstrap reads them.',
+      `The install line adds opentelemetry-instrumentation-logging. On its own it puts an OpenTelemetry handler on the root logger, whatever OTEL_LOGS_EXPORTER says, and then the warnings and errors of loggers that have no handler do not show in the app output. ${PYTHON_LOG_HANDLER_OFF} keeps it off the root logger. The UKNOWS log bridge in "Send the logs" sends the logs instead.`,
+      `Keep ${PYTHON_DETECTORS} with the 5 settings. Python then sends the host name of the app, as Node.js does.`,
+      'Put opentelemetry-instrument in front of the command that starts your app now.',
+      'For Django, set DJANGO_SETTINGS_MODULE before the app starts.',
+      'opentelemetry-instrument works with 1 worker. For Gunicorn or uvicorn with more than 1 worker, follow the pre-fork server steps in the OpenTelemetry Python docs.',
+      'Remove the --reload option in production.',
+      'If your repo uses uv or Poetry, add the packages to the project that your image installs, then run uv lock or poetry lock. In a uv workspace, that is the member that uv sync --package names. Commit the lock file.',
+      'If your app needs protobuf below version 5, use opentelemetry-distro==0.48b0 and opentelemetry-exporter-otlp-proto-http==1.27.0. They are the last releases that work with protobuf 4. Later releases need protobuf 5 or later.',
+      'A Procfile starts the app only on a platform that reads it. If yours does, put opentelemetry-instrument before the command on the web line yourself.',
+    ],
+  },
+  {
+    id: 'dotnet',
+    label: '.NET',
+    summary: 'Add the OpenTelemetry.AutoInstrumentation package. Start the app with instrument.sh.',
+    manifests: ['*.csproj', '*.sln'],
+    frameworks: ['ASP.NET Core', 'Minimal APIs', 'gRPC for ASP.NET Core'],
+    install: [
+      'dotnet add package OpenTelemetry.AutoInstrumentation',
+      'dotnet publish -c Release -r linux-x64 -o ./publish',
+    ].join('\n'),
+    files: [],
+    dockerfile: [
+      '# Build stage',
+      'RUN dotnet publish -c Release -r linux-x64 -o /app/publish',
+      '',
+      '# Final stage',
+      'WORKDIR /app',
+      'COPY --from=build /app/publish .',
+      dockerEnv([DOTNET_LOG_DIRECTORY, DOTNET_LOGS_MESSAGE]),
+      'ENTRYPOINT ["sh", "./instrument.sh", "dotnet", "OrdersApi.dll"]',
+    ].join('\n'),
+    start: 'sh ./publish/instrument.sh dotnet ./publish/OrdersApi.dll',
+    startRequired: '.NET still needs the start line. The settings alone do not start monitoring. Start the app with instrument.sh, also under systemd, Docker and SAE.',
+    extraSettings: {
+      lines: [DOTNET_LOG_DIRECTORY, DOTNET_LOGS_MESSAGE],
+      why: 'OpenTelemetry writes its log files to this folder, so the app must be able to write to it. The formatted message puts the values of each log line in its text.',
+    },
+    notes: [
+      'Replace OrdersApi.dll with the dll of your app.',
+      'Use .NET 8 or later.',
+      'A runtime identifier in the build is optional. With one, such as -r linux-x64, linux-arm64 or linux-musl-x64 for Alpine images, the publish folder holds the native files of that platform only. Without one, it holds them for every platform, and instrument.sh picks the one it runs on.',
+      'The package puts instrument.sh in the publish folder. The script starts your app with monitoring on.',
+      `Keep ${DOTNET_LOG_DIRECTORY} with the 5 settings. Without a folder that the app can write, the app stops when it starts. The default folder, /var/log/opentelemetry, is not writable on a Mac or in an image that runs as a user that is not root.`,
+      `Keep ${DOTNET_LOGS_MESSAGE} too. Without it, a log line reaches UKNOWS as its message template, such as "Served order {Id}", without the values.`,
+      'If your app uses StackExchange.Redis, also when a package such as NRedisStack brings it in, the build stops and names 1 more package and its version. Add that package. For OpenTelemetry.AutoInstrumentation 1.17.0, run dotnet add package OpenTelemetry.Instrumentation.StackExchangeRedis --version 1.19.0-beta.1.',
+      'If your repo has packages.lock.json, run dotnet restore --force-evaluate after you add the packages. Use the same -r runtime identifier as your build, for example -r linux-x64. Run it also for each project that references the app and has its own packages.lock.json, such as a test project, with the -r of that lock. Then commit every packages.lock.json that changed.',
+      'If your Dockerfile restores the packages with --network=none, add the new packages to the package source that it uses first.',
+      'To turn monitoring off for .NET, set OTEL_DOTNET_AUTO_TRACES_ENABLED=false.',
+    ],
+  },
+  {
+    id: 'java',
+    label: 'Java',
+    summary: `Add the OpenTelemetry Java agent ${JAVA_AGENT.version}. Start the JVM with -javaagent.`,
+    manifests: ['pom.xml', 'build.gradle', 'build.gradle.kts'],
+    frameworks: ['Spring Boot', 'Spring WebFlux', 'Quarkus', 'Micronaut', 'Jakarta EE', 'Dropwizard'],
+    install: [
+      `curl -fsSL -o ${JAVA_AGENT.file} ${JAVA_AGENT.url}`,
+      `echo "${JAVA_AGENT.sha256}  ${JAVA_AGENT.file}" | sha256sum -c -`,
+    ].join('\n'),
+    files: [],
+    dockerfile: [
+      '# Final stage, after your last RUN line',
+      JAVA_COPY_LINE,
+      `ENV JAVA_TOOL_OPTIONS="-javaagent:/otel/${JAVA_AGENT.file}"`,
+      SETTINGS_DOCKERFILE,
+      'CMD ["java", "-jar", "app.jar"]',
+    ].join('\n'),
+    start: `java -javaagent:./${JAVA_AGENT.file} -jar app.jar`,
+    platformEnv: [`JAVA_TOOL_OPTIONS=-javaagent:/path/to/${JAVA_AGENT.file}`],
+    options: [
+      {
+        title: 'Your network blocks ghcr.io?',
+        summary: 'Download the agent from GitHub in a build stage instead. The stage checks the SHA-256 checksum of the agent.',
+        steps: [
+          'Add the build stage below before the final stage of your Dockerfile.',
+          'In the final stage, use its COPY line instead of the COPY line from ghcr.io.',
+          'Keep the ENV JAVA_TOOL_OPTIONS line.',
+        ],
+        snippets: [{ caption: 'Dockerfile', language: 'dockerfile', code: JAVA_AGENT_STAGE }],
+      },
+    ],
+    notes: [
+      `The agent is version ${JAVA_AGENT.version}. Check its SHA-256 checksum before you use it.`,
+      'In the JAVA_TOOL_OPTIONS line, replace /path/to with the folder of the agent.',
+      'On macOS, use shasum -a 256 -c - instead of sha256sum -c -.',
+      'Replace app.jar with your built app. Put -javaagent before -jar. Keep your other JVM options.',
+      'If your image already sets JAVA_TOOL_OPTIONS, add the -javaagent option to that value.',
+      `The COPY line takes the same agent from the OpenTelemetry image ${JAVA_AGENT.image}. The digest pins the exact image. Docker keeps it in its cache, so a build does not download the agent each time.`,
+      'Put the COPY and ENV lines after the last RUN line of the final stage, so build steps do not load the agent.',
+      'Use Java 8 or later. Use a JVM build. Native images need the OpenTelemetry starter for your framework.',
+      'To turn the agent off completely, set OTEL_JAVAAGENT_ENABLED=false.',
+    ],
+  },
+  {
+    id: 'go',
+    label: 'Go',
+    summary: 'Add the OpenTelemetry Go SDK and the middleware for your router. Add a short init file.',
+    manifests: ['go.mod'],
+    frameworks: ['net/http', 'Gin', 'Echo', 'chi'],
+    install: goInstall(),
+    files: [
+      { path: 'otel.go', language: 'go', summary: 'Add this file to your main package.', content: GO_INIT },
+      { path: 'main.go', language: 'go', summary: 'Change main like this. Keep only the middleware for your router.', content: GO_MAIN },
+    ],
+    dockerfile: [
+      '# Build stage: no change. otel.go builds into your binary.',
+      '# Final stage',
+      SETTINGS_DOCKERFILE,
+    ].join('\n'),
+    start: `go build -o ${EXAMPLE_SERVICE} . && ./${EXAMPLE_SERVICE}`,
+    options: [GO_OLDER_OPTION],
+    notes: [
+      `Use Go 1.26 or later. The current OpenTelemetry Go modules need it. With an older Go, the build stops with a Go version error. For Go 1.23, 1.24 or 1.25, use the versions in "${GO_OLDER.title}".`,
+      'Call setupOTel at the start of main. The main.go code stops the server on Ctrl+C or SIGTERM. Then it calls the shutdown function, which sends the last data.',
+      'If your app already stops the server on SIGTERM, keep your code. Call the shutdown function after the server stops and before the app exits.',
+      'Use the middleware for your router. For net/http, wrap the ServeMux with withRoute, then with otelhttp.NewHandler. withRoute adds the route of each request. Gin and Echo add the route on their own.',
+      'For chi, add the route middleware before your routes. chi stops with an error when a middleware comes after a route.',
+      'For another router, call setRoute with the route of the request after the router picks it.',
+      'For outgoing HTTP calls, use otelhttp.NewTransport in your HTTP client. Pass the request context to each call.',
+      'For Echo v5, use github.com/labstack/echo-otel/v5.',
+      GO_LIBRARIES.gorm.note,
+      GO_LIBRARIES.redis.note,
+      'Run go mod tidy. Then run your tests and build.',
+      'These steps add code at startup only. Your business logic stays the same.',
+    ],
+  },
+  {
+    id: 'php',
+    label: 'PHP',
+    summary: 'Add the OpenTelemetry extension and the Composer packages. Turn on autoload with OTEL_PHP_AUTOLOAD_ENABLED.',
+    manifests: ['composer.json'],
+    frameworks: ['Laravel', 'Symfony', 'Slim'],
+    install: [
+      'pecl install opentelemetry',
+      'composer config allow-plugins.php-http/discovery false',
+      'composer require --ignore-platform-req=ext-opentelemetry open-telemetry/sdk open-telemetry/exporter-otlp open-telemetry/opentelemetry-auto-laravel',
+    ].join('\n'),
+    files: [
+      { path: 'php.ini', language: 'ini', summary: 'Turn on the extension. Check it with php -m | grep opentelemetry.', content: '[opentelemetry]\nextension=opentelemetry.so' },
+    ],
+    dockerfile: [
+      '# Official php images',
+      'RUN pecl install opentelemetry \\',
+      ' && docker-php-ext-enable opentelemetry',
+      dockerEnv(['OTEL_PHP_AUTOLOAD_ENABLED=true']),
+    ].join('\n'),
+    start: 'OTEL_PHP_AUTOLOAD_ENABLED=true php artisan serve --no-reload',
+    platformEnv: ['OTEL_PHP_AUTOLOAD_ENABLED=true'],
+    notes: [
+      'Set OTEL_PHP_AUTOLOAD_ENABLED=true with the 5 settings. PHP needs it to start OpenTelemetry.',
+      'Keep --no-reload with php artisan serve. Without it, artisan serve does not pass the OTEL_ settings to your app.',
+      'For Symfony, use open-telemetry/opentelemetry-auto-symfony instead of the Laravel package.',
+      'For Slim, use open-telemetry/opentelemetry-auto-slim instead of the Laravel package.',
+      'The exporter needs a PSR-18 HTTP client. Laravel apps include Guzzle, which works. For other apps, run composer require guzzlehttp/guzzle.',
+      'The --ignore-platform-req option lets composer add the packages on a computer without the extension. The image installs the extension. If your Dockerfile runs composer install in a stage without the extension, such as the composer image, add --ignore-platform-req=ext-opentelemetry to that line too.',
+      'PHP-FPM removes environment variables by default. Set clear_env = no in the pool config, or pass each setting with env[NAME].',
+      'On Alpine images, install the build tools first with apk add --no-cache $PHPIZE_DEPS.',
+    ],
+  },
+  {
+    id: 'ruby',
+    label: 'Ruby',
+    summary: 'Add the OpenTelemetry gems. Add an initializer that turns on all instrumentation.',
+    manifests: ['Gemfile'],
+    frameworks: ['Rails', 'Sinatra', 'Rack'],
+    install: 'bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all',
+    files: [
+      { path: 'config/initializers/opentelemetry.rb', language: 'ruby', summary: 'Add this file for Rails.', content: RUBY_INITIALIZER },
+    ],
+    dockerfile: [
+      '# bundle install adds the gems from Gemfile.lock',
+      'RUN bundle install',
+      SETTINGS_DOCKERFILE,
+      'CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]',
+    ].join('\n'),
+    start: 'bundle exec rails server',
+    notes: [
+      'For Sinatra, put the same code in config.ru after require "sinatra" and before your app loads.',
+      'For a plain Rack app, put the same code in config.ru. Below it, add use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args).',
+      'Commit Gemfile and Gemfile.lock.',
+    ],
+  },
+  {
+    id: 'otel',
+    label: 'I already use OpenTelemetry',
+    summary: 'Keep your OpenTelemetry setup. Point its traces at UKNOWS with 3 of the settings.',
+    manifests: ['package.json', 'requirements.txt', 'pyproject.toml', '*.csproj', 'pom.xml', 'build.gradle', 'go.mod', 'composer.json', 'Gemfile'],
+    frameworks: ['Any app that already lists OpenTelemetry packages: @opentelemetry/*, opentelemetry-*, OpenTelemetry.*, io.opentelemetry, go.opentelemetry.io or open-telemetry/*'],
+    install: '# No new packages. Keep the OpenTelemetry packages that you use now.',
+    files: [],
+    dockerfile: ['# Final stage. Your SDK reads these settings at startup.', SHARED_SETTINGS_DOCKERFILE].join('\n'),
+    start: '# Keep your start command. Your SDK reads the OTEL_ settings when the app starts.',
+    settings: SHARED_SETTINGS,
+    warning: 'These settings send your traces to UKNOWS instead of the backend that gets them now. Your metrics and logs keep going where they go now. To keep your current backend for traces too, add UKNOWS to an OpenTelemetry Collector instead. See "Keep your current backend: add UKNOWS to your Collector".',
+    options: [
+      {
+        title: 'Keep your current backend: add UKNOWS to your Collector',
+        summary: 'Your apps keep their settings and send to your OpenTelemetry Collector. The Collector sends traces to your current backend and to UKNOWS.',
+        steps: [
+          'Add the otlphttp/uknows exporter below to your Collector config.',
+          'Add otlphttp/uknows to the exporters of your traces pipeline. Keep the exporters that you have.',
+          `Set UKNOWS_KEY as a secret on the Collector, as "${STEP_TITLES.secret}" says. Use the key only, without x-uknows-key=.`,
+          'Restart the Collector.',
+          'Newer Collectors name this exporter otlp_http. If your Collector says that otlphttp is deprecated, rename otlphttp/uknows to otlp_http/uknows in both places.',
+        ],
+        snippets: [{ caption: 'Collector config', language: 'yaml', code: COLLECTOR_CONFIG }],
+      },
+    ],
+    notes: [
+      'Remove exporter addresses and headers from your code. Then the OTEL_ settings apply.',
+      'Set OTEL_TRACES_EXPORTER to otlp, or remove it.',
+      'UKNOWS takes OTLP over HTTP. If your code creates a gRPC exporter, change it to the HTTP exporter.',
+      'For Python, use the opentelemetry-exporter-otlp-proto-http package. For Go, use the otlptracehttp exporter.',
+      'If you send data through an OpenTelemetry Collector, add UKNOWS to the Collector. The config is in "Keep your current backend: add UKNOWS to your Collector".',
+      TRACES_ONLY_NOTE,
+      DOTNET_TRACES_ONLY.note,
+      SAMPLING_NOTE,
+    ],
+  },
+]
+
+/**
+ * The settings of 1 stack as env lines, for otel.env and the settings tab:
+ * the 5 settings, then for each extra group a # line and its lines. A shell,
+ * systemd and docker run --env-file skip the # lines.
+ */
+export function stackSettingsEnv(stack) {
+  const lines = [stackSettings(stack).map((setting) => `${setting.name}=${setting.value}`).join('\n')]
+  if (stack.extraSettings) lines.push(`# For ${stack.label}: ${stack.extraSettings.why}`, ...stack.extraSettings.lines)
+  if (stack.platformEnv?.length) lines.push(`# For ${stack.label}: this loads OpenTelemetry when the app starts.`, ...stack.platformEnv)
+  return lines.join('\n')
+}
+
+/** A stricter way to store the key, shown folded under the host. */
+
+/**
+ * A check for 1 kind of deploy file. The page lists every check of a host.
+ * The setup tool prints a check when it finds that kind of file in the repo,
+ * with the file and line.
+ */
+
+/** How the setup tool and the page name the checks of a host. The tool fills in {where} for the files that it finds. */
+export const DEPLOY_CHECKS = {
+  title: 'Check your deploy files',
+  found: 'Found in {where}.',
+}
+
+/** The path of the key file on a VM or Docker host. Only root can read it. */
+export const KEY_FILE = '/etc/uknows.env'
+
+/** A word for a bash script: as it is when it is plain, else in single quotes. */
+const shellWord = (text        ) => (/^[A-Za-z0-9._-]+$/.test(text) ? text : `'${text.replace(/'/g, `'\\''`)}'`)
+
+/** event.name of the deploy marker of a VM: the coverage watchdog of UKNOWS looks for log records with it. */
+export const DEPLOY_EVENT = 'uknows.deploy'
+
+/**
+ * The deploy marker of a VM: run on the host as the last step of each deploy, it sends 1 log record to UKNOWS. A deploy
+ * inside a machine never reaches the activity log of the cloud, so this record is how UKNOWS knows that a deploy
+ * happened, and can say when one stops the data of the app. The record has event.name uknows.deploy, the service name,
+ * and the Azure resource id of the machine from the Azure instance metadata (exact, never a guess), and the body
+ * "uknows deploy", with "commit <7 to 12 hex characters>" when COMMIT holds one. The key comes from KEY_FILE and is never
+ * an argument of a program: curl reads the header from a pipe. The deploy never fails because of the marker: each problem
+ * prints 1 line and the script ends with 0. RESOURCE_ID, when set, takes the place of the instance metadata; it must be
+ * an Azure resource id of a virtual machine or a scale set instance.
+ */
+export function vmDeployMarker(service = EXAMPLE_SERVICE) {
+  return [
+    '# Run in bash on the host, as root or with sudo, as the last step of each deploy.',
+    `SERVICE=${shellWord(service)}   # the service name of the app (OTEL_SERVICE_NAME)`,
+    'COMMIT=${COMMIT:-}   # optional: the commit that this deploy runs, 7 to 12 hex characters',
+    '(',
+    `  KEY_FILE=\${UKNOWS_KEY_FILE:-${KEY_FILE}}`,
+    `  ENDPOINT=\${OTEL_EXPORTER_OTLP_ENDPOINT:-${INGEST_ENDPOINT}}`,
+    `  KEY="$(sed -n 's/^${SECRET.name}=${SECRET.header}=//p' "$KEY_FILE" 2>/dev/null | head -n 1)"`,
+    '  [ -n "$KEY" ] || { echo "No key in $KEY_FILE, so no deploy marker. Do the key step first."; exit 0; }',
+    "  ID=\"${RESOURCE_ID:-$(curl -fsS -m 5 -H Metadata:true 'http://169.254.169.254/metadata/instance/compute/resourceId?api-version=2021-02-01&format=text' 2>/dev/null)}\"",
+    '  case "$ID" in',
+    '    /subscriptions/*/resourceGroups/*/providers/Microsoft.Compute/*) ;;',
+    '    *) echo "This is not an Azure VM and RESOURCE_ID is not set, so no deploy marker."; exit 0 ;;',
+    '  esac',
+    '  case "$SERVICE$ID" in *[!A-Za-z0-9/._\\(\\)-]*) echo "SERVICE or the resource id has other characters, so no deploy marker."; exit 0 ;; esac',
+    '  BODY="uknows deploy"',
+    '  case "$COMMIT" in ?????????????*|*[!0-9a-f]*|"") ;; ???????*) BODY="uknows deploy commit $COMMIT" ;; esac',
+    '  NOW="$(date +%s)000000000"',
+    `  attr() { printf '{"key":"%s","value":{"stringValue":"%s"}}' "$1" "$2"; }`,
+    `  printf '{"resourceLogs":[{"resource":{"attributes":[%s,%s,%s,%s]},"scopeLogs":[{"scope":{"name":"${DEPLOY_EVENT}"},"logRecords":[{"timeUnixNano":"%s","observedTimeUnixNano":"%s","severityNumber":9,"severityText":"INFO","body":{"stringValue":"%s"},"attributes":[%s]}]}]}]}' \\`,
+    '    "$(attr service.name "$SERVICE")" "$(attr cloud.provider azure)" "$(attr cloud.platform azure.vm)" "$(attr cloud.resource_id "$ID")" \\',
+    `    "$NOW" "$NOW" "$BODY" "$(attr event.name ${DEPLOY_EVENT})" |`,
+    `    curl -fsS -m 10 -o /dev/null -X POST "$ENDPOINT/v1/logs" -H 'content-type: application/json' -H @<(printf '${SECRET.header}: %s\\n' "$KEY") --data-binary @- \\`,
+    '    && echo "Sent the deploy marker to UKNOWS." || echo "UKNOWS did not get the deploy marker. Your deploy is done."',
+    ')',
+  ].join('\n')
+}
+
+/**
+ * A bash script that asks for the key without showing it. The ( ) block is a
+ * subshell: exit stops the block, not the terminal, and the key is gone when
+ * the block ends. bash reads the whole block before it runs, so pasted lines
+ * never become the key.
+ */
+export function keyScript(setup, body, where = 'Run in bash') {
+  return [
+    `# ${where}. The key does not show on the screen. It is gone when the ( ) block ends.`,
+    '(',
+    ...[...setup, KEY_PROMPT, KEY_EMPTY_GUARD, ...body].map((line) => `  ${line}`),
+    ')',
+  ].join('\n')
+}
+
+/** The first step of the key steps of a host. Kubernetes and the other hosts that are not 1 cloud use the plain Windows tip. */
+export const BASH_STEP = `Open a bash terminal. ${MACOS_TIP} ${WINDOWS_TIP}`
+export const AZURE_BASH_STEP = `Open a bash terminal. ${MACOS_TIP} On Windows, use Azure Cloud Shell or WSL.`
+export const AWS_BASH_STEP = `Open a bash terminal. ${MACOS_TIP} On Windows, use AWS CloudShell or WSL.`
+
+/**
+ * The names that a key script uses. The page shows the examples (EXAMPLE_NAMES). The setup tool fills in the names
+ * that it finds in the deploy files of the repo. from: where each found name comes from, such as "deploy.yml line 12".
+ * Each name keeps a comment that says where it comes from, or that it is an example.
+ */
+
+/**
+ * The first lines of each Azure script: the subscription, the resource group and the apps. Every az command names
+ * the subscription, so a script never acts on another subscription that happens to be the default of the CLI.
+ * The script stops when SUBSCRIPTION is empty.
+ */
+export function azureNames(names = {}, one = false) {
+  const from = names.from ?? {}
+  // A comment for each name: where it comes from, what it is, or that it is an example.
+  const say = (key                                                            , given         , what        , example        ) =>
+    (from[key] ? `from ${from[key]}` : given ? what : example)
+  return [
+    `SUBSCRIPTION="${names.subscription ?? ''}"   # ${say('subscription', Boolean(names.subscription), 'the subscription of your apps', 'the id of the subscription of your apps. az account list -o table lists them.')}`,
+    '[ -n "$SUBSCRIPTION" ] || { echo "Set SUBSCRIPTION first. Nothing changed."; exit 1; }',
+    `RESOURCE_GROUP=${names.resourceGroup ?? EXAMPLE_NAMES.resourceGroup}   # ${say('resourceGroup', Boolean(names.resourceGroup), 'the resource group of your apps', 'an example. Use the resource group of your apps.')}`,
+    ...(one
+      ? [`APP=${names.app ?? EXAMPLE_SERVICE}   # ${say('app', Boolean(names.app), 'the name of your app on the platform', 'an example. Use the name of your app on the platform.')}`,
+        ...(names.slot ? [names.slotUnknown
+          ? `SLOT=your-slot   # an example. Use the slot that ${from.slot ?? 'your deploy'} deploys to.`
+          : `SLOT=${names.slot}   # ${say('slot', true, 'the deployment slot', '')}`] : [])]
+      : [`APPS="${names.apps ?? EXAMPLE_NAMES.apps}"   # ${say('apps', Boolean(names.apps), 'only these apps get the key', 'examples. Only these apps get the key.')}${from.apps ? '. Only these apps get the key.' : ''}`]),
+  ]
+}
+
+/**
+ * The lines before the key prompt of a script that changes apps one by one.
+ * With DRY_RUN=1 the script only checks that each app exists and says what it
+ * would change. It never asks for the key.
+ */
+export function dryRun(show, change, names = {}) {
+  return [
+    ...azureNames(names),
+    'DRY_RUN=1   # 1: list the changes only. 0: make them.',
+    'if [ "$DRY_RUN" = 1 ]; then',
+    '  for APP in $APPS; do',
+    `    ${show} --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none &&`,
+    `    echo "Would set the key on $APP. ${change}"`,
+    '  done',
+    '  exit 0',
+    'fi',
+  ]
+}
+
+/** The key script for Azure Container Apps. */
+export function acaKeyScript(names = {}) {
+  return keyScript(dryRun('az containerapp show', 'It would restart the app.', names), [
+    'for APP in $APPS; do',
+    '  az containerapp secret set --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+    '    --secrets "uknows-otlp-headers=x-uknows-key=$UKNOWS_KEY" &&',
+    '  az containerapp update --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+    '    --set-env-vars "OTEL_EXPORTER_OTLP_HEADERS=secretref:uknows-otlp-headers" &&',
+    '  echo "Set the key on $APP."',
+    'done',
+  ])
+}
+
+/** The Key Vault script for Azure Container Apps. It never sees the key. */
+export function acaVaultScript(names = {}) {
+  return [
+    '# Run in bash. This script never sees the key.',
+    '(',
+    ...dryRun('az containerapp show', 'It would restart the app.', names).map((line) => `  ${line}`),
+    '  SECRET_URI=https://my-vault.vault.azure.net/secrets/uknows-otlp-headers',
+    '  for APP in $APPS; do',
+    '    az containerapp secret set --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+    '      --secrets "uknows-otlp-headers=keyvaultref:$SECRET_URI,identityref:system" &&',
+    '    az containerapp update --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+    '      --set-env-vars "OTEL_EXPORTER_OTLP_HEADERS=secretref:uknows-otlp-headers" &&',
+    '    echo "Set the key on $APP."',
+    '  done',
+    ')',
+  ].join('\n')
+}
+
+/** The key script for Azure App Service web apps. */
+export function appServiceKeyScript(names = {}) {
+  return keyScript(dryRun('az webapp show', 'It would restart the app.', names), [
+    'for APP in $APPS; do',
+    '  az webapp config appsettings set --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+    '    --settings "OTEL_EXPORTER_OTLP_HEADERS=x-uknows-key=$UKNOWS_KEY" &&',
+    '  echo "Set the key on $APP."',
+    'done',
+  ])
+}
+
+/** The key script for Azure Functions: the key as an app setting of each function app. */
+export function functionsKeyScript(names = {}) {
+  return keyScript(dryRun('az functionapp show', 'It would restart the app.', names), [
+    'for APP in $APPS; do',
+    '  az functionapp config appsettings set --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+    '    --settings "OTEL_EXPORTER_OTLP_HEADERS=x-uknows-key=$UKNOWS_KEY" &&',
+    '  echo "Set the key on $APP."',
+    'done',
+  ])
+}
+
+/** The 5 settings as app settings of each function app (the docs tab). It has no key. */
+export function functionsSettingsScript(names = {}) {
+  return [
+    '# Run in bash. This script has no key.',
+    ...azureNames(names),
+    'for APP in $APPS; do',
+    '  az functionapp config appsettings set --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none --settings \\',
+    ...SETTINGS.map((setting) => `    "${setting.name}=${setting.name === 'OTEL_SERVICE_NAME' ? '$APP' : setting.value}" \\`),
+    '    && echo "Set the 5 settings on $APP."',
+    'done',
+  ].join('\n')
+}
+
+/**
+ * Azure Functions, for the setup tool. The docs page does not show these yet: it says that serverless functions are not
+ * supported (SERVERLESS) until the install proof (test A3) passes. The Functions host itself sends a server span for
+ * each call of a function, and the logs, over OTLP, when host.json has "telemetryMode": "OpenTelemetry" and the app
+ * has the OTLP app settings. Measured on the bench on 22 Oct 2026: every request of a Node.js, a Python and a .NET
+ * isolated function app had its server span, with no package and no code in the app. The setup tool fills in {file},
+ * {value} and {count}.
+ */
+export const FUNCTIONS = {
+  label: 'Azure Functions',
+  telemetryMode: 'OpenTelemetry',
+  summary: 'Turn on OpenTelemetry in the Functions host: "telemetryMode": "OpenTelemetry" in {file}.',
+  other: {
+    title: 'Turn on OpenTelemetry in host.json',
+    lines: [
+      '{file} sets "telemetryMode" to {value}. This tool does not change it.',
+      'Set it to "OpenTelemetry". Then the Functions host sends the traces and logs of your functions to UKNOWS.',
+    ],
+  },
+  unreadable: {
+    title: 'Turn on OpenTelemetry in host.json',
+    lines: [
+      'This tool cannot read {file} as JSON, so it did not change it.',
+      'Add "telemetryMode": "OpenTelemetry" next to "version" in it. Then the Functions host sends the traces and logs of your functions to UKNOWS.',
+    ],
+  },
+  notes: [
+    'The Functions host sends a trace for each call of a function, and the logs, once host.json and the app settings are in. Your code needs no package.',
+    'With OpenTelemetry on, the log stream of the Azure portal does not show the logs of this app, and "Recent function invocations" only shows data that goes to Application Insights. If the app has APPLICATIONINSIGHTS_CONNECTION_STRING, the host keeps sending to Application Insights too.',
+  ],
+  /** The UKNOWS hooks cannot apply to this app (hooks.unsupported), so host.json stays as it is (measured 22 Oct 2026). */
+  standDown: {
+    title: 'OpenTelemetry stays off for this function app',
+    reason: 'This tool cannot add the UKNOWS hooks to this app: {reason}.',
+    signs: '{signs} show that this app sends to Application Insights.',
+    unknown: 'This tool could not look at the app settings of your function app in Azure, so it cannot tell if the app sends to Application Insights.',
+    lines: [
+      'With OpenTelemetry on in the Functions host, Application Insights still gets the requests and the logs. But it names each request by its route, such as GET api/orders/{id}, instead of the name of the function, and leaves out InvocationId. The function list under Monitor in the Azure portal, and your own queries and alerts on the function name, then change. The log stream of the Azure portal stops showing the logs of the app.',
+      'To turn it on in the Functions host anyway, run npx @uknows/setup --functions-opentelemetry.',
+    ],
+  },
+  /** A dry run in a terminal: what a real run does first. */
+  predicted: 'A real run first checks the app settings of your function app in Azure. If the app sends to Application Insights, it adds the UKNOWS hooks instead of this line.',
+  /** The pull request text, when host.json gets the line: a paragraph of its own. */
+  pr: 'Turns on OpenTelemetry in the Azure Functions host (host.json). The host then sends the traces and logs of each call of a function to UKNOWS. The log stream of the Azure portal stops showing the logs of the app; UKNOWS shows them.',
+  /**
+   * The UKNOWS worker hooks: the default for a function app that sends to Application Insights, or where setup cannot
+   * tell. The host keeps its Application Insights mode (measured on the bench, 22 and 23 Oct 2026: Application Insights
+   * the same, a server span for each call, the same trace id and InvocationId).
+   */
+  hooks: {
+    summary: {
+      node: 'Add the UKNOWS hooks: {file}, loaded with your functions ("main": "{main}" in package.json). Application Insights stays exactly as it is.',
+      file: 'Add the UKNOWS hooks: {file}. Application Insights stays exactly as it is.',
+      python: 'Add the UKNOWS hooks: {file}, loaded by 2 lines in {app}. Application Insights stays exactly as it is.',
+      dotnet: 'Add the UKNOWS hooks: {file}, loaded by 2 lines in {program}. Application Insights stays exactly as it is.',
+    },
+    notes: [
+      'This function app sends to Application Insights, or this tool could not tell. So instead of the line in host.json, this tool adds small UKNOWS hooks to the code of the app. Application Insights keeps the same requests, names and fields. UKNOWS gets a span for each call of a function, with the trace id of Application Insights, and the logs.',
+    ],
+    packagesTitle: 'Add the OpenTelemetry packages of the UKNOWS hooks',
+    packagesByHand: 'This tool cannot add these packages here. Add them at exactly these versions: UKNOWS tested the hooks with them.',
+    pythonTitle: 'Load the UKNOWS hooks in function_app.py',
+    pythonByHand: 'This tool did not find 1 FunctionApp and the azure.functions import in {file}. Add the import at the top, and the instrument line after the last function, with the name of your FunctionApp.',
+    dotnetTitle: 'Add the UKNOWS middleware in Program.cs',
+    dotnetByHand: 'This tool cannot place the 2 lines in {file}. Add them where the worker is set up, after the builder is made.',
+    untested: {
+      title: 'Check UKNOWS after the deploy: a version that UKNOWS did not test',
+      other: 'This app uses {name} {found}. UKNOWS tested the hooks with {name} {tested}.',
+      unknown: 'This tool cannot read the version of {name} that this app uses. UKNOWS tested the hooks with {name} {tested}.',
+      on: 'Tested on {on}.',
+      lines: ['After the deploy, check that each call of the app shows in UKNOWS. If it does not, run npx @uknows/setup remove and tell us.'],
+    },
+    unsupported: {
+      otel: 'the app sends OpenTelemetry or Azure Monitor data from its own code already',
+      language: 'the hooks are for Node.js, Python and .NET function apps, not {lang}',
+      packageJson: 'this tool cannot read package.json',
+      nodeV3: 'the hooks need version 4 of @azure/functions, the v4 programming model',
+      nodeMain: 'package.json has no "main" that this tool can change',
+      pythonV1: 'the hooks need function_app.py, the v2 programming model of Python',
+      pythonRequirements: 'the app has no requirements.txt',
+      dotnetInProcess: 'the hooks need the isolated worker (Microsoft.Azure.Functions.Worker); the in-process model has no middleware',
+    },
+    pr: 'Adds small UKNOWS hooks to the function app ({files}). The Functions host keeps its Application Insights mode, so Application Insights keeps the same requests, names and fields. UKNOWS gets a span for each call and the logs from the worker, with the same trace id.',
+    prPython: 'Python: the function app needs the app setting PYTHON_ENABLE_WORKER_EXTENSIONS=1 too, with the other settings. The Python worker runs the hooks only with it.',
+  },
+  settings: {
+    title: 'Set the app settings of your function app',
+    lines: [
+      'A function app reads its settings from its app settings, not from a file in the repo. Add the {count} settings below to each function app that runs this code.',
+      'They stay when you deploy new code. Set them once for each app, for example staging and production.',
+    ],
+  },
+  key: {
+    title: 'Set your key once: Azure Functions',
+    lines: [
+      AZURE_BASH_STEP,
+      'Sign in with az login.',
+      'Set SUBSCRIPTION, RESOURCE_GROUP and APPS to your function apps at the top of the script. az account list -o table lists your subscriptions. Run the script with DRY_RUN=1 first. It checks each app and says what it would change.',
+      'Set DRY_RUN=0 and run it again. Paste your key when it asks. The key does not show on the screen.',
+      'Azure restarts each function app with the key. Run it at a quiet time.',
+      'Run the script on your own computer or in Azure Cloud Shell. Do not run it on a shared server. Other users of a shared server can see the commands that run, and the az command gets the key.',
+    ],
+  },
+}
+
+/** The Key Vault script for Azure App Service. It never sees the key. */
+export function appServiceVaultScript(names = {}) {
+  return [
+    '# Run in bash. This script never sees the key.',
+    '(',
+    ...dryRun('az webapp show', 'It would restart the app.', names).map((line) => `  ${line}`),
+    '  SECRET_URI=https://my-vault.vault.azure.net/secrets/uknows-otlp-headers',
+    '  for APP in $APPS; do',
+    '    az webapp config appsettings set --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+    '      --settings "OTEL_EXPORTER_OTLP_HEADERS=@Microsoft.KeyVault(SecretUri=$SECRET_URI)" &&',
+    '    echo "Set the key on $APP."',
+    '  done',
+    ')',
+  ].join('\n')
+}
+
+/**
+ * App Service with a deployment slot that is swapped into production. A swap moves the code and the plain app
+ * settings between the slots, and a slot setting stays with its slot. So the key goes on each slot as a slot setting.
+ * The setup tool prints this when a deploy file names a slot. It fills in {app}, {slot} and {where}.
+ */
+export const APP_SERVICE_SLOTS = {
+  title: 'Set the key on both slots of {app}',
+  lines: [
+    '{where} deploys {app} to the slot {slot}, and a swap moves the slot into production.',
+    'A swap moves the code and the plain app settings between the slots. A slot setting stays with its slot. So set the key as a slot setting on both slots: the production slot with the key of your Production environment, and the {slot} slot with the key of the environment that it serves.',
+    'Run both scripts below. Each one asks for its key. Each one restarts that slot, so run them at a quiet time.',
+  ],
+}
+
+/** The script that sets the key as a slot setting on 1 slot of a web app: production when names.slot is empty. */
+export function appServiceSlotScript(names = {}) {
+  const slot = names.slot ? ' --slot "$SLOT"' : ''
+  return keyScript(azureNames(names, true), [
+    `az webapp config appsettings set --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP"${slot} -o none \\`,
+    '  --slot-settings "OTEL_EXPORTER_OTLP_HEADERS=x-uknows-key=$UKNOWS_KEY" &&',
+    names.slot ? 'echo "Set the key on the $SLOT slot of $APP."' : 'echo "Set the key on the production slot of $APP."',
+  ], names.slotUnknown ? 'Run in bash for the deployment slot' : names.slot ? `Run in bash for the ${names.slot} slot` : 'Run in bash for the production slot')
+}
+
+/**
+ * App Service that runs the code of the app, not an image (a zip or Oryx deploy). App Service does not use the
+ * Dockerfile of the repo then, so the start line and the settings must be set on App Service. The setup tool prints
+ * this as a required step. It fills in {where}, {dockerfile}, {count}, {startWhere}, {startup} and {prefix}.
+ */
+export const APP_SERVICE_CODE = {
+  title: 'Set the start command and the settings on App Service',
+  lines: [
+    '{where} deploys the code of this app to App Service, not an image. App Service builds the code itself and does not use {dockerfile}, so the changes in {dockerfile} do not reach the app there.',
+    'Add the {count} settings below as app settings of the web app. Put them in the step of your deploy that sets the other app settings, so each deploy keeps them.',
+  ],
+  start: '{startWhere} sets the startup command to {startup}. Change it to the startup command below, so App Service starts the app with {prefix}.',
+  startNone: 'Set the startup command below on the web app, so App Service starts the app with {prefix}. Replace the command after {prefix} with the command that starts your app.',
+  noDockerfile: 'your Dockerfile',
+}
+
+/** The GitHub environment secret commands, 1 for each environment, and the repository secret when a job has none. */
+export function githubSecretCommands(environments = [EXAMPLE_NAMES.environment], repo = EXAMPLE_NAMES.repo) {
+  return environments.map((environment) => `gh secret set UKNOWS_KEY --env ${environment} --repo ${repo}`).join('\n')
+}
+
+/** The workflow step that sets the key on a container app, before the deploy step. */
+export function githubKeyStep(names = {}) {
+  const environment = names.environment === undefined ? EXAMPLE_NAMES.environment : names.environment
+  return [
+    `# Add this step before your deploy step${environment ? `, in the job with environment: ${environment}` : ''}.`,
+    '# An earlier step signs in to Azure.',
+    '- name: Set the UKNOWS key',
+    '  env:',
+    '    SUBSCRIPTION: ${{ vars.AZURE_SUBSCRIPTION_ID }}   # the subscription id of the app',
+    `    RESOURCE_GROUP: ${names.resourceGroup ?? EXAMPLE_NAMES.resourceGroup}`,
+    `    APP: ${names.app ?? EXAMPLE_SERVICE}`,
+    '    UKNOWS_KEY: ${{ secrets.UKNOWS_KEY }}',
+    '  run: |',
+    '    [ -n "$UKNOWS_KEY" ] || { echo "::error::Set the UKNOWS_KEY secret for this environment."; exit 1; }',
+    '    az containerapp secret set --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none --secrets "uknows-otlp-headers=x-uknows-key=$UKNOWS_KEY"',
+    `# In your deploy step, add ${ACA_SECRET_REF} to its environment variables.`,
+    `# If the command has --set-env-vars already, add the pair to that list: az uses only the last --set-env-vars.`,
+  ].join('\n')
+}
+
+/**
+ * What the setup tool says about the deploy jobs of each workflow. It fills in {where}, {job} and {environment}.
+ * The page does not show these.
+ */
+export const GITHUB_JOBS = {
+  found: '{where}: the deploy job {job} has environment: {environment}. Set the key for that environment.',
+  none: '{where}: the deploy job {job} has no environment: line, so it cannot read an environment secret.',
+}
+
+export const QUIET_TIME = 'Run it at a quiet time.'
+
+/** The env entry that loads the key from the uknows-otlp-headers secret of a container app. */
+export const ACA_SECRET_REF = 'OTEL_EXPORTER_OTLP_HEADERS=secretref:uknows-otlp-headers'
+
+export const ACA_YAML = [
+  '# Your Container Apps YAML file. Keep your other settings.',
+  'properties:',
+  '  configuration:',
+  '    secrets:',
+  '      - name: uknows-otlp-headers',
+  '        keyVaultUrl: https://my-vault.vault.azure.net/secrets/uknows-otlp-headers',
+  '        identity: system',
+  '  template:',
+  '    containers:',
+  `      - name: ${EXAMPLE_SERVICE}`,
+  '        env:',
+  '          - name: OTEL_EXPORTER_OTLP_HEADERS',
+  '            secretRef: uknows-otlp-headers',
+].join('\n')
+
+export const ACA_BICEP = [
+  '// In your Microsoft.App/containerApps resource. Keep your other settings.',
+  '// The app reads the secret from Key Vault with its managed identity.',
+  'configuration: {',
+  '  secrets: [',
+  '    {',
+  "      name: 'uknows-otlp-headers'",
+  "      keyVaultUrl: 'https://my-vault.vault.azure.net/secrets/uknows-otlp-headers'",
+  "      identity: 'system'",
+  '    }',
+  '  ]',
+  '}',
+  'template: {',
+  '  containers: [',
+  '    {',
+  `      name: '${EXAMPLE_SERVICE}'`,
+  '      env: [',
+  "        { name: 'OTEL_EXPORTER_OTLP_HEADERS', secretRef: 'uknows-otlp-headers' }",
+  '      ]',
+  '    }',
+  '  ]',
+  '}',
+].join('\n')
+
+export const ACA_TERRAFORM = [
+  '# Pass the value with TF_VAR_uknows_otlp_headers. Keep it out of the repo.',
+  'variable "uknows_otlp_headers" {',
+  '  type      = string',
+  '  sensitive = true',
+  '}',
+  '',
+  '# In your azurerm_container_app resource. Keep your other settings.',
+  'secret {',
+  '  name  = "uknows-otlp-headers"',
+  '  value = var.uknows_otlp_headers',
+  '}',
+  '',
+  'template {',
+  '  container {',
+  `    name = "${EXAMPLE_SERVICE}"`,
+  '    env {',
+  '      name        = "OTEL_EXPORTER_OTLP_HEADERS"',
+  '      secret_name = "uknows-otlp-headers"',
+  '    }',
+  '  }',
+  '}',
+].join('\n')
+
+export const HOSTS = [
+  {
+    id: 'azure-container-apps',
+    label: 'Azure Container Apps',
+    summary: 'Set the key as a secret on the container apps that you name.',
+    steps: [
+      AZURE_BASH_STEP,
+      'Sign in with az login.',
+      'Set SUBSCRIPTION, RESOURCE_GROUP and APPS at the top of the script. APPS is the list of apps that send data to UKNOWS. az account list -o table lists your subscriptions, and az containerapp list --subscription <subscription id> -g <resource group> --query "[].name" -o tsv lists the apps.',
+      'Run the script with DRY_RUN=1 first. It checks each app and says what it would change. It changes nothing.',
+      'Set DRY_RUN=0 and run it again. Paste your key when it asks. The key does not show on the screen.',
+      `Each app restarts with the key. ${QUIET_TIME}`,
+    ],
+    snippets: [
+      {
+        caption: 'Set the key on your container apps',
+        language: 'bash',
+        code: acaKeyScript(),
+      },
+    ],
+    notes: [
+      'Run the script on your own computer or in Azure Cloud Shell. Do not run it on a shared server. Other users of a shared server can see the commands that run, and the az command gets the key.',
+      'When you add a new app, run the script again with APPS set to the new app.',
+      'If an app has more than 1 container, add --container-name to the update command.',
+    ],
+    stricter: {
+      title: 'Stricter option: keep the key in Azure Key Vault',
+      summary: 'The key stays in Key Vault. Each app reads it with its managed identity. The key never passes through a terminal.',
+      steps: [
+        'In the Azure portal, open your key vault. Create a secret named uknows-otlp-headers. Set its value to x-uknows-key=<key>.',
+        'Turn on the system-assigned managed identity of each container app.',
+        'Give each identity the Key Vault Secrets User role on the key vault.',
+        'Set SUBSCRIPTION, RESOURCE_GROUP, APPS and SECRET_URI. Run the script with DRY_RUN=1 first. Then set DRY_RUN=0 and run it again at a quiet time.',
+      ],
+      snippets: [{ caption: 'Use the Key Vault secret on your container apps', language: 'bash', code: acaVaultScript() }],
+    },
+    checks: [
+      {
+        id: 'replace-env-vars',
+        text: `If your deploy runs az containerapp update with --replace-env-vars, that command replaces every environment variable. The next deploy removes the key reference. Add ${ACA_SECRET_REF} to that list.`,
+      },
+      {
+        id: 'deploy-action-env',
+        text: `If your workflow uses azure/container-apps-deploy-action with environmentVariables, the action replaces every environment variable too. Add ${ACA_SECRET_REF} to environmentVariables.`,
+      },
+      {
+        id: 'deploy-action-yaml',
+        text: 'If the deploy action uses yamlConfigPath, put the secret and the env entry in that YAML file. Otherwise each deploy drops them.',
+        snippets: [{ caption: 'Container Apps YAML', language: 'yaml', code: ACA_YAML }],
+      },
+      {
+        id: 'template',
+        text: 'If a Bicep or Terraform template deploys your container app, the template owns its environment variables and secrets. Add the secret and the env entry to the template, as a Key Vault reference, a @secure() parameter or a secret block. A change made only with az is undone the next time the template is applied.',
+        snippets: [
+          { caption: 'Bicep', language: 'bicep', code: ACA_BICEP },
+          { caption: 'Terraform', language: 'hcl', code: ACA_TERRAFORM },
+        ],
+      },
+      {
+        id: 'template-ignored',
+        text: 'If your Terraform template has lifecycle ignore_changes on the env or the secrets of the container app, terraform apply keeps what the app has. Then set the key with az, as the script above does. A change to the template does not reach this app.',
+      },
+      {
+        id: 'secret-first',
+        text: 'Set the secret on each app before the deploy that references it. A deploy that references a secret that is not there yet fails with ContainerAppSecretRefNotFound.',
+      },
+    ],
+  },
+  {
+    id: 'azure-app-service',
+    label: 'Azure App Service',
+    summary: 'Set the key as an app setting on the web apps that you name.',
+    steps: [
+      AZURE_BASH_STEP,
+      'Sign in with az login.',
+      'Set SUBSCRIPTION, RESOURCE_GROUP and APPS to your web apps at the top of the script. az account list -o table lists your subscriptions. Run the script with DRY_RUN=1 first. It checks each app and says what it would change.',
+      'Set DRY_RUN=0 and run it again. Paste your key when it asks. The key does not show on the screen.',
+      `App Service restarts each app with the key. ${QUIET_TIME}`,
+    ],
+    snippets: [
+      {
+        caption: 'Set the key on your web apps',
+        language: 'bash',
+        code: appServiceKeyScript(),
+      },
+    ],
+    notes: [
+      'Run the script on your own computer or in Azure Cloud Shell. Do not run it on a shared server. Other users of a shared server can see the commands that run, and the az command gets the key.',
+      'If your app does not start from your Dockerfile, add the 5 settings as app settings too.',
+      'For Python and .NET, put the start line of your stack in the startup command of the app.',
+      'If you swap a deployment slot into production, set the key on both slots as a slot setting, with --slot-settings instead of --settings. A swap moves the plain app settings with the code, and a slot setting stays with its slot. Add --slot with the name of the slot for that slot, and no --slot for production.',
+    ],
+    stricter: {
+      title: 'Stricter option: keep the key in Azure Key Vault',
+      summary: 'The key stays in Key Vault. Each app reads it with its managed identity. The key never passes through a terminal.',
+      steps: [
+        'In the Azure portal, open your key vault. Create a secret named uknows-otlp-headers. Set its value to x-uknows-key=<key>.',
+        'Turn on the system-assigned managed identity of each web app.',
+        'Give each identity the Key Vault Secrets User role on the key vault.',
+        'Set SUBSCRIPTION, RESOURCE_GROUP, APPS and SECRET_URI. Run the script with DRY_RUN=1 first. Then set DRY_RUN=0 and run it again at a quiet time.',
+      ],
+      snippets: [{ caption: 'Use the Key Vault secret on your web apps', language: 'bash', code: appServiceVaultScript() }],
+    },
+    checks: [
+      {
+        id: 'slot',
+        text: 'If you deploy to a slot, with slot-name in azure/webapps-deploy or with --slot, set the key on each slot as a slot setting, with --slot-settings. Then each slot keeps its own key when you swap.',
+      },
+    ],
+  },
+  {
+    id: 'azure-functions',
+    label: 'Azure Functions',
+    summary: 'The setup tool sets up a function app for you, for Node.js, Python and .NET. By hand: add 1 line to host.json, then set the 5 settings and your key as app settings of each function app.',
+    steps: [
+      'Run the setup tool in the repo of your function app. If the app does not send to the monitoring built into Azure, the tool adds 1 line to host.json. If it does, or the tool cannot tell, the tool adds small UKNOWS hooks to the code of the app instead, so that monitoring keeps showing what it shows now. Then it prints the app settings and the key steps for your function apps.',
+      'By hand, for an app that does not send to the monitoring built into Azure: in host.json, add "telemetryMode": "OpenTelemetry" next to "version", as in the example. Commit it and deploy as usual. The Functions host then sends a trace for each call of a function, and the logs. Your code needs no package.',
+      AZURE_BASH_STEP,
+      'Sign in with az login.',
+      'Set SUBSCRIPTION, RESOURCE_GROUP and APPS to your function apps at the top of both scripts. az account list -o table lists your subscriptions. Run the key script with DRY_RUN=1 first. It checks each app and says what it would change.',
+      'Set DRY_RUN=0 and run it again. Paste your key when it asks. The key does not show on the screen.',
+      'Run the settings script. A function app reads its settings from its app settings, not from a file in your repo, and keeps them when you deploy new code. Each app gets its own name in UKNOWS: the name of the function app.',
+      `Azure restarts each function app when its settings change. ${QUIET_TIME}`,
+    ],
+    snippets: [
+      {
+        caption: 'host.json: the line to add',
+        language: 'json',
+        code: ['{', '  "version": "2.0",', '  "telemetryMode": "OpenTelemetry"', '}'].join('\n'),
+      },
+      { caption: 'Set the key on your function apps', language: 'bash', code: functionsKeyScript() },
+      { caption: 'Add the 5 settings to your function apps', language: 'bash', code: functionsSettingsScript() },
+    ],
+    notes: [
+      'Run the scripts on your own computer or in Azure Cloud Shell. Do not run them on a shared server. Other users of a shared server can see the commands that run, and the az command gets the key.',
+      'Tested with Node.js, Python and .NET (isolated worker) function apps on Linux.',
+      'If the function app sends its data to the monitoring built into Azure (it has the app setting APPLICATIONINSIGHTS_CONNECTION_STRING), the line in host.json changes what that monitoring shows. It still gets the requests, but names each one by its route, such as GET api/orders/{id}, instead of the name of the function, and leaves out InvocationId. The function list under Monitor in the Azure portal, and your own queries and alerts on the function name, then change. So for such an app the setup tool adds the UKNOWS hooks instead. The hooks keep that monitoring exactly as it is, and send a span for each call of a function and the logs to UKNOWS, with the same trace id.',
+      'The hooks need the v4 programming model of Node.js, the v2 model of Python or the isolated worker of .NET. For an app on another model that sends to the monitoring built into Azure, the tool changes nothing and says why. To turn on the line in host.json anyway, run npx @uknows/setup --functions-opentelemetry.',
+      'A Python function app with the hooks also needs the app setting PYTHON_ENABLE_WORKER_EXTENSIONS=1. The setup tool lists it with the other app settings.',
+      'With the line in host.json, the log stream of the Azure portal no longer shows the logs of the app.',
+      'For a deployment slot, add --slot with the name of the slot to each az command.',
+    ],
+    stricter: {
+      title: 'Stricter option: keep the key in Azure Key Vault',
+      summary: 'The key stays in Key Vault. Each function app reads it with its managed identity. The key never passes through a terminal.',
+      steps: [
+        'In the Azure portal, open your key vault. Create a secret named uknows-otlp-headers. Set its value to x-uknows-key=<key>.',
+        'Turn on the system-assigned managed identity of each function app.',
+        'Give each identity the Key Vault Secrets User role on the key vault.',
+        'Set SUBSCRIPTION, RESOURCE_GROUP, APPS and SECRET_URI. Run the script with DRY_RUN=1 first. Then set DRY_RUN=0 and run it again at a quiet time.',
+      ],
+      snippets: [
+        {
+          caption: 'Use the Key Vault secret on your function apps',
+          language: 'bash',
+          code: [
+            '# Run in bash. This script never sees the key.',
+            '(',
+            ...dryRun('az functionapp show', 'It would restart the app.').map((line) => `  ${line}`),
+            '  SECRET_URI=https://my-vault.vault.azure.net/secrets/uknows-otlp-headers',
+            '  for APP in $APPS; do',
+            '    az functionapp config appsettings set --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP" -o none \\',
+            '      --settings "OTEL_EXPORTER_OTLP_HEADERS=@Microsoft.KeyVault(SecretUri=$SECRET_URI)" &&',
+            '    echo "Set the key on $APP."',
+            '  done',
+            ')',
+          ].join('\n'),
+        },
+      ],
+    },
+  },
+  {
+    id: 'aws-ecs',
+    label: 'AWS ECS and Fargate',
+    summary: 'Store the key in AWS Secrets Manager. Each task definition reads it as a secret.',
+    steps: [
+      AWS_BASH_STEP,
+      'Sign in to the AWS CLI, for example with aws sso login.',
+      'Run the script once for each environment. Paste your key when it asks. The script prints the ARN of the secret.',
+      'In the task definition of each app, add the secret to the container. Use the ARN that the script printed.',
+      'Let the task execution role of each app read the secret: it needs secretsmanager:GetSecretValue on it.',
+      `Register the new task definition. Then update the service to use it. ECS replaces the running tasks. ${QUIET_TIME}`,
+    ],
+    snippets: [
+      {
+        caption: 'Store the key in Secrets Manager',
+        language: 'bash',
+        code: keyScript(['SECRET_NAME=uknows-otlp-headers-prod'], [
+          "printf 'x-uknows-key=%s' \"$UKNOWS_KEY\" \\",
+          '  | aws secretsmanager create-secret --name "$SECRET_NAME" \\',
+          '      --secret-string file:///dev/stdin --query ARN --output text',
+        ]),
+      },
+      {
+        caption: 'Add the secret to the container in your task definition',
+        language: 'json',
+        code: [
+          '"secrets": [',
+          '  {',
+          '    "name": "OTEL_EXPORTER_OTLP_HEADERS",',
+          '    "valueFrom": "arn:aws:secretsmanager:<region>:<account>:secret:uknows-otlp-headers-prod-AbCdEf"',
+          '  }',
+          ']',
+        ].join('\n'),
+      },
+    ],
+    notes: [
+      'The key goes to the AWS CLI through a pipe, not as an argument. Other users of the computer cannot see it.',
+      'If your image does not have ENV lines for the 5 settings, add the 5 settings to the environment of the container in the task definition.',
+      'ECS reads the secret when a task starts. To change the key, store the new key with aws secretsmanager put-secret-value. Then update the service with --force-new-deployment.',
+      'You can use AWS Systems Manager Parameter Store instead. Store a SecureString parameter and put its ARN in valueFrom.',
+      'For EKS, use the Kubernetes steps. For EC2, use the VM steps.',
+    ],
+    checks: [
+      {
+        id: 'task-definition',
+        text: 'If your repo has the task definition JSON, add the secrets entry to that file and commit it. The ARN is not a secret.',
+      },
+    ],
+  },
+  {
+    id: 'kubernetes',
+    label: 'Kubernetes (any cluster)',
+    summary: 'Store the key in a Kubernetes secret. Load it into each deployment with envFrom.',
+    steps: [
+      BASH_STEP,
+      'Create the secret once in each namespace that runs your apps. Paste your key when the script asks.',
+      'Add envFrom to each deployment. Commit this change with the 5 settings.',
+      'If your image does not have ENV lines for the 5 settings, add them to env in the deployment too.',
+      'Apply the deployment. Kubernetes starts new pods with the key.',
+    ],
+    snippets: [
+      {
+        caption: 'Create the secret',
+        language: 'bash',
+        code: keyScript(['NAMESPACE=orders'], [
+          "printf 'x-uknows-key=%s' \"$UKNOWS_KEY\" \\",
+          '  | kubectl create secret generic uknows -n "$NAMESPACE" \\',
+          '      --from-file=OTEL_EXPORTER_OTLP_HEADERS=/dev/stdin --dry-run=client -o yaml \\',
+          '  | kubectl apply -f -',
+        ]),
+      },
+      {
+        caption: 'Load the secret in your deployment',
+        language: 'yaml',
+        code: [
+          '# Adds OTEL_EXPORTER_OTLP_HEADERS from the uknows secret.',
+          'spec:',
+          '  template:',
+          '    spec:',
+          '      containers:',
+          `        - name: ${EXAMPLE_SERVICE}`,
+          '          envFrom:',
+          '            - secretRef:',
+          '                name: uknows',
+          '                optional: true',
+        ].join('\n'),
+      },
+      {
+        caption: 'The 5 settings in your deployment, if your image does not have them',
+        language: 'yaml',
+        code: [
+          'spec:',
+          '  template:',
+          '    spec:',
+          '      containers:',
+          `        - name: ${EXAMPLE_SERVICE}`,
+          '          env:',
+          ...SETTINGS.flatMap((setting) => [`            - name: ${setting.name}`, `              value: ${setting.value}`]),
+        ].join('\n'),
+      },
+      {
+        caption: 'Helm: the same in values.yaml, if your chart passes env and envFrom to the container',
+        language: 'yaml',
+        code: [
+          '# Charts differ. Use the keys that your chart reads.',
+          'env:',
+          ...SETTINGS.flatMap((setting) => [`  - name: ${setting.name}`, `    value: ${setting.value}`]),
+          'envFrom:',
+          '  - secretRef:',
+          '      name: uknows',
+          '      optional: true',
+        ].join('\n'),
+      },
+    ],
+    notes: [
+      'The same steps work on any cluster: Amazon EKS, Azure AKS, Google GKE, Alibaba ACK and your own clusters.',
+      'The key goes to kubectl through a pipe, not as an argument. Other users of the computer cannot see it.',
+      'To change the key, run the script again. Then run kubectl rollout restart for each deployment.',
+    ],
+    checks: [
+      {
+        id: 'optional',
+        text: 'The envFrom lines mark the secret optional: true, so a missing secret never stops pods from starting. Create the secret first. Pods that start without it send no data to UKNOWS.',
+      },
+    ],
+  },
+  {
+    id: 'alibaba-sae',
+    label: 'Alibaba Cloud SAE',
+    summary: 'Store the key in an SAE secret. Reference it in the environment variables of each app.',
+    steps: [
+      'Open the SAE console. Select the region and namespace of your apps.',
+      'Create a secret named uknows with the key and value below.',
+      'Open each app. Edit its environment variables.',
+      'Add a variable named OTEL_EXPORTER_OTLP_HEADERS. Make it reference the secret uknows and the key OTEL_EXPORTER_OTLP_HEADERS.',
+      'If your image does not have ENV lines for the 5 settings, add the 5 settings as environment variables too.',
+      'Deploy the app. SAE restarts it with the key.',
+    ],
+    snippets: [
+      {
+        caption: 'Secret content',
+        language: 'text',
+        code: ['Secret name: uknows', 'Key: OTEL_EXPORTER_OTLP_HEADERS', `Value: ${SECRET.value}`].join('\n'),
+      },
+    ],
+    notes: [
+      'Replace <key> with your key in the SAE console. Do not put the key in a file or a chat.',
+      'SAE restarts the app when you deploy. Deploy at a quiet time.',
+    ],
+  },
+  {
+    id: 'vm-docker',
+    label: 'Any VM or Docker',
+    summary: `Store the key in ${KEY_FILE} on each host. Load the file when the app starts.`,
+    steps: [
+      'On each host, run the script in bash. Paste your key when it asks.',
+      `The script creates ${KEY_FILE}. Only root can read it.`,
+      `For Docker, add --env-file ${KEY_FILE} to docker run.`,
+      `For systemd, add EnvironmentFile=${KEY_FILE} to the service.`,
+      'Restart the app.',
+      'At the end of each deploy, run the deploy marker below on the host. It tells UKNOWS that a deploy happened, so UKNOWS can warn you when a deploy stops the data of your app. On an Azure VM it finds the resource id of the machine by itself.',
+    ],
+    snippets: [
+      {
+        caption: 'Create the key file',
+        language: 'bash',
+        code: keyScript([], [
+          `sudo touch ${KEY_FILE}`,
+          `sudo chmod 600 ${KEY_FILE}`,
+          `printf 'OTEL_EXPORTER_OTLP_HEADERS=x-uknows-key=%s\\n' "$UKNOWS_KEY" | sudo tee ${KEY_FILE} > /dev/null &&`,
+          `echo "Saved the key in ${KEY_FILE}."`,
+        ], 'Run in bash on each host'),
+      },
+      {
+        caption: 'Docker',
+        language: 'bash',
+        code: ['# Loads OTEL_EXPORTER_OTLP_HEADERS from the key file.', `sudo docker run -d --env-file ${KEY_FILE} ${EXAMPLE_SERVICE}:latest`].join('\n'),
+      },
+      {
+        caption: 'systemd service',
+        language: 'ini',
+        code: [
+          '[Service]',
+          `# The 5 settings, from ${SETTINGS_FILE.path} in your repo.`,
+          `EnvironmentFile=/opt/${EXAMPLE_SERVICE}/${SETTINGS_FILE.path}`,
+          '# Loads OTEL_EXPORTER_OTLP_HEADERS from the key file.',
+          `EnvironmentFile=${KEY_FILE}`,
+        ].join('\n'),
+      },
+      { caption: 'Mark each deploy', language: 'bash', code: vmDeployMarker() },
+    ],
+    notes: [
+      'Docker reads the file as the user that runs docker. Run docker with sudo or as root.',
+      'If your image does not have ENV lines for the 5 settings, add --env-file otel.env to docker run too.',
+      `For Docker Compose, add env_file: ${KEY_FILE} to the service.`,
+      'After you change a systemd service, run sudo systemctl daemon-reload. Then restart the service.',
+      `If you start the app from a shell as a user that is not root, make that user the owner of the key file: sudo chown <user> ${KEY_FILE}.`,
+      'The same steps work on any Linux VM or server: Amazon EC2, Azure VMs, Google Compute Engine, Alibaba ECS and servers in your own data center.',
+    ],
+  },
+  {
+    id: 'github-actions',
+    label: 'GitHub Actions',
+    summary: 'Store the key as a GitHub environment secret, once for each environment. Your deploy workflow sets it on your app.',
+    steps: [
+      'Install the GitHub CLI. Sign in with gh auth login.',
+      'Run the command once for each GitHub environment that your deploy jobs use. Paste the key of that environment when it asks. Paste the key only, without x-uknows-key=. The key does not show on the screen.',
+      'Add the step below to each deploy job, before its deploy step. It reads the secret and sets the key on your app. The example is for Azure Container Apps.',
+    ],
+    snippets: [
+      { caption: 'Set the environment secret', language: 'bash', code: githubSecretCommands() },
+      { caption: 'Set the key in your deploy workflow', language: 'yaml', code: githubKeyStep() },
+      { caption: 'Or: 1 organization secret for many repos', language: 'bash', code: `gh secret set UKNOWS_KEY --org ${EXAMPLE_NAMES.org} --visibility private` },
+    ],
+    notes: [
+      `Replace ${EXAMPLE_NAMES.repo} with your repo, and ${EXAMPLE_NAMES.environment} with the environment: name of your deploy job. Never rename an environment that your workflows use: its other secrets and variables stay with the old name.`,
+      `A job can read an environment secret only when it has an environment: line. If your deploy job has none, do not add one just for the key. A job that signs in to Azure with OpenID Connect then signs in as environment:<name> instead of ref:refs/heads/<branch>, and azure/login fails until the Azure identity trusts that name. Either add a federated credential for environment:<name> to the identity first, or store the key as a repository secret: gh secret set UKNOWS_KEY --repo ${EXAMPLE_NAMES.repo}.`,
+      `Each environment has its own key. gh secret set UKNOWS_KEY --env ${EXAMPLE_NAMES.environment} sets the key for ${EXAMPLE_NAMES.environment} only. For staging, run it again with --env staging and the staging key.`,
+      'An organization secret holds 1 key. Use it only when all the repos that read it deploy to the same environment.',
+      '--visibility private shares the organization secret with the private repos of the organization. Public repos cannot use it.',
+      `To share it with some repos only, use --visibility selected --repos ${EXAMPLE_SERVICE},payments instead.`,
+      `In the example, replace ${EXAMPLE_NAMES.resourceGroup} and ${EXAMPLE_SERVICE} with your resource group and app.`,
+      `The app must load the secret. Make your deploy command set ${ACA_SECRET_REF}, as the Azure Container Apps script does. If the command has --set-env-vars already, add the pair to that list: az uses only the last --set-env-vars.`,
+      'On other platforms, pass the secret the same way to the step that sets your app settings.',
+    ],
+    checks: [
+      {
+        id: 'guard',
+        text: 'The step above fails the job when the UKNOWS_KEY secret is empty, so the app is never deployed without the key. It sets the key on the app first. Then your deploy step adds the env entry that reads it.',
+      },
+    ],
+  },
+]
+
+/** Said plainly, on the page and in llms.txt. */
+export const SERVERLESS = 'Azure Functions works: the setup tool sets up Node.js, Python and .NET function apps, and its tab has the steps by hand. AWS Lambda, Google Cloud Functions and Alibaba Function Compute are not supported yet. Apps in containers, on Kubernetes and on VMs work.'
+
+/**
+ * What the setup tool says when the check cannot reach UKNOWS. The site check can pass and the upload to the ingest
+ * address still fail: they are 2 addresses. The tool fills in {host}, {port} and {seconds}.
+ */
+export const CHECK_NETWORK = {
+  keyFine: 'The key is fine, but the test span did not reach UKNOWS.',
+  timeout: 'This computer cannot reach {host} on port {port}: no answer in {seconds} seconds.',
+  refused: '{host} refused the connection on port {port}.',
+  reset: 'The connection to {host} closed before UKNOWS answered.',
+  unreachable: 'This computer cannot reach {host}. Check its network.',
+  dns: 'This computer cannot find {host} in DNS. Check DNS, or the proxy that this computer must use.',
+  other: 'This computer cannot reach {host} ({code}).',
+  ask: 'Ask your network team to allow outbound HTTPS to {host} on port {port}.',
+  where: 'This check tests the network of this computer. Your apps need the same address from where they run. To test that, run the network check in "Check your key" on a host of your app.',
+  proxy: 'This tool does not use HTTPS_PROXY. Run the check on a network that can reach UKNOWS directly.',
+}
+
+const KEY_ANSWERS                       = [
+  { answer: '"workspace" and "environment"', meaning: 'The key works. It sends data to that workspace and environment.' },
+  { answer: '"keyState": "retiring"', meaning: 'The key still works until the time in "retiresAt". A new key replaced it. Set the new key.' },
+  { answer: 'ingest_key_invalid', meaning: 'UKNOWS does not know this key. Copy the whole key again, with no spaces or quotes. An Admin or an Engineer of your workspace can show it again in Settings › Keys.' },
+  { answer: 'ingest_key_revoked', meaning: 'The key no longer works. An Admin revoked it, a new key replaced it, or its environment was turned off. Get a new key from an Admin of your workspace.' },
+  { answer: 'workspace_paused', meaning: 'Your workspace is paused. Talk to us to start it again.' },
+  { answer: 'rate_limited', meaning: 'Too many checks from your address. Wait 1 minute.' },
+  { answer: `No answer from ${INGEST_HOST}`, meaning: `The key can still be fine. This computer cannot reach ${INGEST_HOST} on port 443. Ask your network team to allow outbound HTTPS to ${INGEST_HOST}, then check again.` },
+  { answer: `Cannot find ${INGEST_HOST}`, meaning: `This computer cannot find ${INGEST_HOST} in DNS. Check DNS, or the proxy that this computer must use.` },
+]
+
+/**
+ * Check a key before you deploy: the ping route of the site says which
+ * workspace and environment the key sends to, or why it is refused. A second
+ * line checks that a host reaches the ingest address.
+ */
+export const KEY_CHECK = {
+  id: 'check-key',
+  title: 'Check your key',
+  summary: 'Check the key before you deploy. Then you know that the key works, and for which workspace and environment.',
+  steps: [
+    'Run the script in bash on your own computer. Paste your key when it asks. The key does not show on the screen.',
+    'Read the answer. The list below says what each answer means.',
+    'Run the network check on a host that runs your app.',
+  ],
+  snippet: {
+    caption: 'Check the key',
+    language: 'bash',
+    code: keyScript([], [
+      `printf '${SECRET.header}: %s\\n' "$UKNOWS_KEY" | curl -sS -H @- ${PING_URL}`,
+      'echo',
+    ]),
+  },
+  answers: KEY_ANSWERS,
+  network: {
+    caption: 'Check that your app can reach UKNOWS',
+    language: 'bash',
+    code: `curl -sS -o /dev/null -w '%{http_code}\\n' https://${INGEST_HOST}/otlp/v1/traces`,
+  },
+  networkText: 'Any 3-digit number means the host reaches UKNOWS. 000 or an error means it cannot. Then check DNS, the firewall and any proxy.',
+}
+
+/**
+ * How to load otel.env when the app does not start from a Dockerfile with the
+ * ENV lines. The Dockerfile ENV lines stay the main path.
+ */
+export const SETTINGS_FILE_LOADERS = [
+  {
+    id: 'shell',
+    label: 'Plain start',
+    summary: `Load the file and the key file in the shell that starts your app. Then run the start line for your stack. The key file belongs to root. Run the start as root. Or make the app user the owner with sudo chown <user> ${KEY_FILE}, then run the start as that user. Do not use chmod to let more users read the key file.`,
+    snippet: {
+      caption: 'Load the settings and the key, then start the app',
+      language: 'bash',
+      code: [
+        '# Run in bash, in the folder of the service.',
+        `# Run as root, or as the owner of ${KEY_FILE}. Only they can read it.`,
+        'set -a',
+        `. ./${SETTINGS_FILE.path}        # the 5 settings`,
+        `. ${KEY_FILE}   # the key file from "${STEP_TITLES.secret}"`,
+        'set +a',
+        '# Now run the start line for your stack.',
+      ].join('\n'),
+    },
+  },
+  {
+    id: 'systemd',
+    label: 'systemd',
+    summary: 'Add the file and the key file to the service. Then restart the service.',
+    snippet: {
+      caption: 'systemd service',
+      language: 'ini',
+      code: [
+        '[Service]',
+        `# The 5 settings, from ${SETTINGS_FILE.path} in your repo.`,
+        `EnvironmentFile=/opt/${EXAMPLE_SERVICE}/${SETTINGS_FILE.path}`,
+        `# The key file from "${STEP_TITLES.secret}".`,
+        `EnvironmentFile=${KEY_FILE}`,
+      ].join('\n'),
+    },
+  },
+  {
+    id: 'docker',
+    label: 'Docker',
+    summary: 'If your Dockerfile does not have the ENV lines, pass the file and the key file to docker run.',
+    snippet: {
+      caption: 'docker run',
+      language: 'bash',
+      code: [
+        '# Loads the 5 settings and the key.',
+        `sudo docker run -d --env-file ${SETTINGS_FILE.path} --env-file ${KEY_FILE} ${EXAMPLE_SERVICE}:latest`,
+      ].join('\n'),
+    },
+  },
+  {
+    id: 'alibaba-sae',
+    label: 'Alibaba Cloud SAE',
+    summary: `Open each app in the SAE console. Add the 5 settings as environment variables. If your stack has a line that loads OpenTelemetry, add it too. Then set the key as "${STEP_TITLES.secret}" says.`,
+    snippet: {
+      caption: 'Environment variables',
+      language: 'text',
+      code: SETTINGS_ENV,
+    },
+    listsSettings: true,
+  },
+]
+
+/**
+ * When the setup tool finds no Dockerfile, no Kubernetes file and no file in the repo that loads otel.env, it adds
+ * no file. It prints the settings in the form of the platform instead. The page does not show these.
+ */
+export const SETTINGS_ELSEWHERE = {
+  title: 'Add these settings where your app runs',
+  why: `This tool found no Dockerfile, no Kubernetes file and no file in your repo that loads ${SETTINGS_FILE.path}. So it did not add ${SETTINGS_FILE.path}.`,
+  /** Instead of why, when the repo has Dockerfiles that this tool did not pick for this service. It fills in {dockerfiles}. */
+  notPicked: `This tool did not pick a Dockerfile for this service. It saw {dockerfiles}. It also found no Kubernetes file and no file in your repo that loads ${SETTINGS_FILE.path}, so it did not add ${SETTINGS_FILE.path}.`,
+  steps: [
+    'Add these settings to the environment of your app, where it runs. Use the form for your platform below.',
+    `Or add ${SETTINGS_FILE.path} with these lines next to your app, and load it when the app starts: EnvironmentFile= in a systemd service, env_file: in Docker Compose, --env-file in docker run, or . ./${SETTINGS_FILE.path} in a start script. Then run npx @uknows/setup again. It keeps the file up to date.`,
+  ],
+  /** A repo file loads otel.env, so the setup tool adds the settings there. It fills in {file}, {line} and {path}. */
+  loaded: '{file} line {line} loads {path}, so this tool adds the settings to {path}.',
+}
+
+/** The settings in the form of 1 platform, for SETTINGS_ELSEWHERE. app is the name of the app on the platform. */
+export function settingsSnippet(host, pairs, app = EXAMPLE_SERVICE, names = {}) {
+  const env = pairs.map(([name, value]) => `${name}=${value}`)
+  // names.slot (App Service only): the settings go on that deployment slot, as the deploy of the repo does.
+  const az = (command        , flag        , slot = false) => [
+    '# Run in bash.',
+    ...azureNames({ ...names, app: names.app ?? app, slot: slot ? names.slot : undefined }, true).filter((line) => !line.startsWith('[')),
+    `${command} --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP"${slot && names.slot ? ' --slot "$SLOT"' : ''} -o none ${flag} \\`,
+    env.map((line) => `  "${line}"`).join(' \\\n'),
+  ].join('\n')
+  switch (host) {
+    case 'azure-app-service':
+      return { caption: 'App settings of your web app', language: 'bash', code: az('az webapp config appsettings set', '--settings', true) }
+    case 'azure-functions':
+      return { caption: 'App settings of your function app', language: 'bash', code: az('az functionapp config appsettings set', '--settings') }
+    case 'azure-container-apps':
+      return { caption: 'Environment variables of your container app', language: 'bash', code: az('az containerapp update', '--set-env-vars') }
+    case 'aws-ecs':
+      return { caption: 'The environment of the container in your task definition', language: 'json',
+        code: ['"environment": [', pairs.map(([name, value]) => `  { "name": "${name}", "value": "${value}" }`).join(',\n'), ']'].join('\n') }
+    case 'kubernetes':
+      return { caption: 'The env of the container in your deployment', language: 'yaml',
+        code: ['env:', ...pairs.flatMap(([name, value]) => [`  - name: ${name}`, `    value: "${value}"`])].join('\n') }
+    case 'alibaba-sae':
+      return { caption: 'Environment variables of your app in the SAE console', language: 'text', code: env.join('\n') }
+    default:
+      return { caption: 'The settings', language: 'text', code: env.join('\n') }
+  }
+}
+
+/** Where a person checks their key in their own terminal: the key check of the Reference. */
+export const KEY_CHECK_URL = `${DOCS_URL}/reference#check`
+
+/** What a person chose for the AI prompt: the name of the app in UKNOWS, and the environment of the key they will use. */
+
+/** The app name as OTEL_SERVICE_NAME takes it: lower case letters, digits, dots, dashes and underscores. Empty when none. */
+export function serviceName(raw) {
+  return raw.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, 63)
+}
+
+/**
+ * The prompt a person copies into an AI coding assistant. It has this build's
+ * addresses and the app and environment the person chose. It never contains a
+ * key: the person gets and stores the key with the key command, in their own terminal.
+ */
+export function aiPrompt({ app = '', env = 'Staging' }           = {}) {
+  const name = serviceName(app)
+  const named = name ? ` --service-name ${name}` : ''
+  return [
+    'Set up UKNOWS monitoring in this repo with the UKNOWS setup tool.',
+    `First read ${LLMS_URL} and follow its "Rules for AI assistants".`,
+    '',
+    `1. In the root folder of the repo, run: ${setupCommand(` --dry-run --json${named}`)}`,
+    '   It changes nothing. Show me the plan: each service, each file it changes and the packages it adds.',
+    `2. When I say yes, run: ${setupCommand(` --yes${named}`)}`,
+    '   It makes exactly the change in the plan and asks nothing. If setup stops, change nothing and tell me why.',
+    '3. Build the project and run its tests.',
+    '4. Commit the change, with .uknows/setup.json, on a new branch. Open a pull request named "Add UKNOWS monitoring".',
+    '5. Do not deploy, and do not change business logic.',
+    '',
+    'Never ask me for my UKNOWS key, and never write, print or commit it.',
+    `When you are done, tell me to run ${setupCommand(' key')} in my own terminal, in this repo. I sign in and choose ${env}. Then it checks my ${env} key and stores it where the app runs.`,
+    `Then I merge and deploy as usual, and watch ${name || 'the app'} connect at ${CONNECT_URL}?app=${name || '<app name>'}.`,
+  ].join('\n')
+}
+
+export const TROUBLESHOOTING = [
+  {
+    id: 'no-data',
+    problem: 'No data after 10 minutes',
+    steps: [
+      'Send a few requests to your app. UKNOWS shows the requests that your app gets.',
+      'Restart or redeploy the app after you set the key.',
+      'Compare the names and values of the 5 settings with this page.',
+      'Check the key, as "Check your key" says.',
+      'Open Settings › Keys. It shows the uploads UKNOWS rejected for each key, and why.',
+      `Make sure that the app can reach ${INGEST_HOST} on port 443.`,
+      'Remove OTEL_SDK_DISABLED, or set it to false.',
+      'Read the app log for OpenTelemetry export errors. Some SDKs log nothing when UKNOWS refuses the key.',
+    ],
+  },
+  {
+    id: 'unauthorized',
+    problem: 'The key is not accepted (401)',
+    cause: 'UKNOWS does not accept the key. The key is wrong or in the wrong format, or it was revoked. Your app may not show this. Some OpenTelemetry SDKs, Node.js among them, drop the 401 and log nothing.',
+    steps: [
+      'Check the key, as "Check your key" says. It says if the key is invalid or revoked.',
+      'Open Settings › Keys. It shows the uploads UKNOWS rejected for each key, and why.',
+      'If an Admin revoked the key, an Admin creates a new key there.',
+      'Copy the key again. Set the secret again.',
+      'Use the format x-uknows-key=<key>. Remove spaces and quotes.',
+      'Restart the app.',
+    ],
+  },
+  {
+    id: 'forbidden',
+    problem: 'The app log shows 403 (access stopped)',
+    cause: 'Your workspace is paused. A revoked or unknown key gets 401, not 403.',
+    steps: [
+      'Talk to us to start the workspace again.',
+    ],
+  },
+  {
+    id: 'too-many',
+    problem: 'The app log shows 429 (too many requests)',
+    cause: 'Each key can send 200 requests a second, with short bursts up to 400. Your apps sent more.',
+    steps: [
+      'Keep the batch settings of OpenTelemetry. They send many traces in 1 request.',
+      'Talk to us if your apps need more.',
+    ],
+  },
+  {
+    id: 'missing-jobs',
+    problem: 'Queue consumers or batch jobs do not show',
+    cause: 'UKNOWS drops traces that have links. Queue consumers and batch jobs often add links.',
+    steps: [
+      'Check the requests of the same app. They still show.',
+      'Talk to us if you need these traces. We are working on it.',
+    ],
+  },
+  {
+    id: 'low-counts',
+    problem: 'UKNOWS shows fewer requests than your app gets',
+    cause: 'Your app samples traces. UKNOWS counts only the requests that it gets.',
+    steps: [
+      'Remove OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG, or set OTEL_TRACES_SAMPLER=parentbased_always_on.',
+      'Remove any sampler from the OpenTelemetry code of the app.',
+      'Restart the app.',
+    ],
+  },
+  {
+    id: 'other-apm',
+    problem: 'Your app already uses another APM agent',
+    cause: '2 tracing agents in 1 app can conflict.',
+    steps: [
+      'Use 1 tracing agent in each app.',
+      'Remove the other agent, or turn off its tracing, before you add UKNOWS.',
+      'If your app already uses OpenTelemetry, use the steps for "I already use OpenTelemetry".',
+    ],
+  },
+  {
+    id: 'turn-off',
+    problem: 'Turn monitoring off',
+    steps: [
+      'Set OTEL_SDK_DISABLED=true on the platform.',
+      'Restart the app.',
+      'For .NET, set OTEL_DOTNET_AUTO_TRACES_ENABLED=false and OTEL_DOTNET_AUTO_LOGS_ENABLED=false.',
+      'If your app also sends to the monitoring built into Azure, remove OTEL_EXPORTER_OTLP_ENDPOINT instead, then restart the app. That turns UKNOWS off and keeps that monitoring. OTEL_SDK_DISABLED=true would stop it too.',
+      'To turn monitoring on again, remove the setting and restart the app.',
+    ],
+  },
+]
+
+/**
+ * Help that only the setup tool prints, when it stops for what it found in a repo. The pages leave it out: it names
+ * the products that the tool finds, and the public pages name UKNOWS only.
+ */
+export const SETUP_TROUBLESHOOTING = [
+  {
+    id: 'otel-wrapper',
+    problem: 'A library in your app brings its own OpenTelemetry',
+    cause: 'A library that is not standard OpenTelemetry, such as a telemetry library of your company, brings OpenTelemetry and can limit its version. Standard OpenTelemetry can conflict with it.',
+    steps: [
+      'Remove that library and the code that calls it. Then your app can use standard OpenTelemetry.',
+      'Or ask the owners of the library to allow a newer OpenTelemetry version.',
+    ],
+  },
+  {
+    id: 'app-insights-classic',
+    problem: 'Your app uses an Application Insights SDK that UKNOWS cannot join',
+    cause: 'UKNOWS can add its exporter only beside the Azure Monitor OpenTelemetry packages. It cannot join the .NET SDK 2.x, the Node.js applicationinsights package 2.x, OpenCensus for Python, the Java agent or the codeless attach of App Service.',
+    steps: [
+      'Move to the Azure Monitor OpenTelemetry package for your language: Azure.Monitor.OpenTelemetry.AspNetCore for .NET, @azure/monitor-opentelemetry for Node.js or azure-monitor-opentelemetry for Python.',
+      'Then keep Azure Monitor and add UKNOWS beside it. Use the steps in "Your app uses Azure Monitor?".',
+    ],
+  },
+]
+
+/**
+ * How many days UKNOWS keeps workspace data. This is an owner decision. The
+ * trace store keeps traces for 7 or 15 days by default, so no number is
+ * promised yet. Until the owner picks a number and the store is set and
+ * checked, this stays null and the page gives no number. Set it to the
+ * decided number of days, for example 30.
+ */
+export const RETENTION_DAYS = null
+
+/** The signals UKNOWS checks every minute for an alert: Refused and Throttled, and the scan and revoked-key alerts
+    when the owner turned them on. */
+export function checkedEveryMinute() {
+  const alerts = ['Refused', 'Throttled', ...(SCAN_ALERT ? ['scans'] : []), ...(REVOKED_KEY_ALERT ? ['uploads with a revoked key'] : [])]
+  return `${alerts.slice(0, -1).join(', ')} and ${alerts[alerts.length - 1]}`
+}