Prevent Metric attribute serialization key collisions

[fubhy]

Summary

Different valid metric attribute sets can serialize to the same registry key, causing logically separate series to share a hook and contaminate each other's values.

Important

This PR starts with focused failing reproduction tests. Add the implementation fix to this same branch; CI is expected to fail until that fix is included.

Distinct metric attribute sets can share registry state

Module: Metric
Audit ID: core-g-r-metric-attribute-series-key-collision
Severity / confidence: high / high

What happens

Different valid metric attribute sets can serialize to the same registry key, causing logically separate series to share a hook and contaminate each other's values.

Why it happens

makeKey concatenates unescaped key=value pairs with commas. The valid sets { a: "b,c=d" } and { a: "b", c: "d" } both serialize as a=b,c=d and occupy one registry entry.

Expected behavior

Metric attributes identify dimensions: referentially equivalent definitions share a series, but each distinct attribute combination represents a separate series.

Relevant implementation

These links and excerpts are pinned to audit base c9b56ab507f224426ee8388dc450da447ec4715f.

• packages/effect/src/Metric.ts:2823-2829
• packages/effect/src/Metric.ts:3480-3508

View problematic code at packages/effect/src/Metric.ts:2823-2829

 * Returns a new metric that applies the specified attributes to all operations.
 *
 * **Details**
 *
 * Attributes are key-value pairs that provide additional context for metrics,
 * enabling filtering, grouping, and more detailed analysis. Each combination
 * of attribute values creates a separate metric series.

View exact lines on GitHub

View problematic code at packages/effect/src/Metric.ts:3480-3508

function makeKey<Input, State>(
  metric: Metric<Input, State>,
  attributes: Metric.Attributes | undefined
) {
  let key = `${metric.type}:${metric.id}`
  if (Predicate.isNotUndefined(metric.description)) {
    key += `:${metric.description}`
  }
  if (Predicate.isNotUndefined(attributes)) {
    key += `:${serializeAttributes(attributes)}`
  }
  return key
}

function makeHooks<Input, State>(
  get: (context: Context.Context<never>) => State,
  update: (input: Input, context: Context.Context<never>) => void,
  modify?: (input: Input, context: Context.Context<never>) => void
): Metric.Hooks<Input, State> {
  return { get, update, modify: modify ?? update }
}

function serializeAttributes(attributes: Metric.Attributes): string {
  return serializeEntries(Array.isArray(attributes) ? attributes : Object.entries(attributes))
}

function serializeEntries(entries: ReadonlyArray<[string, string]>): string {
  return entries.map(([key, value]) => `${key}=${value}`).join(",")
}

View exact lines on GitHub

Reproduction

pnpm vitest run packages/effect/test/Metric.test.ts -t "keeps distinct attribute sets in separate series"

Observed failure: The intended failure was reproduced: the first counter was 11 instead of 1.

Implementation handoff

The initial reproduction tests on this branch are the regression specification for the implementation fix that should follow in this PR.

1. Start with the pinned implementation excerpts and the Why it happens analysis above.
2. Change the implementation so it satisfies the stated Expected behavior; do not weaken or remove the reproduction assertions.
3. Run the focused reproduction command(s) and confirm the observed failures become passing tests:

pnpm vitest run packages/effect/test/Metric.test.ts -t "keeps distinct attribute sets in separate series"

4. Run the affected package's existing tests, then the repository lint and type checks before requesting review.

Audit provenance

• Audit base: c9b56ab507f224426ee8388dc450da447ec4715f
• Reproduction base: c9b56ab507f224426ee8388dc450da447ec4715f
• Findings: core-g-r-metric-attribute-series-key-collision
• Initial patch: focused reproduction tests; implementation fix pending

Closes EFF-348

[changeset-bot]

🦋 Changeset detected

Latest commit: 76359a0

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

This PR includes changesets to release 30 packages

Name	Type
effect	Patch
@effect/opentelemetry	Patch
@effect/platform-browser	Patch
@effect/platform-bun	Patch
@effect/platform-deno	Patch
@effect/platform-node-shared	Patch
@effect/platform-node	Patch
@effect/vitest	Patch
@effect/ai-anthropic	Patch
@effect/ai-openai-compat	Patch
@effect/ai-openai	Patch
@effect/ai-openrouter	Patch
@effect/atom-react	Patch
@effect/atom-solid	Patch
@effect/atom-vue	Patch
@effect/sql-clickhouse	Patch
@effect/sql-d1	Patch
@effect/sql-libsql	Patch
@effect/sql-mssql	Patch
@effect/sql-mysql2	Patch
@effect/sql-pg	Patch
@effect/sql-pglite	Patch
@effect/sql-sqlite-bun	Patch
@effect/sql-sqlite-do	Patch
@effect/sql-sqlite-node	Patch
@effect/sql-sqlite-react-native	Patch
@effect/sql-sqlite-wasm	Patch
@effect/docgen	Patch
@effect/doctest	Patch
@effect/openapi-generator	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

