@uknows/setup 0.1.0 → 0.2.0

package/lib/stacks/index.mjs

@@ -5,6 +5,14 @@ import { dotnet } from './dotnet.mjs'
 import { java } from './java.mjs'
 import { go, php, ruby } from './guided.mjs'
 import { otel } from './otel.mjs'
+import { azure } from './azure.mjs'
+import { channel } from './channel.mjs'
+import { functions } from './functions.mjs'
 
-/** @type {Record<import('../types.mjs').StackId, import('../types.mjs').Applier>} */
-export const APPLIERS = { node, python, dotnet, java, go, php, ruby, otel }
+/**
+ * azure is not a stack of the docs: the engine uses it for every service in azure-monitor mode. channel is the agent
+ * channel (--channel): the engine uses it for a Java, .NET or Node.js service with a Dockerfile in channel mode.
+ * functions: an Azure Functions app (Node.js, Python or .NET isolated) in standard mode: 1 line in host.json.
+ * @type {Record<import('../types.mjs').StackId|'azure'|'channel', import('../types.mjs').Applier>}
+ */
+export const APPLIERS = { node, python, dotnet, java, go, php, ruby, otel, azure, channel, functions }

package/lib/stacks/java.mjs

@@ -1,15 +1,16 @@
-// Java: add the pinned OpenTelemetry Java agent to the final image with the docs ADD line (Docker checks
-// the checksum) and load it with JAVA_TOOL_OPTIONS. Build files are never touched. Both lines go after
-// the last RUN, so build steps (mvn, gradle) never load the agent.
+// Java: copy the pinned OpenTelemetry Java agent into the final image with the docs COPY --from line
+// (the image digest pins the jar) and load it with JAVA_TOOL_OPTIONS. Build files are never touched.
+// Both lines go after the last RUN, so build steps (mvn, gradle) never load the agent.
 import { JAVA_AGENT, STACKS } from '../contract.mjs'
 import { addOption, insertBeforeStart, parseDockerfile } from '../dockerfile.mjs'
 import { envOverrides } from './k8s.mjs'
 
 const DOCS = STACKS.find((s) => s.id === 'java')
-const ADD_LINE = DOCS.dockerfile.split('\n').find((l) => l.startsWith('ADD '))
-// Earlier /docs gave --chmod=644. BuildKit also gives that mode to the /otel folder it creates, so a
-// non-root USER cannot load the agent and the JVM stops. A Dockerfile with that exact line gets the new one.
-const OLD_ADD_LINE = ADD_LINE.replace('--chmod=755', '--chmod=644')
+const COPY_LINE = DOCS.dockerfile.split('\n').find((l) => l.startsWith('COPY --from='))
+// 0.1.0 wrote an ADD line with --checksum and --chmod, which need BuildKit. Earlier /docs gave --chmod=644.
+// A Dockerfile with one of those exact lines gets the COPY line instead.
+const ADD_LINE = `ADD --checksum=sha256:${JAVA_AGENT.sha256} --chmod=755 ${JAVA_AGENT.url} /otel/${JAVA_AGENT.file}`
+const OLD_LINES = [ADD_LINE, ADD_LINE.replace('--chmod=755', '--chmod=644')]
 const AGENT_OPTION = /JAVA_TOOL_OPTIONS="([^"]+)"/.exec(DOCS.dockerfile)[1]
 const AGENT_PATH = AGENT_OPTION.replace(/^-javaagent:/, '')
 const note = (re) => DOCS.notes.find((n) => re.test(n))
@@ -35,19 +36,19 @@ export const java = {
     }
     const has = (value) => value.includes(AGENT_OPTION)
     plan.manual.push(...envOverrides(service, 'JAVA_TOOL_OPTIONS', AGENT_OPTION, has))
-    const fixed = text.split(OLD_ADD_LINE).join(ADD_LINE)
-    const added = fixed.includes(JAVA_AGENT.url) || fixed.includes(AGENT_PATH) ? fixed : insertBeforeStart(fixed, [ADD_LINE])
+    const fixed = OLD_LINES.reduce((out, line) => out.split(line).join(COPY_LINE), text)
+    const added = [JAVA_AGENT.url, JAVA_AGENT.image, AGENT_PATH].some((s) => fixed.includes(s)) ? fixed : insertBeforeStart(fixed, [COPY_LINE])
     const after = addOption(added, 'JAVA_TOOL_OPTIONS', AGENT_OPTION, has)
     if (after === text) return plan
     if (after === fixed) {
-      plan.edits.push({ file: service.dockerfile, before: text, after, why: 'Let a non-root user load the OpenTelemetry Java agent.' })
-      plan.summary.push(`Give the agent folder in ${service.dockerfile} mode 755, so an app that runs as a non-root user can load the agent.`)
+      plan.edits.push({ file: service.dockerfile, before: text, after, why: 'Copy the OpenTelemetry Java agent from the pinned image.' })
+      plan.summary.push(`Replace the ADD line of the agent in ${service.dockerfile} with a COPY line from the pinned OpenTelemetry image. It needs no BuildKit.`)
       return plan
     }
     plan.edits.push({ file: service.dockerfile, before: text, after, why: 'Add the OpenTelemetry Java agent and load it when the JVM starts.' })
