[wrangler] Add metrics export configuration by cf-mandarin · Pull Request #15112 · cloudflare/workers-sdk

cf-mandarin · 2026-08-10T11:17:47Z

Fixes https://jira.cfdata.org/browse/WO-1037.

Purpose

This PR makes metrics export a first-class Wrangler configuration under observability.metrics, alongside the existing observability.logs and observability.traces settings.

Users can declare whether metrics export is enabled and which destinations should receive metrics directly in their wrangler.jsonc file:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "metrics-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-10",

  "observability": {
    "logs": {
      "enabled": true
    },
    "traces": {
      "enabled": true
    },
    "metrics": {
      "enabled": true,
      "destinations": ["opentelemetry-metrics"]
    }
  },

  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "metrics-database",
      "database_id": "11111111-1111-1111-1111-111111111111"
    }
  ],

  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "metrics-bucket"
    }
  ]
}

The same destinations are applied to the Worker and its supported bound resources.

Metrics export can be explicitly disabled without removing the configuration block:

{
  "observability": {
    "metrics": {
      "enabled": false
    }
  }
}

Supported resources

This initial implementation supports:

Workers
D1 databases bound to the Worker
R2 buckets bound to the Worker

Wrangler resolves canonical D1 and R2 identifiers from local configuration or deployed Worker settings. Other resource types are not included in the reconciliation request.

Lifecycle coverage

Wrangler path	Metrics export behavior
`wrangler deploy`	Supported. Reconciles metrics after the Worker, routes, and cron triggers have been deployed.
`wrangler delete`	Supported. Deletes the Worker first, then attempts best-effort metrics cleanup. A failed Worker deletion leaves metrics export unchanged; cleanup failures after deletion warn.
`wrangler versions deploy`	No-op. The metrics block is removed from script settings and is not reconciled.
`wrangler versions upload`	No-op. Observability settings are non-versioned and metrics are not reconciled.
Preview and development flows	No-op. The metrics block is removed from preview settings and is not sent to the metrics export API.
Dispatch namespace deploys	No-op. The deployment continues normally without metrics reconciliation.

Native Logs and Traces settings continue through their existing upload and script-settings paths. Adding a metrics-only block does not enable, disable, or otherwise change Logs or Traces.

Validation

When observability.metrics is present:

enabled must be explicitly set to true or false.
destinations is required and must be non-empty when enabled.
Destination names are trimmed.
Blank and duplicate destinations are rejected.

Implementation

Metrics export uses a separate API from the native Worker observability settings. Wrangler therefore removes metrics from Worker upload, preview, and script-settings payloads before reconciling it independently.

The reconciliation request identifies the Worker as the requester and includes the supported Worker, D1, and R2 resources. Transient API failures are retried. Configuration errors, such as unresolved bindings, retain their actionable error messages.

If reconciliation fails during a regular deployment, Wrangler warns that the primary Worker deployment succeeded but metrics export configuration was not applied. The completed Worker deployment still returns successfully.

Configuration removal semantics

Removing the entire observability section or only observability.metrics intentionally leaves any existing metrics export active. Wrangler does not call the Portal /metricsexport API when the metrics block is absent. This prevents every normal deployment, including projects that never adopted metrics export, from calling an API that is currently restricted to allowlisted accounts.

To stop an existing export, users must explicitly deploy observability.metrics.enabled: false. This differs from native Workers Logs and Traces, which are disabled when their observability configuration is removed. We plan to revisit this behavior when Wrangler can distinguish existing metrics-export state without calling the Portal API for unrelated deployments.

Rollout

The metrics export API is currently behind a Flagship rollout flag and is available only to whitelisted accounts. The internal Flagship flag name is intentionally not exposed here.

Tests
- Tests included/updated
- Automated tests not possible - manual testing has been completed as follows:
- Additional testing not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: rollout is currently restricted to allowlisted accounts.

…r-metrics-export-config # Conflicts: # packages/deploy-helpers/src/deploy/deploy.ts # packages/deploy-helpers/src/preview/preview.ts # packages/workers-utils/src/config/validation.ts # packages/wrangler/src/__tests__/preview.test.ts

changeset-bot · 2026-08-10T11:17:55Z

🦋 Changeset detected

Latest commit: 6261c79

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@cloudflare/config	Minor
@cloudflare/workers-auth	Minor
@cloudflare/workers-utils	Minor
wrangler	Minor
@cloudflare/build-output-utils	Patch
@cloudflare/vite-plugin	Patch
@cloudflare/remote-bindings	Patch
@cloudflare/autoconfig	Patch
@cloudflare/cli-shared-helpers	Patch
@cloudflare/deploy-helpers	Patch
@cloudflare/vitest-pool-workers	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