[pullfrog]

✅ No new issues found.

Reviewed changes — a single reproduction test for a Metric attribute series key collision:

• New test "keeps distinct attribute sets in separate series" — creates two counters sharing a metric ID but with attribute sets { a: "b,c=d" } and { a: "b", c: "d" } that naively serialize to the same string, then asserts each counter maintains an independent count.

The test is well-formed: it follows the existing patterns in the file (it.effect, Effect.gen, nextId() for isolation, assert.strictEqual), uses the correct Metric APIs, and the assertions unambiguously capture the expected contract — that distinct attribute sets must be tracked as separate series.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — replaced the buggy manual attribute serialization with JSON.stringify to prevent key collisions:

• Inlined serializeAttributes to use JSON.stringify — removed the two-function serializeAttributes → serializeEntries chain that concatenated unescaped key=value pairs with commas. JSON.stringify of Object.entries (or the array path directly) produces deterministic, collision-free strings because arrays of string tuples never produce ambiguous serialization.
• Added a patch changeset — correctly scoped as "effect": patch.
• Retained the reproduction test from the prior review — the test "keeps distinct attribute sets in separate series" now serves as the regression test for the fix.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

[github-actions]

Bundle Size Analysis

Generated from PR build output; treat the content below as untrusted.

File Name	Current Size	Previous Size	Difference
basic.ts	7.06 KB	7.06 KB	0.00 KB (0.00%)
batching.ts	9.86 KB	9.86 KB	0.00 KB (0.00%)
brand.ts	6.34 KB	6.34 KB	0.00 KB (0.00%)
cache.ts	10.62 KB	10.62 KB	0.00 KB (0.00%)
config.ts	20.60 KB	20.60 KB	0.00 KB (0.00%)
differ.ts	20.20 KB	20.20 KB	0.00 KB (0.00%)
http-client.ts	21.49 KB	21.49 KB	0.00 KB (0.00%)
logger.ts	10.76 KB	10.76 KB	0.00 KB (0.00%)
metric.ts	8.98 KB	8.99 KB	-0.01 KB (-0.11%)
optic.ts	7.18 KB	7.18 KB	0.00 KB (0.00%)
pubsub.ts	14.90 KB	14.90 KB	0.00 KB (0.00%)
queue.ts	11.58 KB	11.58 KB	0.00 KB (0.00%)
schedule.ts	10.74 KB	10.74 KB	0.00 KB (0.00%)
schema-class.ts	19.14 KB	19.14 KB	0.00 KB (0.00%)
schema-fromJsonSchemaDocument.ts	28.96 KB	28.96 KB	0.00 KB (0.00%)
schema-representation-roundtrip.ts	25.29 KB	25.29 KB	0.00 KB (0.00%)
schema-string-transformation.ts	13.30 KB	13.30 KB	0.00 KB (0.00%)
schema-string.ts	10.94 KB	10.94 KB	0.00 KB (0.00%)
schema-template-literal.ts	15.17 KB	15.17 KB	0.00 KB (0.00%)
schema-toArbitraryLazy.ts	21.94 KB	21.94 KB	0.00 KB (0.00%)
schema-toCodeDocument.ts	24.34 KB	24.34 KB	0.00 KB (0.00%)
schema-toCodecJson.ts	19.18 KB	19.18 KB	0.00 KB (0.00%)
schema-toEquivalence.ts	19.01 KB	19.01 KB	0.00 KB (0.00%)
schema-toFormatter.ts	18.87 KB	18.87 KB	0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts	22.60 KB	22.60 KB	0.00 KB (0.00%)
schema-toRepresentation.ts	19.52 KB	19.52 KB	0.00 KB (0.00%)
schema.ts	18.41 KB	18.41 KB	0.00 KB (0.00%)
stm.ts	12.54 KB	12.54 KB	0.00 KB (0.00%)
stream.ts	9.79 KB	9.80 KB	-0.01 KB (-0.08%)