Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

fix(web): derive Faro labels from native build inputs (#1033)

Genereaaaddca147a
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0cb499438..bd8456695 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,6 +24,14 @@ This starts the web app and workers locally. To work on the CLI separately:
pnpm dev:cli
```
+### Frontend telemetry build configuration
+
+`NEXT_PUBLIC_FARO_COLLECTOR_URL` is the only manual Faro setting. Supply it to the Web and Blog build environments when enabling their existing consent-controlled telemetry.
+
+Both apps derive environment from `NODE_ENV` and source release from the first valid full Git SHA in `WORKERS_CI_COMMIT_SHA`, `CF_PAGES_COMMIT_SHA`, then `GITHUB_SHA`. Next embeds these values at build time. Worker runtime variables do not change an existing browser bundle.
+
+`NEXT_PUBLIC_FARO_RELEASE` and `NEXT_PUBLIC_FARO_ENVIRONMENT` are generated build outputs for the browser and the Web Worker's first-request snapshot. Do not configure them: both Next configs overwrite them from the native build inputs. Missing or invalid source identity remains `release_status=missing`; package versions and Worker version IDs do not replace a Git SHA. Environment validation keeps the existing telemetry allowlist.
+
## Project Structure
Alook is a monorepo with nine packages:
diff --git a/src/web/blog/next.config.ts b/src/web/blog/next.config.ts
index bd3482d6e..7a71fca0c 100644
--- a/src/web/blog/next.config.ts
+++ b/src/web/blog/next.config.ts
@@ -9,9 +9,15 @@ const blogRedirectRules = JSON.parse(
readFileSync(path.resolve(__dirname, "src/lib/blog/redirects.json"), "utf8"),
) as Array<{ source: string; destination: string; statusCode: 301 }>;
const pkg = JSON.parse(readFileSync(path.resolve(__dirname, "../package.json"), "utf8"));
+const { resolveObservationBuild } = createRequire(path.resolve(__dirname, "next.config.ts"))("../src/lib/observability/build.ts") as typeof import("@/lib/observability/build");
+const observation = resolveObservationBuild(process.env);
const nextConfig: NextConfig = {
- env: { NEXT_PUBLIC_APP_VERSION: pkg.version },
+ env: {
+ NEXT_PUBLIC_APP_VERSION: pkg.version,
+ NEXT_PUBLIC_FARO_RELEASE: observation.release ?? "",
+ NEXT_PUBLIC_FARO_ENVIRONMENT: observation.environment ?? "",
+ },
assetPrefix: "/blog-static",
images: { unoptimized: true },
pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"],
diff --git a/src/web/blog/scripts/frontend-version.test.ts b/src/web/blog/scripts/frontend-version.test.ts
index 05ddb94a9..aba72b196 100644
--- a/src/web/blog/scripts/frontend-version.test.ts
+++ b/src/web/blog/scripts/frontend-version.test.ts
@@ -1,14 +1,80 @@
import { readFileSync } from "node:fs"
+import { execFileSync } from "node:child_process"
import { fileURLToPath } from "node:url"
-import { expect, it, vi } from "vitest"
+import { afterEach, expect, it, vi } from "vitest"
vi.mock("@next/mdx", () => ({ default: () => (config: unknown) => config }))
vi.mock("@opennextjs/cloudflare", () => ({ initOpenNextCloudflareForDev: vi.fn() }))
+vi.mock("node:module", async importOriginal => {
+ const original = await importOriginal<typeof import("node:module")>()
+ const build = await import("../../src/lib/observability/build")
+ return {
+ ...original,
+ createRequire: (filename: Parameters<typeof original.createRequire>[0]) => {
+ const require = original.createRequire(filename)
+ return Object.assign((id: string) => id === "../src/lib/observability/build.ts" ? build : require(id), require)
+ },
+ }
+})
+
+afterEach(() => { vi.unstubAllEnvs(); vi.resetModules() })
+
+function loadBuildConfigs(mode: string, source: string) {
+ const output = execFileSync(process.execPath, ["-e", `
+ const path = require("node:path");
+ const { transpileConfig } = require("next/dist/build/next-config-ts/transpile-config");
+ (async () => {
+ const configs = [];
+ for (const app of [".", "blog"]) {
+ const dir = path.resolve(app);
+ const loaded = await transpileConfig({ nextConfigPath: path.join(dir, "next.config.ts"), dir });
+ const config = typeof loaded.default === "function" ? await loaded.default() : loaded.default;
+ configs.push({ env: config.env, assetPrefix: config.assetPrefix });
+ }
+ console.log("FARO_BUILD_CONFIG=" + JSON.stringify(configs));
+ process.exit(0);
+ })().catch(error => { console.error(error); process.exit(1); });
+ `], {
+ cwd: fileURLToPath(new URL("../../", import.meta.url)),
+ encoding: "utf8",
+ env: { ...process.env, NODE_ENV: mode, WORKERS_CI_COMMIT_SHA: source, CF_PAGES_COMMIT_SHA: "", GITHUB_SHA: "",
+ NEXT_PUBLIC_FARO_RELEASE: "c".repeat(40), NEXT_PUBLIC_FARO_ENVIRONMENT: "qa" },
+ })
+ const encoded = output.split("\n").find(line => line.startsWith("FARO_BUILD_CONFIG="))!
+ return JSON.parse(encoded.slice("FARO_BUILD_CONFIG=".length)) as Array<{ env: Record<string, string>; assetPrefix?: string }>
+}
-it("injects the same shared frontend package version into the Blog build", async () => {
+it("injects the same shared frontend package version into the Blog build", () => {
const pkg = JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", import.meta.url)), "utf8"))
+ const config = loadBuildConfigs("production", "")[1]
+ expect(config.env?.NEXT_PUBLIC_APP_VERSION).toBe(pkg.version)
+ expect(config.assetPrefix).toBe("/blog-static")
+})
+
+it.each([
+ { mode: "production", source: "a".repeat(40), release: "a".repeat(40), environment: "production" },
+ { mode: "development", source: "b".repeat(40), release: "b".repeat(40), environment: "development" },
+ { mode: "production", source: "", release: "", environment: "production" },
+ { mode: "test", source: "", release: "", environment: "" },
+])("embeds native provenance in both apps for $mode with source '$source'", ({ mode, source, release, environment }) => {
+ for (const config of loadBuildConfigs(mode, source)) {
+ expect(config.env).toMatchObject({ NEXT_PUBLIC_FARO_RELEASE: release, NEXT_PUBLIC_FARO_ENVIRONMENT: environment })
+ }
+})
+
+it.each([
+ { mode: "production", source: "a".repeat(40), release: "a".repeat(40), environment: "production" },
+ { mode: "test", source: "", release: "", environment: "" },
+])("executes the real Blog configuration with the shared resolver for $mode", async ({ mode, source, release, environment }) => {
+ vi.stubEnv("NODE_ENV", mode)
+ vi.stubEnv("WORKERS_CI_COMMIT_SHA", source)
+ vi.stubEnv("CF_PAGES_COMMIT_SHA", "")
+ vi.stubEnv("GITHUB_SHA", "")
+ vi.stubEnv("NEXT_PUBLIC_FARO_RELEASE", "c".repeat(40))
+ vi.stubEnv("NEXT_PUBLIC_FARO_ENVIRONMENT", "qa")
const { default: loadConfig } = await import("../next.config")
const config = await loadConfig()
- expect(config.env?.NEXT_PUBLIC_APP_VERSION).toBe(pkg.version)
+ const pkg = JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", import.meta.url)), "utf8"))
+ expect(config.env).toMatchObject({ NEXT_PUBLIC_APP_VERSION: pkg.version, NEXT_PUBLIC_FARO_RELEASE: release, NEXT_PUBLIC_FARO_ENVIRONMENT: environment })
expect(config.assetPrefix).toBe("/blog-static")
})
diff --git a/src/web/custom-worker.ts b/src/web/custom-worker.ts
index d8431c848..4225a9287 100644
--- a/src/web/custom-worker.ts
+++ b/src/web/custom-worker.ts
@@ -4,12 +4,13 @@
import openNextHandler from "./.open-next/worker.js"
import { createWebWorkerHandler } from "./src/lib/worker-runtime"
import type { NextConfig } from "next"
-import { resolveObservationBuild } from "./src/lib/observability/build"
+import { resolveObservationLabels } from "./src/lib/observability/build"
// @ts-ignore — generated by Next build before the Worker bundle
import requiredServerFiles from "./.open-next/server-functions/default/src/web/.next/required-server-files.json"
// @ts-ignore — generated at build time, may not exist yet
export { DOQueueHandler } from "./.open-next/worker.js"
-const build = resolveObservationBuild((requiredServerFiles as { config: Pick<NextConfig, "env"> }).config.env ?? {})
+const buildEnv = (requiredServerFiles as { config: Pick<NextConfig, "env"> }).config.env
+const build = resolveObservationLabels({ release: buildEnv?.NEXT_PUBLIC_FARO_RELEASE, environment: buildEnv?.NEXT_PUBLIC_FARO_ENVIRONMENT })
export default createWebWorkerHandler(openNextHandler as ExportedHandler<CloudflareEnv>, build)
diff --git a/src/web/src/lib/observability/build.test.ts b/src/web/src/lib/observability/build.test.ts
index 58e6d0ab1..3f728d08f 100644
--- a/src/web/src/lib/observability/build.test.ts
+++ b/src/web/src/lib/observability/build.test.ts
@@ -1,10 +1,30 @@
import { expect, it } from "vitest"
-import { resolveObservationBuild } from "./build"
+import { resolveObservationBuild, resolveObservationLabels } from "./build"
-it("uses a full CI source SHA and marks absent or invalid provenance explicitly", () => {
- expect(resolveObservationBuild({ WORKERS_CI_COMMIT_SHA: "a".repeat(40), NEXT_PUBLIC_FARO_RELEASE: "b".repeat(40), NEXT_PUBLIC_FARO_ENVIRONMENT: "qa" }))
+it("uses native CI source priority and NODE_ENV despite old manual overrides", () => {
+ expect(resolveObservationBuild({ WORKERS_CI_COMMIT_SHA: "a".repeat(40), CF_PAGES_COMMIT_SHA: "b".repeat(40), GITHUB_SHA: "c".repeat(40), NODE_ENV: "production", NEXT_PUBLIC_FARO_RELEASE: "d".repeat(40), NEXT_PUBLIC_FARO_ENVIRONMENT: "qa" }))
+ .toEqual({ release: "a".repeat(40), environment: "production", release_status: "present", environment_status: "present" })
+ expect(resolveObservationBuild({ WORKERS_CI_COMMIT_SHA: "abbreviated", CF_PAGES_COMMIT_SHA: "b".repeat(40), GITHUB_SHA: "c".repeat(40), NODE_ENV: "development" }))
+ .toEqual({ release: "b".repeat(40), environment: "development", release_status: "present", environment_status: "present" })
+ expect(resolveObservationBuild({ WORKERS_CI_COMMIT_SHA: "", CF_PAGES_COMMIT_SHA: "invalid", GITHUB_SHA: "c".repeat(40) }).release).toBe("c".repeat(40))
+})
+
+it("does not use manual Faro aliases or package versions as source provenance", () => {
+ expect(resolveObservationBuild({ NEXT_PUBLIC_FARO_RELEASE: "a".repeat(40), NEXT_PUBLIC_FARO_ENVIRONMENT: "production", NEXT_PUBLIC_APP_VERSION: "0.1.56" }))
+ .toEqual({ release: undefined, environment: undefined, release_status: "missing", environment_status: "missing" })
+ expect(resolveObservationBuild({ WORKERS_CI_COMMIT_SHA: "0.1.56", NODE_ENV: "production" }))
+ .toEqual({ release: undefined, environment: "production", release_status: "missing", environment_status: "present" })
+})
+
+it("keeps absent or unsupported environment labels explicitly missing", () => {
+ for (const NODE_ENV of [undefined, "", "test", "private"]) {
+ expect(resolveObservationBuild({ NODE_ENV }).environment_status).toBe("missing")
+ }
+})
+
+it("validates already compiled labels without resolving source inputs again", () => {
+ expect(resolveObservationLabels({ release: "a".repeat(40), environment: "qa" }))
.toEqual({ release: "a".repeat(40), environment: "qa", release_status: "present", environment_status: "present" })
- expect(resolveObservationBuild({ WORKERS_CI_COMMIT_SHA: "abbreviated", GITHUB_SHA: "b".repeat(40), NEXT_PUBLIC_FARO_ENVIRONMENT: "development" }).release).toBe("b".repeat(40))
- expect(resolveObservationBuild({ NEXT_PUBLIC_FARO_RELEASE: "0.1.46", NEXT_PUBLIC_FARO_ENVIRONMENT: "private" }))
+ expect(resolveObservationLabels({ release: "abbreviated", environment: "private" }))
.toEqual({ release: undefined, environment: undefined, release_status: "missing", environment_status: "missing" })
})
diff --git a/src/web/src/lib/observability/build.ts b/src/web/src/lib/observability/build.ts
index 021349f4b..09454fbb4 100644
--- a/src/web/src/lib/observability/build.ts
+++ b/src/web/src/lib/observability/build.ts
@@ -1,8 +1,12 @@
import { cleanAttributes } from "./schema"
export function resolveObservationBuild(env: Record<string, string | undefined>) {
- const release = [env.WORKERS_CI_COMMIT_SHA, env.CF_PAGES_COMMIT_SHA, env.GITHUB_SHA, env.NEXT_PUBLIC_FARO_RELEASE]
+ const release = [env.WORKERS_CI_COMMIT_SHA, env.CF_PAGES_COMMIT_SHA, env.GITHUB_SHA]
.find(value => value && /^[0-9a-f]{40}$/.test(value))
- const environment = cleanAttributes({ environment: env.NEXT_PUBLIC_FARO_ENVIRONMENT }).environment
+ return resolveObservationLabels({ release, environment: env.NODE_ENV })
+}
+
+export function resolveObservationLabels(labels: { release?: string; environment?: string }) {
+ const { release, environment } = cleanAttributes(labels)
return { release, environment, release_status: release ? "present" : "missing", environment_status: environment ? "present" : "missing" }
}
diff --git a/src/web/src/lib/observability/client.ts b/src/web/src/lib/observability/client.ts
index d528e3301..dbd27b87b 100644
--- a/src/web/src/lib/observability/client.ts
+++ b/src/web/src/lib/observability/client.ts
@@ -12,7 +12,7 @@ import { installLongTaskObserver } from "./browser"
import { resolveCommunityModulePlan } from "../community/community-route"
import { observeTransportSpan, finishTransportSpan, installNavigationFetchContext } from "./requests"
import { resolveFrontendIdentity } from "./runtime"
-import { resolveObservationBuild } from "./build"
+import { resolveObservationLabels } from "./build"
import { finishTransportClock } from "./clock"
import { observeResourceResponse } from "./resource"
@@ -25,7 +25,7 @@ function validBuildProfile(profile: BuildProfile) {
}
const build: BuildProfile = {
url: process.env.NEXT_PUBLIC_FARO_COLLECTOR_URL,
- ...resolveObservationBuild({ NEXT_PUBLIC_FARO_ENVIRONMENT: process.env.NEXT_PUBLIC_FARO_ENVIRONMENT, NEXT_PUBLIC_FARO_RELEASE: process.env.NEXT_PUBLIC_FARO_RELEASE }),
+ ...resolveObservationLabels({ environment: process.env.NEXT_PUBLIC_FARO_ENVIRONMENT, release: process.env.NEXT_PUBLIC_FARO_RELEASE }),
}
let started = false
let documentSuspended = false
diff --git a/src/web/src/lib/observability/sanitize.ts b/src/web/src/lib/observability/sanitize.ts
index 664d76494..99b4717ec 100644
--- a/src/web/src/lib/observability/sanitize.ts
+++ b/src/web/src/lib/observability/sanitize.ts
@@ -2,7 +2,7 @@ import type { TransportItem, EventEvent, ExceptionEvent, MeasurementEvent, Trace
import { actionNames, routeTemplate } from "./coverage"
import { cleanAttributes, eventNames } from "./schema"
import type { FrontendIdentity } from "./runtime"
-import { resolveObservationBuild } from "./build"
+import { resolveObservationLabels } from "./build"
import { documentEventNames } from "./document-timing"
import { transportClockStart, transportClockEnd, retiredObservationSpan } from "./clock"
import { networkEventNames } from "./resource"
@@ -25,7 +25,7 @@ function qualifiedMonotonic(fields: Record<string, unknown>, since?: number) {
}
export function sanitizeTrace(input: unknown, sessionId: string, origin: string, identity?: Partial<FrontendIdentity> & { release?: string; environment?: string }, since = 0, monotonicSince?: number) {
const canonical = { ...(identity ? { frontend_surface: identity.frontend_surface, client_platform: identity.client_platform, app_version: identity.app_version } : {}),
- ...resolveObservationBuild({ NEXT_PUBLIC_FARO_RELEASE: identity?.release, NEXT_PUBLIC_FARO_ENVIRONMENT: identity?.environment }) }
+ ...resolveObservationLabels({ release: identity?.release, environment: identity?.environment }) }
const context = cleanAttributes(canonical)
const resources = array(record(input).resourceSpans).flatMap(resource => {
const scopes = array(record(resource).scopeSpans).flatMap(scope => {
diff --git a/src/web/src/lib/observability/worker.test.ts b/src/web/src/lib/observability/worker.test.ts
index 634f2d117..7f68917f3 100644
--- a/src/web/src/lib/observability/worker.test.ts
+++ b/src/web/src/lib/observability/worker.test.ts
@@ -1,6 +1,6 @@
import { afterEach, expect, it, vi } from "vitest"
import { observeWorkerOperation } from "./worker"
-import { resolveObservationBuild } from "./build"
+import { resolveObservationLabels } from "./build"
import { createWebWorkerHandler, workerRequestAttributes } from "../worker-runtime"
const native = vi.hoisted(() => ({ tracing: undefined as ExecutionContext["tracing"] | undefined }))
@@ -21,7 +21,7 @@ it("passes execution to native request spans and filters private attributes", as
})
it("records received trace context and actual Worker version without claiming a native parent", () => {
- const build = resolveObservationBuild({ NEXT_PUBLIC_FARO_RELEASE: "a".repeat(40), NEXT_PUBLIC_FARO_ENVIRONMENT: "qa" })
+ const build = resolveObservationLabels({ release: "a".repeat(40), environment: "qa" })
const request = new Request("https://fixture.test/c/me?token=PRIVATE", { headers: { traceparent: `00-${"b".repeat(32)}-${"c".repeat(16)}-01`, tracestate: "PRIVATE" } })
const fields = workerRequestAttributes(request, { CF_VERSION_METADATA: { id: "real-version" } } as Env, build)
expect(fields).toMatchObject({ release: "a".repeat(40), environment: "qa", worker_version: "real-version", trace_context: "received", upstream_trace_id: "b".repeat(32), upstream_span_id: "c".repeat(16) })