workers-devprod · 2026-08-10T11:18:12Z

Codeowners approval required for this PR:

@cloudflare/wrangler

Show detailed file reviewers

.changeset/fuzzy-metrics-export.md: [@cloudflare/wrangler]
packages/config/src/tests/convert.test.ts: [@cloudflare/wrangler]
packages/config/src/tests/schema.test.ts: [@cloudflare/wrangler]
packages/config/src/convert.ts: [@cloudflare/wrangler]
packages/config/src/schema.ts: [@cloudflare/wrangler]
packages/config/src/types.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/deploy/deploy.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/deploy/helpers/metrics-export.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/index.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/preview/shared.ts: [@cloudflare/wrangler]
packages/workers-auth/src/core/scopes.ts: [@cloudflare/wrangler]
packages/workers-utils/src/config/environment.ts: [@cloudflare/wrangler]
packages/workers-utils/src/config/validation-helpers.ts: [@cloudflare/wrangler]
packages/workers-utils/src/config/validation.ts: [@cloudflare/wrangler]
packages/workers-utils/tests/config/validation/normalize-and-validate-config.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/delete.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/deploy/core.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/deploy/metrics-export.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/preview.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/profiles.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/user.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/versions/versions.deploy.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/whoami.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/delete.ts: [@cloudflare/wrangler]
packages/wrangler/src/versions/deploy.ts: [@cloudflare/wrangler]

pkg-pr-new · 2026-08-11T09:11:28Z

@cloudflare/autoconfig

npm i https://pkg.pr.new/@cloudflare/autoconfig@15112

@cloudflare/build-output-utils

npm i https://pkg.pr.new/@cloudflare/build-output-utils@15112

@cloudflare/config

npm i https://pkg.pr.new/@cloudflare/config@15112

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@15112

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/@cloudflare/deploy-helpers@15112

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@15112

miniflare

npm i https://pkg.pr.new/miniflare@15112

@cloudflare/pages-functions

npm i https://pkg.pr.new/@cloudflare/pages-functions@15112

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@15112

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@15112

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@15112

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@15112

@cloudflare/workers-auth

npm i https://pkg.pr.new/@cloudflare/workers-auth@15112

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@15112

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@15112

wrangler

npm i https://pkg.pr.new/wrangler@15112

commit: c1484dc

NuroDev · 2026-08-11T10:28:51Z

