chore(migrate): align scaffold + skill with 5.0 CF-native observability - #160
Merged
Conversation
The migration scaffold's server-entry template and phase-report next-steps were still describing the pre-5.0 observability stack: "CF-managed OTLP push when wrangler.jsonc has observability.logs.destinations", and the report's bullet 7 was literally pointing at HyperDX provisioning. 5.0 dropped the in-Worker OTLP transport. The CF dashboard is the destination — no destinations, no flush hook, no OTLP exporter. This PR brings the scaffold-time documentation in line with what the framework actually does and adds a new section 47 in the migration skill (worker-cloudflare reference) covering: - what instrumentWorker still does in 5.0+ (api-bridge, attribute floor, AE binding wiring) and what it no longer accepts (enableAppSideOtlpLogs, otlpEndpoint, otlpHeaders, otlpMinSeverity, samplingConfig, exportIntervalMillis) - the canonical wrangler.jsonc shape with the master switch observability.enabled at the top level (a master switch I learned about the hard way during the lebiscuit canary) - AE datasets are auto-provisioned on first writeDataPoint — no CF API call, no dashboard step - the ClickHouse-collector adapter scaffolded at src/sdk/otelAdapters/clickhouseCollector.ts as the future export path, with the explicit caveat that it throws today Net effect: the next agent or human running deco-migrate against a fresh site repo gets observability guidance that matches the framework currently on npm (5.0.0). Co-authored-by: Cursor <cursoragent@cursor.com>
4 tasks
|
🎉 This PR is included in version 5.1.0 🎉 The release is available on:
Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
scripts/migrate/templates/server-entry.ts(both the non-VTEX and VTEX worker-entry templates) so they describe the 5.0+ Cloudflare-native stack instead of the pre-5.0 OTLP-push stack.scripts/migrate/phase-report.tsstep 7 to drop the HyperDX provisioning line and point at the canonical CF-native block + the future ClickHouse path.references/worker-cloudflare.mdcovering instrumentWorker's 5.0 surface, the required wrangler.jsonc shape (including theenabled: truemaster switch), AE auto-provisioning, and the ClickHouse-collector stub.Why
The framework PR (#156) and the codemod (#150-area) updated the runtime + the wrangler codemod, but the scaffold-time documentation that the migration script bakes into a new site's worker-entry comment header and
MIGRATION_REPORT.mdwas still describing the pre-5.0 behaviour. The next person to rundeco-migratewould get a worker-entry whose comments contradict the framework version they're consuming.This is the
scaffold-updatetodo from the drop-hyperdx-cf-rollout plan — wrapping up Phase 3.3.What changes
scripts/migrate/templates/server-entry.tsBoth
generateWorkerEntry(non-VTEX, default scaffold) andgenerateVtexWorkerEntry(VTEX scaffold) get their observability comment header rewritten to describe:console.*-> CF Workers Logs (no app-side exporter)@opentelemetry/apiglobal tracer (bridged fromwithTracing) -> CF Workers Tracingscripts/migrate/phase-report.tsStep 7 in the generated
MIGRATION_REPORT.mdnext-steps was:Replaced with a paragraph that points at the canonical CF dashboard view, notes that no external destination is needed today, and previews the future
--destination-logs/--destination-tracesopt-in flag once ClickHouse-via-collector ships..agents/skills/deco-to-tanstack-migration/references/worker-cloudflare.mdNew section 47 ("Observability (5.0+, Cloudflare-native)") covers:
instrumentWorkerdoes in 5.0+ and what options it no longer acceptswrangler.jsoncshape with theobservability.enabled: truemaster switch (the master switch I learned about the hard way during the lebiscuit canary)writeDataPointsrc/sdk/otelAdapters/clickhouseCollector.tsas the future directionTest plan
bunx tsc --noEmitpassesMade with Cursor
Summary by cubic
Aligns the migration scaffold and docs with the 5.0 Cloudflare‑native observability stack. Removes OTLP/HyperDX guidance, points to the CF dashboard, and documents the required
wrangler.jsoncshape and future ClickHouse path.scripts/migrate/templates/server-entry.ts(default and VTEX) for 5.0: logs via CF Workers Logs, traces via@opentelemetry/api→ CF Tracing, metrics via AE.scripts/migrate/phase-report.tsstep 7 to add the canonicalobservabilityblock guidance, remove HyperDX provisioning, and preview future--destination-logs/--destination-tracesflags.references/worker-cloudflare.mdcoveringinstrumentWorkerin 5.0, the requiredwrangler.jsonc(observability.enabled: true,DECO_METRICS), AE auto-provisioning, removed options (enableAppSideOtlpLogs,otlp*,samplingConfig,exportIntervalMillis), and the ClickHouse collector stub (sdk/otelAdapters/clickhouseCollector).Written for commit cdab162. Summary will update on new commits.