[SMT-0001]: task-local metrics factory proposal implementation draft

Benchmarks/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+/.build
+/Packages
+xcuserdata/
+DerivedData/
+.swiftpm/configuration/registries.json
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.netrc

Benchmarks/Benchmarks/MetricsBenchmarks/MetricsBenchmarks.swift

@@ -0,0 +1,79 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Metrics API open source project
+//
+// Copyright (c) 2026 Apple Inc. and the Swift Metrics API project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift Metrics API project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import Benchmark
+import CoreMetrics
+import Metrics
+import MetricsTestKit
+
+public func makeBenchmark(
+    _ suffix: String = "",
+    _ body: @escaping (Benchmark) -> Void
+) {
+    let iterations = 1_000_000
+    let metrics: [BenchmarkMetric] = [.instructions, .objectAllocCount]
+
+    Benchmark(
+        "metrics_benchmark_\(suffix)",
+        configuration: .init(
+            metrics: metrics,
+            maxIterations: iterations,
+            thresholds: [
+                .instructions: BenchmarkThresholds(
+                    relative: [
+                        .p90: 1.0  // we only record p90
+                    ]
+                ),
+                .objectAllocCount: BenchmarkThresholds(
+                    absolute: [
+                        .p90: 0  // we only record p90
+                    ]
+                ),
+            ]
+        )
+    ) { benchmark in
+        body(benchmark)
+    }
+}
+
+public let benchmarks: @Sendable () -> Void = {
+    let metricsFactory = TestMetrics()
+    MetricsSystem.bootstrap(metricsFactory)
+
+    makeBenchmark("task-local-init") { benchmark in
+        withMetricsFactory(changingFactory: metricsFactory) {
+            benchmark.startMeasurement()
+            let _ = Timer(label: "test-timer")
+            let _ = Counter(label: "test-counter")
+            let _ = Gauge(label: "test-gauge")
+            benchmark.stopMeasurement()
+        }
+    }
+    makeBenchmark("explicit-init") { benchmark in
+        benchmark.startMeasurement()
+        let _ = Timer(label: "test-timer", factory: metricsFactory)
+        let _ = Counter(label: "test-counter", factory: metricsFactory)
+        let _ = Gauge(label: "test-gauge", factory: metricsFactory)
+        benchmark.stopMeasurement()
+    }
+    makeBenchmark("explicit-init-with-current") { benchmark in
+        withMetricsFactory(changingFactory: metricsFactory) {
+            benchmark.startMeasurement()
+            let _ = Timer(label: "test-timer", factory: MetricsSystem.currentFactory)
+            let _ = Counter(label: "test-counter", factory: MetricsSystem.currentFactory)
+            let _ = Gauge(label: "test-gauge", factory: MetricsSystem.currentFactory)
+            benchmark.stopMeasurement()
+        }
+    }
+}

Benchmarks/Benchmarks/Thresholds/dev/MetricsBenchmarks.metrics_benchmark_init.p90.json

@@ -0,0 +1,4 @@
+{
+  "instructions" : 10855,
+  "objectAllocCount" : 3
+}

Benchmarks/Package.swift

@@ -0,0 +1,33 @@
+// swift-tools-version: 6.0
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "MetricsBenchmarks",
+    platforms: [
+        .macOS(.v13)
+    ],
+    products: [
+        .executable(name: "MetricsBenchmarks", targets: ["MetricsBenchmarks"])
+    ],
+    dependencies: [
+        // swift-metrics
+        .package(name: "swift-metrics", path: "../"),
+        .package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
+    ],
+    targets: [
+        .executableTarget(
+            name: "MetricsBenchmarks",
+            dependencies: [
+                .product(name: "Benchmark", package: "package-benchmark"),
+                .product(name: "CoreMetrics", package: "swift-metrics"),
+                .product(name: "MetricsTestKit", package: "swift-metrics"),
+            ],
+            path: "Benchmarks/MetricsBenchmarks",
+            plugins: [
+                .plugin(name: "BenchmarkPlugin", package: "package-benchmark")
+            ]
+        )
+    ]
+)

README.md

@@ -44,6 +44,74 @@ let counter = Counter(label: "com.example.BestExampleApp.numberOfRequests")
 counter.increment()
 ```
 
+### Correct metrics usage pattern
+
+Metrics objects should be created **once**, with pre-defined labels and dimensions known at initialization time, and
+reused for the lifetime of the component. Creating new metric objects on every request or operation is an antipattern:
+
+- It can lead to **unbounded memory allocation** if the labels or dimensions are unbounded (e.g. per-request IDs),
+  causing unbounded cardinality in the metrics backend.
+- It is **slow** and can become a bottleneck for fast parallel execution, since metric creation typically involves
+  factory synchronization and backend registration.
+
+```swift
+// ❌ Creating metrics on demand — unbounded cardinality when dimensions vary per-request
+func handleRequest(requestID: String) {
+    let counter = Counter(label: "requests", dimensions: [("request_id", requestID)])
+    counter.increment()
+}
+
+// ✅ Create metrics once during setup with fixed dimensions and reuse them
+struct RequestHandler {
+    let requestCounter = Counter(label: "requests")
+
+    func handleRequest(requestID: String) {
+        requestCounter.increment()
+    }
+}
+```
+
+When using a scoped factory override — such as `withMetricsFactory(_:)` for testing — the factory is only active for
+the duration of the closure. Any metrics created outside that scope will not see the overridden factory and will fall
+back to the global one. If no global factory has been bootstrapped, such metrics will fail to initialize, providing a
+safeguard against creating metrics outside of the designated setup scope.
+
+```swift
+struct UserService {
+    let counter: Counter
+
+    init() {
+        // ✅ Created during init — picks up the task-local factory
+        self.counter = Counter(label: "users.created")
+    }
+
+    func createUser(name: String) async throws -> User {
+        // ❌ Created on demand — task-local factory is no longer in scope,
+        //    falls back to global; fails if global is not bootstrapped
+        let onDemandCounter = Counter(label: "users.created.on_demand")
+        let user = User()
+        self.counter.increment()
+        return user
+    }
+}
+
+@Test
+func testUserCreation() async throws {
+    let testMetrics = TestMetrics()
+
+    // The task-local factory is only active inside this block
+    let service = withMetricsFactory(testMetrics) {
+        UserService()  // counter is created here — uses testMetrics
+    }
+
+    // service.createUser() runs outside the withMetricsFactory scope,
+    // so onDemandCounter inside it will NOT use testMetrics
+    _ = try await service.createUser(name: "Alice")
+
+    #expect(try testMetrics.expectCounter("users.created").values == [1])
+}
+```
+
 ### Selecting a metrics backend implementation (applications only)
 
 Note: If you are building a library, you don't need to concern yourself with this section. It is the end users of your library (the applications) who will decide which metrics backend to use. Libraries should never change the metrics implementation as that is something owned by the application.

Sources/CoreMetrics/Docs.docc/Proposals/Proposals.md

@@ -35,4 +35,5 @@ If you have any questions, ask in an issue on GitHub.
 
 ## Topics
 
+- <doc:SMT-0001-task-local-metrics-factory>
 - <doc:SMT-NNNN>