-    plan.summary.push(`Add the OpenTelemetry Java agent ${JAVA_AGENT.version} to ${service.dockerfile}. Docker checks its checksum.`,
+    plan.summary.push(`Add the OpenTelemetry Java agent ${JAVA_AGENT.version} to ${service.dockerfile}, from the image pinned by its digest.`,
       `Load the agent when the JVM starts (JAVA_TOOL_OPTIONS in ${service.dockerfile}).`)
-    plan.notes.push(note(/Docker 25/))
+    plan.notes.push(note(/digest pins/))
     if (info.env.has('JAVA_TOOL_OPTIONS') || info.inherited.has('JAVA_TOOL_OPTIONS')) {
       plan.notes.push(`${service.dockerfile} already sets JAVA_TOOL_OPTIONS. A new ENV line before the start keeps that value and adds the agent.`)
     }

package/lib/stacks/node.mjs

@@ -1,22 +1,37 @@
 /*
  * Node.js: add @opentelemetry/api and @opentelemetry/auto-instrumentations-node
- * with the package manager of the repo, then load the register module when
- * node starts: NODE_OPTIONS in the Dockerfile, or the option right after
- * `node` in scripts.start.
+ * with the package manager of the repo, then load OpenTelemetry when node
+ * starts: NODE_OPTIONS in the Dockerfile, or the option right after `node` in
+ * scripts.start.
+ *
+ * It loads the start file uknows-otel.cjs (install.ts NODE_REGISTER_FILE), which
+ * this tool adds next to package.json: it stops the app cleanly on SIGTERM after
+ * the last data. In an image, a COPY line in the final stage puts it in the
+ * WORKDIR. When the build context, the WORKDIR or .dockerignore makes that
+ * unsure, it loads the upstream register line instead and says why.
  *
  * Safety rule: node crashes at start when the register module is missing, so
  * the start changes only when the packages surely reach the running app.
  * Package managers run with install scripts turned off, so no code of the
  * project or its dependencies runs.
  */
+import { buildContext, finalWorkdir, ignoredBy } from '../context.mjs'
+import { unpicked } from '../settings.mjs'
 import { Doc, shellWords } from '../doc.mjs'
-import { addOption, dockerStart, parseDockerfile } from '../dockerfile.mjs'
-import { NODE_REGISTER, PINS, STACKS } from '../contract.mjs'
+import { addOption, dockerStart, insertBeforeStart, parseDockerfile } from '../dockerfile.mjs'
+import { NODE_REGISTER, NODE_REGISTER_FILE, NODE_START_FILE, PINS, RESOLVE, STACKS } from '../contract.mjs'
 import { list } from '../ui.mjs'
 import { upFrom } from '../workspace.mjs'
 import { envOverrides } from './k8s.mjs'
 
 const STACK = STACKS.find((s) => s.id === 'node')
+const START_FILE = NODE_REGISTER_FILE.path
+const START_TEXT = `${NODE_REGISTER_FILE.content}\n`
+/** The docs option for the start file. Its steps go in the advice when this tool cannot add the file. */
+const SIGTERM = STACK.options.find((o) => o.title.startsWith('Stops cleanly on SIGTERM'))
+/** A NODE_OPTIONS value or a start script that loads OpenTelemetry already: the upstream register or the start file. */
+const loads = (value) => value.includes(NODE_REGISTER) || value.includes(START_FILE)
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
 const LOCKS = [['package-lock.json', 'npm'], ['npm-shrinkwrap.json', 'npm'], ['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'],
   ['bun.lockb', 'bun'], ['bun.lock', 'bun']]
 const DEFAULT_LOCK = { npm: 'package-lock.json', pnpm: 'pnpm-lock.yaml', yarn: 'yarn.lock' }
@@ -59,10 +74,15 @@ export const node = {
     const script = typeof pkg.scripts?.start === 'string' ? pkg.scripts.start : null
     const entry = entryOf(info ? start?.argv : service.start?.argv ?? shellWords(script ?? ''), script)
     const esm = /\.m[jt]s$/.test(entry ?? '') || (pkg.type === 'module' && !/\.c[jt]s$/.test(entry ?? ''))
-    const flag = esm ? PINS.node.esmFlag : PINS.node.requireFlag
+    const flag = PINS.node.flag(esm)
 
     const guided = guidedBlock(service, ws, pkg, info, entry, flag)
     if (guided) { out.manual.push(guided); return out }
+    // The docs settings for Node.js: only the resource detectors that ask no cloud metadata address (NETWORK.node).
+    for (const line of STACK.extraSettings?.lines ?? []) {
+      const at = line.indexOf('=')
+      out.extraSettings.push({ name: line.slice(0, at), value: line.slice(at + 1) })
+    }
     const pm = packageManager(service.dir, pkg, ctx.repo ?? ws)
     if (pm.outside) {
       out.manual.push({ title: 'Run setup from the repo root', lines: [
@@ -83,10 +103,18 @@ export const node = {
       return out
     }
     const added = wanted.filter((name) => !pkg.dependencies?.[name])
+    // npm here writes the lock that npm ci in the image reads: a newer npm than the image has stops the run.
+    const npmBlock = added.length && pm.cmd === 'npm' && pm.lock && info ? npmGuard(service, info, ctx.tools?.npm) : null
+    if (npmBlock) {
+      out.manual.push(npmBlock)
+      out.stop = true
+      return out
+    }
     if (added.length) {
       const lock = pm.lock ?? (pm.cmd === 'npm' ? null : join(service.dir, DEFAULT_LOCK[pm.cmd]))
-      // No install scripts. npm with a lockfile and pnpm write only package.json and the lockfile.
-      const flags = pm.cmd === 'npm' ? ['--ignore-scripts', pm.lock ? '--package-lock-only' : '--no-package-lock']
+      // No install scripts, no audit and no funding lines (they are about the app, not this change). npm with a
+      // lockfile and pnpm write only package.json and the lockfile.
+      const flags = pm.cmd === 'npm' ? ['--ignore-scripts', '--no-audit', '--no-fund', pm.lock ? '--package-lock-only' : '--no-package-lock']
         : pm.cmd === 'pnpm' ? ['--lockfile-only', ...(ws.exists(join(service.dir, 'pnpm-workspace.yaml')) ? ['-w'] : [])]
           : [pm.berry ? '--mode=skip-build' : '--ignore-scripts']
       const why = `Add ${list(added)} with ${pm.cmd}.`
@@ -96,29 +124,45 @@ export const node = {
         undo: { cmd: pm.cmd, args: [pm.cmd === 'npm' ? 'uninstall' : 'remove', ...flags, ...added] },
         touches: [pkgFile, ...(lock ? [lock] : [])] })
       out.summary.push(why)
-      if (lockOnly) out.notes.push(`To start the app on this computer, run ${pm.cmd} install first. Your build installs the packages from ${base(lock)}.`)
+      if (lockOnly) out.notes.push(`${pm.cmd} updates only package.json and ${base(lock)} here, so node_modules on this computer does not have the new packages yet. Run ${pm.cmd} install before you start the app on this computer. Your build installs them from ${base(lock)}.`)
     }
 
     if (info) {
       const runsNode = start && (start.argv ?? [start.raw]).flatMap((w) => w.split(/\s+/)).some((w) => RUNS_NODE.test(base(w.replace(/^["']|["']$/g, ''))))
       if (!runsNode) out.manual.push(startBlock(flag, entry, `the start command in ${service.dockerfile}`))
       else {
-        const has = (value) => value.includes(NODE_REGISTER)
-        const after = addOption(docker, 'NODE_OPTIONS', flag, has)
+        const current = info.env.get('NODE_OPTIONS') ?? info.inherited.get('NODE_OPTIONS')
+        const done = Boolean(current && loads(current.value))
+        const place = done ? null : placeStartFile(service, ctx.repo ?? ws, info, ctx)
+        const option = place?.path ? PINS.node.flag(esm, place.path) : flag
+        let after = docker
+        if (place?.path) {
+          addStartFile(out, ws, place.file)
+          const copied = info.final.some((x) => (x.keyword === 'COPY' || x.keyword === 'ADD') && x.args.includes(START_FILE))
+          if (!copied) after = insertBeforeStart(after, [place.copy])
+        } else if (place) {
+          out.manual.push({ title: SIGTERM.title, required: false, lines: [place.why, NODE_START_FILE.fallback, ...SIGTERM.steps], snippets: SIGTERM.snippets })
+        }
+        after = addOption(after, 'NODE_OPTIONS', option, loads)
         if (after !== docker) {
-          out.edits.push({ file: service.dockerfile, before: docker, after, why: 'Load OpenTelemetry when node starts.' })
+          out.edits.push({ file: service.dockerfile, before: docker, after, why: place?.path ? `Load OpenTelemetry when node starts. ${NODE_START_FILE.copy}` : 'Load OpenTelemetry when node starts.' })
           out.summary.push(`Load OpenTelemetry when node starts (NODE_OPTIONS in ${service.dockerfile}).`)
-          if (info.env.has('NODE_OPTIONS') || info.inherited.has('NODE_OPTIONS')) {
+          if (current) {
             out.notes.push(`${service.dockerfile} already sets NODE_OPTIONS. A new ENV line before the start keeps that value and adds the option.`)
           }
         }
-        out.manual.push(...envOverrides(service, 'NODE_OPTIONS', flag, has))
+        out.manual.push(...envOverrides(service, 'NODE_OPTIONS', option, loads))
       }
     } else if (script !== null && service.start?.kind !== 'procfile' && shellWords(script)?.[0] === 'node') {
-      if (!script.includes(NODE_REGISTER)) {
-        const after = editStartScript(pkgText, flag)
+      if (!loads(script)) {
+        // npm start runs the script in the package folder, so ./uknows-otel.cjs is the file next to package.json.
+        // The start file is only for a start that surely has it: no Dockerfile that could build this app without it, not ignored by git.
+        const unsure = scriptStartUnsure(service, ctx)
+        const after = editStartScript(pkgText, unsure ? flag : PINS.node.flag(esm, `./${START_FILE}`))
         if (after === null) out.manual.push(startBlock(flag, entry, `scripts.start in ${pkgFile}`))
         else {
+          if (unsure) out.manual.push({ title: SIGTERM.title, required: false, lines: [unsure, NODE_START_FILE.fallback, ...SIGTERM.steps], snippets: SIGTERM.snippets })
+          else addStartFile(out, ws, join(service.dir, START_FILE))
           out.edits.push({ file: pkgFile, before: pkgText, after, why: 'Load OpenTelemetry when node starts.' })
           out.summary.push(`Load OpenTelemetry when node starts (start script in ${pkgFile}).`)
         }
@@ -130,6 +174,85 @@ export const node = {
   },
 }
 
+/**
+ * Where the start file goes in the image: {file, path, copy}, or {why} when this tool is not sure. The file sits
+ * next to package.json. The COPY line takes it from the build context into the WORKDIR of the final stage.
+ */
+function placeStartFile(service, view, info, ctx = {}) {
+  const file = join(service.dir, START_FILE)
+  const values = { file, dockerfile: service.dockerfile }
+  const workdir = finalWorkdir(info)
+  if (!workdir) return { why: fill(NODE_START_FILE.noWorkdir, values) }
+  const context = buildContext(view, service.dockerfile, info, service.dir)
+  if (context === null) return { why: fill(NODE_START_FILE.noContext, values) }
+  if (context !== '.' && !file.startsWith(`${context}/`)) return { why: fill(NODE_START_FILE.outside, values) }
+  const source = context === '.' ? file : file.slice(context.length + 1)
+  const ignore = ignoredBy(view, context, service.dockerfile, source)
+  if (ignore) return { why: fill(NODE_START_FILE.ignored, { ...values, ignore }) }
+  // The pipeline builds from a checkout: a file that git ignores never reaches it, and the COPY line fails there.
+  if (!read(view, file) && ctx.ignored?.(file)) return { why: fill(NODE_START_FILE.gitignored, values) }
+  const dir = workdir === '/' ? '' : workdir
+  return { file, path: `${dir}/${START_FILE}`, copy: `COPY ${source} ${dir}/` }
+}
+
+/**
+ * Why a start script must not load the start file, or null when it can: git ignores the file, so a checkout lacks it,
+ * or the repo has a Dockerfile that this tool did not pick for any service (an image built from it would not copy the
+ * file, and node stops at start when a --require file is missing). The upstream register line has no such file.
+ */
+function scriptStartUnsure(service, ctx) {
+  const view = ctx.repo ?? ctx.ws
+  const file = join(service.dir, START_FILE)
+  if (!read(view, file) && ctx.ignored?.(file)) return fill(NODE_START_FILE.gitignored, { file })
+  const others = unpicked(ctx)
+  return others.length ? fill(NODE_START_FILE.dockerfiles, { file, dockerfiles: list(others.slice(0, 5)) }) : null
+}
+
+/** Add the start file when it is not there. A file that is there stays as it is: it can be the user's own copy. */
+function addStartFile(out, ws, file) {
+  const current = read(ws, file)
+  if (current === null) {
+    out.edits.push({ file, before: null, after: START_TEXT, why: fill(NODE_START_FILE.add, { file }) })
+    out.summary.push(fill(NODE_START_FILE.add, { file }))
+  } else if (current !== START_TEXT) out.notes.push(fill(NODE_START_FILE.keep, { file }))
+}
+
+/**
+ * A required step when npm on this computer is newer (by major version) than the npm of the image that runs npm ci:
+ * the npm of a RUN npm install -g npm@X line, else the npm that the node image of that stage comes with (PINS.node.npm).
+ * null when the versions fit or are not known.
+ */
+export function npmGuard(service, info, have) {
+  const haveMajor = Number(/^(\d+)\./.exec(have ?? '')?.[1] ?? NaN)
+  if (!Number.isFinite(haveMajor)) return null
+  const runs = (stage) => stage.instructions.filter((x) => x.keyword === 'RUN')
+  const text = (x) => (x.argv ? x.argv.join(' ') : x.args)
+  let image = null, line = null, need = null
+  for (const stage of info.stages) {
+    for (const x of runs(stage)) {
+      const pin = /\bnpm\s+(?:install|i)\s+(?:-g|--global)\s+npm@(\d+)/.exec(text(x))
+      if (pin) { need = Number(pin[1]); image = `npm@${pin[1]}`; line = x.start + 1 }
+    }
+  }
+  if (need === null) {
+    const stages = info.stages, byName = new Map(stages.filter((st) => st.name).map((st) => [st.name.toLowerCase(), st]))
+    const stage = stages.find((st) => runs(st).some((x) => /\bnpm\s+(?:ci|install|i)\b/.test(text(x)))) ?? stages.at(-1)
+    if (!stage) return null
+    let from = stage.image
+    for (let hop = 0; hop < 5 && byName.has(from.toLowerCase()); hop++) from = byName.get(from.toLowerCase()).image
+    const m = /(?:^|\/)node:(\d+)(?:\.(\d+))?/.exec(from)
+    if (!m) return null
+    const v = [Number(m[1]), m[2] === undefined ? 99 : Number(m[2])]
+    need = PINS.node.npm.find(([[a, b]]) => v[0] > a || (v[0] === a && v[1] >= b))?.[1] ?? null
+    image = from
+    line = (info.instructions.find((x) => x.keyword === 'FROM' && x.args.split(/\s+/).includes(stage.image))?.start ?? 0) + 1
+  }
+  if (need === null || haveMajor <= need) return null
+  const values = { file: service.dockerfile, line, image, need, have }
+  const fill = (t) => t.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+  return { title: fill(RESOLVE.npm.title), lines: RESOLVE.npm.lines.map(fill) }
+}
+
 /** Cases where loading the register module cannot work: guided only, no packages. */
 function guidedBlock(service, ws, pkg, info, entry, flag) {
   if (service.frameworks.includes('next')) {
@@ -140,7 +263,7 @@ function guidedBlock(service, ws, pkg, info, entry, flag) {
     const install = info.final.some((x) => x.keyword === 'RUN' && /\b(npm (ci|install|i)|pnpm (install|i)|yarn)\b/.test(x.args))
     const copies = info.final.filter((x) => x.keyword === 'COPY' || x.keyword === 'ADD')
     if (!install && !copies.some((x) => /node_modules/.test(x.args) || !/\.output/.test(x.args))) {
-      return { title: 'Put node_modules in the final image', lines: [`The final stage of ${service.dockerfile} copies only the built server, so node cannot load OpenTelemetry.`,
+      return { title: 'Put node_modules in the final image', verify: true, lines: [`The final stage of ${service.dockerfile} copies only the built server, so node cannot load OpenTelemetry.`,
         'Install the packages in the final stage, or copy node_modules into it.', 'Then run npx @uknows/setup again.'] }
     }
   }
@@ -160,7 +283,7 @@ function guidedBlock(service, ws, pkg, info, entry, flag) {
  * The search goes on above the --path folder, up to the top of the git repo (view.top). A workspace root or
  * its lockfile up there is `outside`: this tool cannot update it.
  */
-function packageManager(dir, pkg, view) {
+export function packageManager(dir, pkg, view) {
   const field = typeof pkg.packageManager === 'string' ? /^(npm|pnpm|yarn|bun)@(\d+)/.exec(pkg.packageManager) : null
   let cmd = field ? field[1] : typeof pkg.packageManager === 'string' ? 'other' : null
   let lock = null, outside = null
@@ -181,7 +304,7 @@ function packageManager(dir, pkg, view) {
 }
 
 /** The JS file that node runs, from a start argv. `npm start` and friends read scripts.start. */
-function entryOf(argv, script) {
+export function entryOf(argv, script) {
   let words = argv ?? null
   if (words && /^(npm|yarn|pnpm)$/.test(base(words[0])) && (words[1] === 'start' || (words[1] === 'run' && words[2] === 'start'))) words = shellWords(script ?? '')
   if (!words?.length) return null

package/lib/stacks/otel.mjs

@@ -1,11 +1,63 @@
-// The app already uses OpenTelemetry: keep its packages and start command. settings.mjs adds the 5 settings.
-import { STACKS } from '../contract.mjs'
+// The app already uses OpenTelemetry: keep its packages and start command. settings.mjs adds the 3 shared
+// settings (no none lines, so the metrics and logs of the app keep going where they go now).
+import { AZURE_MONITOR, DOCS_URL, DOTNET_TRACES_ONLY, INGEST_ENDPOINT, OTHER_EXPORTERS_NOTE, STACKS, TRACES_ONLY_NOTE, TRACES_ONLY_PLAN } from '../contract.mjs'
+
+const STACK = STACKS.find((s) => s.id === 'otel')
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+
+/**
+ * The notes of the docs page, and after its .NET note the 2 notes that only setup prints: the pages name UKNOWS only,
+ * and these name products that setup finds in a repo.
+ */
+export const OTEL_NOTES = STACK.notes.flatMap((n) => (n === DOTNET_TRACES_ONLY.note ? [n, AZURE_MONITOR.otelNote, OTHER_EXPORTERS_NOTE] : [n]))
+
+/** The notes that name languages or features. A run keeps the parts that fit what it found. */
+const NOTE = {
+  /** "For Python, use ... For Go, use ...": 1 sentence for each language. */
+  exporter: OTEL_NOTES.find((n) => /^For Python, use /.test(n)),
+  collector: OTEL_NOTES.find((n) => /Collector/.test(n)),
+  azure: AZURE_MONITOR.otelNote,
+}
+/** The label that each sentence of NOTE.exporter starts with. */
+const EXPORTER_LANG = { python: 'Python', go: 'Go' }
+/** The SDKs that send metrics and logs over OTLP by default. settings.mjs uses the traces-only settings for them. */
+const SDK_SIGNALS = new Set(['node', 'python', 'java'])
+
+/**
+ * The notes of the docs page for this run. With no language known (the menu pick "I already use OpenTelemetry"),
+ * every note stays. Else only the notes for this language and for what the repo uses:
+ *   - the exporter sentence of this language only (Python, Go),
+ *   - the traces-only note only when settings.mjs did not already say what this run does with traces only,
+ *     and in a form for this language,
+ *   - the .NET note only for .NET, and only when this run does not use the traces-only settings,
+ *   - the Azure Monitor note only when the code calls Azure Monitor,
+ *   - the other-exporters note never: existing.mjs gives it as advice when the repo has another exporter.
+ * @param {string[]} notes
+ * @param {{lang?: string|null, existing?: Partial<import('../types.mjs').Existing>, tracesOnly?: boolean, endpoint?: string, docs?: string}} found
+ *   endpoint and docs: the ingest address and the docs page of this run.
+ * @returns {string[]}
+ */
+export function otelNotes(notes, { lang = null, existing = {}, tracesOnly = false, endpoint = INGEST_ENDPOINT, docs = DOCS_URL } = {}) {
+  if (!lang) return notes
+  const anchors = existing.anchors ?? []
+  return notes.flatMap((note) => {
+    if (note === NOTE.exporter) {
+      const label = EXPORTER_LANG[lang]
+      return note.split(/(?<=\.) (?=For )/).filter((sentence) => label && sentence.startsWith(`For ${label}, `))
+    }
+    if (note === NOTE.collector) return [`${note} See ${docs}?method=manual&stack=otel#install-app.`]
+    if (note === TRACES_ONLY_NOTE) return tracesOnly || SDK_SIGNALS.has(lang) ? [] : [fill(TRACES_ONLY_PLAN.none, { endpoint })]
+    if (note === DOTNET_TRACES_ONLY.note) return lang === 'dotnet' && !tracesOnly ? [note] : []
+    if (note === NOTE.azure) return anchors.some((a) => a.kind === 'azure-call' || a.kind === 'appinsights-call') ? [note] : []
+    if (note === OTHER_EXPORTERS_NOTE) return []
+    return [note]
+  })
+}
 
 /** @type {import('../types.mjs').Applier} */
 export const otel = {
   id: 'otel',
   plan() {
-    return { summary: ['Keep your OpenTelemetry packages. Point them at UKNOWS with the 5 settings.'], edits: [], commands: [],
-      extraSettings: [], manual: [], notes: [...STACKS.find((s) => s.id === 'otel').notes] }
+    return { summary: [STACK.summary], edits: [], commands: [], extraSettings: [], manual: [], notes: [...OTEL_NOTES] }
   },
 }

package/lib/stacks/python-bootstrap.mjs

@@ -7,11 +7,17 @@
  *
  * Left out on purpose: openai-v2 and vertexai (not pinned to 0.66b1),
  * psutil -> system-metrics (metrics are off) and the upstream quirk that maps
- * pydantic to tortoiseorm.
+ * pydantic to tortoiseorm. The default logging package comes only with the UKNOWS
+ * log bridge (logs: true). On its own, in 0.66b1, it adds an OpenTelemetry
+ * LoggingHandler to the root logger, also with OTEL_LOGS_EXPORTER=none. Then Python
+ * never uses its last-resort handler, so the warnings and errors of loggers with no
+ * handler no longer reach stderr. With the bridge, OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION
+ * =false keeps it off the root logger and the package gives only its LoggingHandler.
  */
+import { compareVersion } from '../versions.mjs'
 
 /** Always printed. */
-export const DEFAULTS = ['asyncio', 'dbapi', 'exceptions', 'logging', 'sqlite3', 'threading', 'urllib', 'wsgi']
+export const DEFAULTS = ['asyncio', 'dbapi', 'exceptions', 'sqlite3', 'threading', 'urllib', 'wsgi']
 
 /** [normalized library name, instrumentation suffixes], in upstream order. */
 export const LIBRARIES = [
@@ -29,6 +35,15 @@ export const LIBRARIES = [
   ['tortoise-orm', ['tortoiseorm']], ['urllib3', ['urllib3']],
 ]
 
+/**
+ * The first contrib release of each instrumentation package on PyPI (tools/check-python-sets.mjs). A set older than
+ * this leaves the package out, because it does not exist there. Packages missing here are older than every set.
+ */
+export const SINCE = { exceptions: '0.64b0', structlog: '0.65b0', asyncclick: '0.53b0', pymssql: '0.51b0', click: '0.50b0',
+  aiokafka: '0.49b0', threading: '0.46b0', psycopg: '0.45b0', asyncio: '0.44b0', 'aiohttp-server': '0.42b0', cassandra: '0.41b0',
+  mysqlclient: '0.40b0', tortoiseorm: '0.36b0', 'aio-pika': '0.32b0', boto3sqs: '0.32b0', 'confluent-kafka': '0.32b0',
+  remoulade: '0.32b0', 'kafka-python': '0.28b0', pika: '0.25b0', httpx: '0.23b0', urllib3: '0.20b0', urllib: '0.17b0' }
+
 /** Packages that a framework always installs, so upstream would see them too. */
 export const IMPLIED = { fastapi: ['starlette'], django: ['asgiref'], flask: ['jinja2'], requests: ['urllib3'], boto3: ['botocore'] }
 
@@ -37,15 +52,20 @@ export const normalize = (name) => name.toLowerCase().replace(/[-_.]+/g, '-')
 
 /**
  * The instrumentation packages for these requirement names: the defaults,
- * then 1 per matching library in table order, without repeats.
+ * then 1 per matching library in table order, without repeats. Packages that
+ * are newer than version (SINCE) are left out.
  * @param {Iterable<string>} names  normalized requirement names
- * @param {string} version          e.g. '0.66b1'
+ * @param {string} version          the contrib release of the set, e.g. '0.66b1'
+ * @param {{floor?: string|null, logs?: boolean}} [options]  floor: write '>=' limits from this release (or the first
+ *   release of the package, when it is newer) instead of '==' pins, for uv and Poetry projects. logs: add the logging
+ *   package, for the UKNOWS log bridge
  * @returns {string[]} e.g. ['opentelemetry-instrumentation-asyncio==0.66b1', ...]
  */
-export function bootstrap(names, version) {
+export function bootstrap(names, version, { floor = null, logs = false } = {}) {
   const have = new Set(names)
   for (const name of [...have]) for (const extra of IMPLIED[name] ?? []) have.add(extra)
-  const suffixes = [...DEFAULTS]
+  const suffixes = [...DEFAULTS, ...(logs ? ['logging'] : [])]
   for (const [library, list] of LIBRARIES) if (have.has(library)) suffixes.push(...list)
-  return [...new Set(suffixes)].map((x) => `opentelemetry-instrumentation-${x}==${version}`)
+  return [...new Set(suffixes)].filter((x) => !SINCE[x] || compareVersion(SINCE[x], version) <= 0)
+    .map((x) => `opentelemetry-instrumentation-${x}${floor ? `>=${[floor, SINCE[x] ?? floor].sort(compareVersion).at(-1)}` : `==${version}`}`)
 }

package/lib/stacks/python-lock.mjs

@@ -0,0 +1,105 @@
+/*
+ * The lock refresh of uv and Poetry projects (uv lock in the workspace root, poetry lock), shared by the Python and
+ * the Azure Monitor appliers. The tool on this computer writes the lock, and the image reads it, so the run stops
+ * with a required step when:
+ *   - the lock is above the --path folder (the command would write outside it),
+ *   - the tool is missing (the engine probed it: ctx.tools[tool] === null),
+ *   - it does not meet [tool.uv] required-version (or uv.toml), [tool.poetry] requires-poetry, or the version that
+ *     the Dockerfile pins (COPY --from=ghcr.io/astral-sh/uv:0.11.29, pip install uv==X, the astral.sh/uv/<version>/install.sh
+ *     installer with ENV UV_VERSION, POETRY_VERSION).
+ * After the run, the engine rolls back when the lockfile format line changed (keep): version = N in uv.lock,
+ * lock-version in poetry.lock. An older tool in the image cannot read a newer format.
+ */
+import { posix } from 'node:path'
+import { RESOLVE } from '../contract.mjs'
+import { parseDockerfile } from '../dockerfile.mjs'
+import { tomlString, tomlTable } from '../toml.mjs'
+import { satisfies } from '../versions.mjs'
+
+/** Lockfile name -> tool. PDM has no automatic refresh. */
+export const LOCK_TOOLS = { 'uv.lock': 'uv', 'poetry.lock': 'poetry' }
+const KEEP = { 'uv.lock': '^version = \\d+$', 'poetry.lock': '^lock-version = "[^"]*"$' }
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+const read = (view, path) => { try { return view.read(path) } catch { return null } }
+const at = (dir, name) => (dir === '.' ? name : `${dir}/${name}`)
+
+/**
+ * The lock command for lockFile, or the required step that replaces it.
+ * @param {{view: any, lockFile: string, tools?: Record<string, string|null>, dockerfile?: string|null, docker?: string|null, packages: string}} opts
+ *   packages: what the lock adds, for the required step ('the OpenTelemetry packages').
+ * @returns {{command: import('../types.mjs').Command}|{block: import('../types.mjs').Block}|null}  null for a lockfile with no tool (pdm.lock).
+ */
+export function lockStep({ view, lockFile, tools, dockerfile = null, docker = null, packages }) {
+  const name = posix.basename(lockFile), tool = LOCK_TOOLS[name]
+  if (!tool) return null
+  const dir = posix.dirname(lockFile)
+  const version = tools && Object.prototype.hasOwnProperty.call(tools, tool) ? tools[tool] : undefined
+  const poetry1 = tool === 'poetry' && /^1\./.test(version ?? '')
+  const args = poetry1 ? ['lock', '--no-update'] : ['lock']
+  const command = [tool, ...args].join(' ')
+  if (lockFile.startsWith('../')) {
+    return { block: { title: RESOLVE.outside.title, lines: RESOLVE.outside.lines.map((l) => fill(l, { lock: lockFile, command, dir })) } }
+  }
+  const needs = toolNeeds(view, dir, tool, dockerfile, docker)
+  const pinned = needs.find((n) => n.exact)
+  const block = (reason) => ({ title: fill(RESOLVE.tool.title, { tool, version: pinned ? ` ${pinned.version}` : '' }),
+    lines: [fill(RESOLVE.tool.why, { lock: lockFile, tool, packages }), reason,
+      fill(RESOLVE.tool.install, { tool, version: pinned ? ` ${pinned.version}` : '' }), RESOLVE.again] })
+  if (version === null) return { block: block(fill(RESOLVE.tool.missing, { tool })) }
+  if (version) {
+    const unmet = needs.find((n) => !satisfies(version, n.spec))
+    if (unmet) {
+      return { block: block(fill(unmet.line ? RESOLVE.tool.image : RESOLVE.tool.version,
+        { file: unmet.file, line: unmet.line, tool, need: unmet.version ?? unmet.spec, have: version })) }
+    }
+  }
+  return { command: { cwd: dir, cmd: tool, args, touches: [lockFile], added: [], kind: 'lock', undo: null,
+    keep: [{ file: lockFile, pattern: KEEP[name] }], why: fill(RESOLVE.update, { lock: name, command }) } }
+}
+
+/**
+ * The versions of the tool that the project asks for: required-version (uv) or requires-poetry in the pyproject.toml
+ * next to the lock, uv.toml, and the version the Dockerfile installs. exact: a pinned image or package version.
+ * @returns {{spec: string, version?: string, file: string, line?: number, exact: boolean}[]}
+ */
+export function toolNeeds(view, dir, tool, dockerfile, docker) {
+  const out = []
+  const pyproject = read(view, at(dir, 'pyproject.toml'))
+  if (tool === 'uv') {
+    const spec = tomlString(tomlTable(pyproject ?? '', 'tool.uv'), 'required-version')
+    if (spec) out.push({ spec, file: at(dir, 'pyproject.toml'), exact: false })
+    const own = tomlString(read(view, at(dir, 'uv.toml')) ?? '', 'required-version')
+    if (own) out.push({ spec: own, file: at(dir, 'uv.toml'), exact: false })
+  } else {
+    const spec = tomlString(tomlTable(pyproject ?? '', 'tool.poetry'), 'requires-poetry')
+    if (spec) out.push({ spec, file: at(dir, 'pyproject.toml'), exact: false })
+  }
+  if (docker && dockerfile) {
+    const image = tool === 'uv' ? /\bghcr\.io\/astral-sh\/uv:(\d+(?:\.\d+){0,2})(?=[\s@-]|$)/ : null
+    const pip = new RegExp(`\\bpip3?\\s+install\\b[^\\n&|;]*?["']?\\b${tool}==(\\d+(?:\\.\\d+){1,2})\\b`)
+    const env = tool === 'poetry' ? /\bPOETRY_VERSION=["']?(\d+(?:\.\d+){1,2})\b/ : null
+    // The versioned installer script: astral.sh/uv/0.11.29/install.sh, or astral.sh/uv/${UV_VERSION}/install.sh with an
+    // ENV or ARG UV_VERSION line before it.
+    const script = tool === 'uv' ? /astral\.sh\/uv\/(?:\$\{?UV_VERSION\}?|(\d+(?:\.\d+){1,2}))\/install\.sh/ : null
+    const instructions = parseDockerfile(docker).instructions
+    const uvVersion = (upTo) => instructions.slice(0, upTo).filter((y) => y.keyword === 'ENV' || y.keyword === 'ARG')
+      .map((y) => ({ y, m: /\bUV_VERSION=["']?(\d+(?:\.\d+){1,2})\b/.exec(y.args) })).filter((e) => e.m).at(-1) ?? null
+    for (const [k, x] of instructions.entries()) {
+      const text = x.argv ? x.argv.join(' ') : x.args
+      let m = (image && (x.keyword === 'FROM' || x.keyword === 'COPY') && image.exec(text)) || (x.keyword === 'RUN' && pip.exec(text))
+        || (env && (x.keyword === 'ENV' || x.keyword === 'ARG') && env.exec(text))
+      let at = x
+      const run = !m && script && x.keyword === 'RUN' ? script.exec(text) : null
+      if (run) {
+        const found = run[1] ? null : uvVersion(k)
+        m = run[1] ? run : found?.m ?? null
+        at = found?.y ?? x
+      }
+      if (!m) continue
+      const v = m[1]
+      out.push({ spec: v.split('.').length < 3 ? `==${v}.*` : `==${v}`, version: v, file: dockerfile, line: at.start + 1, exact: true })
+      break
+    }
+  }
+  return out
+}