@@ -545,7 +546,7 @@ async function maybePatchSettings(
 		logpush: config.logpush,
 		tail_consumers: config.tail_consumers,
 		streaming_tail_consumers: config.streaming_tail_consumers,
-		observability: config.observability, // TODO reconcile with how regular deploy handles empty state
+		observability: withoutMetricsExportConfig(config.observability), // TODO reconcile with how regular deploy handles empty state


Is this TODO something worth fixing now?

I don’t think we should address this in this PR. The TODO predates the metrics change and concerns broader differences in how regular and versions deploys clear non-versioned observability settings. This PR only preserves existing behavior while stripping the metrics-only configuration from versions deploys. I’d keep this as follow-up work, what do you think?

NuroDev · 2026-08-11T11:11:25Z

 		.optional(),
+	metrics: z
+		.strictObject({
+			enabled: z.boolean(),


So the metrics object is optional but the enabled field is always required?

Correct, this is intentional. Metrics export is optional, but once the block is present we require an explicit enabled: true or enabled: false. This prevents destinations-only configurations from being silently ignored and gives users an explicit way to clear existing export configuration. Do it make sense?

NuroDev · 2026-08-11T11:16:45Z

+	WorkerMetadataBinding,
+} from "@cloudflare/workers-utils";
+
+export function withoutMetricsExportConfig(


Nit pick: Can we add some JSDoc comments to these functions with a brief description of what they do.

Agree 👍 , on it!

NuroDev · 2026-08-11T12:16:00Z

@@ -336,9 +351,21 @@ describe("wrangler preview", () => {
 			);
 		});

-		test("should create a new preview with defaults applied", async ({
+		test("should ignore metrics export and create a new preview", async ({


The title implies we're ignoring the metrics export but all we do is write a Wrangler config but not actually check anything after to validate metrics exports were ignored?
Unless I am missing something here?

Yes, good catch. There is a separate unit test covering assemblePreviewScriptSettings, but this integration test does not explicitly verify the preview request or absence of a metrics API call. I’ll add assertions that metrics are excluded from the preview payload and that no metrics reconciliation is attempted.

NuroDev · 2026-08-11T12:16:53Z

+		writeWranglerConfig({
+			observability: { metrics: { enabled: false } },
+		});


Is this really needed if we already have a fallback to disable metrics?

The metrics block is needed because cleanup is intentionally gated on its presence, avoiding calls to the allowlist-restricted endpoint for unrelated deletes. However, enabled: false is misleading in this test. I’ll use enabled: true and rename the test to make clear that it verifies post-delete cleanup of an actively configured export.

devin-ai-integration

Devin Review found 1 new potential issue.

View 7 additional findings in Devin Review.

devin-ai-integration · 2026-08-12T15:07:39Z

+---
+"@cloudflare/config": minor
+"@cloudflare/workers-auth": minor
+"@cloudflare/workers-utils": minor
+"wrangler": minor
+---


🟡 Release notes leave out one of the packages that was changed

The release note file (.changeset/fuzzy-metrics-export.md:1-6) lists only four packages even though the deploy helper package was also modified, so that package will not get a version bump or changelog entry when the release is cut.
Impact: The published deploy-helpers package stays on its old version without the metrics-export code, and its changelog omits this change.

Why the missing entry matters for the release pipeline

packages/deploy-helpers is a published (non-private, version 0.6.6) workspace package and is not in the changesets ignore list (.changeset/config.json). This PR adds packages/deploy-helpers/src/deploy/helpers/metrics-export.ts and modifies packages/deploy-helpers/src/deploy/deploy.ts, src/preview/shared.ts, and src/index.ts, but the changeset front-matter only bumps @cloudflare/config, @cloudflare/workers-auth, @cloudflare/workers-utils, and wrangler. Repository rules (AGENTS.md / CONTRIBUTING.md) state that every change to package code requires a changeset, and @cloudflare/deploy-helpers is routinely included in changesets elsewhere in the repo history.

Suggested change

---

"@cloudflare/config": minor

"@cloudflare/workers-auth": minor

"@cloudflare/workers-utils": minor

"wrangler": minor

---

---

"@cloudflare/config": minor

"@cloudflare/deploy-helpers": minor

"@cloudflare/workers-auth": minor

"@cloudflare/workers-utils": minor

"wrangler": minor

---

Was this helpful? React with 👍 or 👎 to provide feedback.

This reverts commit 6e80b65.

cf-mandarin added 6 commits July 8, 2026 13:41

Add Wrangler metrics export config

acf4819

Fix Wrangler metrics export reconciliation

65fec70

Complete Wrangler metrics export lifecycle

f9227e8

Test metrics-only versions deploy settings

ff88b54

Preserve native observability for metrics-only deploys

f27ab5c

cf-mandarin requested a review from workers-devprod as a code owner August 10, 2026 11:17

workers-devprod requested review from a team and jamesopstad and removed request for a team August 10, 2026 11:18

This comment was marked as resolved.

Sign in to view

Protect primary operations from metrics export failures

09b736a

This comment was marked as resolved.

Sign in to view

Preserve actionable metrics binding errors

5e9d0ea

This comment was marked as resolved.

Sign in to view

Require explicit metrics export state

82c9261

This comment was marked as resolved.

Sign in to view

Warn on metrics export reconciliation failures

dbe6b8e

This comment was marked as resolved.

Sign in to view

workers-devprod added this to workers-sdk Aug 11, 2026

github-project-automation Bot moved this to Untriaged in workers-sdk Aug 11, 2026

Correct metrics cleanup failure message

4b66f80

This comment was marked as resolved.

Sign in to view

Clean up metrics after Worker deletion

5886bb0

This comment was marked as resolved.

Sign in to view

cf-mandarin added 2 commits August 11, 2026 10:38

Ignore absent observability validation options

2b406e3

Initialize required metrics enabled state

462ae29

Remove stale metrics test option

a7b54d6

NuroDev reviewed Aug 11, 2026

View reviewed changes

Add Workers Observability OAuth scope

c1484dc

This comment was marked as resolved.

Sign in to view

Include service-bound Workers in metrics export

6e80b65

devin-ai-integration Bot reviewed Aug 12, 2026

View reviewed changes

Revert "Include service-bound Workers in metrics export"

6261c79

This reverts commit 6e80b65.

Uh oh!

Conversation

cf-mandarin commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

workers-devprod commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

pkg-pr-new Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cf-mandarin Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cf-mandarin commented Aug 10, 2026 •

edited

Loading

changeset-bot Bot commented Aug 10, 2026 •

edited

Loading

workers-devprod commented Aug 10, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 11, 2026 •

edited

Loading

cf-mandarin Aug 11, 2026 •

edited

Loading