Add the TracingMacros module and the @Traced macro

**Motivation:**

Adding tracing to functions can be a slightly invasive modification
because using `withSpan` requires re-indenting the whole function. It
also requires some duplicated modifications when modifying the effects
signatures of functions. We want a macro to perform this transformation.

**Modifications:**

Introduce a TracingMacros module to provide macros for the Tracing
package. Add a `@Traced` macro that performs the transformation.

This is defined as a separate product so that users who don't want to
pay the compile-time cost of macros don't have to use it, you opt-in to
that cost by depending on the TracingMacros module.

The `@Traced` macro is only available in Swift 6.0 compilers since
function body macros were introduced in Swift 6.0.

Author: porglezomp

Package.swift

@@ -1,4 +1,5 @@
 // swift-tools-version:5.9
+import CompilerPluginSupport
 import PackageDescription
 
 let package = Package(
@@ -16,9 +17,16 @@ let package = Package(
                 "TracingOpenTelemetrySemanticConventions",
             ]
         ),
+        .library(
+            name: "TracingMacros",
+            targets: [
+                "TracingMacros",
+            ]
+        ),
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-distributed-tracing.git", from: "1.0.0"),
+        .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "600.0.0-latest"),
     ],
     targets: [
         .target(
@@ -34,5 +42,32 @@ let package = Package(
                 .product(name: "Tracing", package: "swift-distributed-tracing"),
             ]
         ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: TracingMacros
+
+        .target(
+            name: "TracingMacros",
+            dependencies: [
+                .target(name: "TracingMacrosImplementation"),
+                .product(name: "Tracing", package: "swift-distributed-tracing"),
+            ]
+        ),
+        .macro(
+            name: "TracingMacrosImplementation",
+            dependencies: [
+                .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+                .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
+            ]
+        ),
+        .testTarget(
+            name: "TracingMacrosTests",
+            dependencies: [
+                .target(name: "TracingMacros"),
+                .target(name: "TracingMacrosImplementation"),
+                .product(name: "Tracing", package: "swift-distributed-tracing"),
+                .product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax"),
+            ]
+        ),
     ]
 )

Sources/TracingMacros/Docs.docc/index.md

@@ -0,0 +1,16 @@
+# ``TracingMacros``
+
+Macro helpers for Tracing.
+
+## Overview
+
+The TracingMacros module provides optional macros to make it easier to write traced code.
+
+The ``Traced()`` macro lets you avoid the extra indentation that comes with
+adopting traced code. You can just attach `@Traced` to a function and get
+started.
+
+## Topics
+
+### Tracing functions
+- ``Traced()``

Sources/TracingMacros/TracedMacro.swift

@@ -0,0 +1,24 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Distributed Tracing open source project
+//
+// Copyright (c) 2020-2024 Apple Inc. and the Swift Distributed Tracing project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift Distributed Tracing project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+@_exported import ServiceContextModule
+import Tracing
+
+#if compiler(>=6.0)
+/// Instrument a function to place the entire body inside a span.
+///
+/// This macro is equivalent to calling ``withSpan`` in the body, but saves an
+/// indentation level and duplication.
+@attached(body)
+public macro Traced() = #externalMacro(module: "TracingMacrosImplementation", type: "TracedMacro")
+#endif

Sources/TracingMacrosImplementation/TracedMacro.swift

@@ -0,0 +1,50 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Distributed Tracing open source project
+//
+// Copyright (c) 2020-2024 Apple Inc. and the Swift Distributed Tracing project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift Distributed Tracing project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+import SwiftCompilerPlugin
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+#if compiler(>=6.0)
+public struct TracedMacro: BodyMacro {
+    public static func expansion(
+        of node: AttributeSyntax,
+        providingBodyFor declaration: some DeclSyntaxProtocol & WithOptionalCodeBlockSyntax,
+        in context: some MacroExpansionContext
+    ) throws -> [CodeBlockItemSyntax] {
+        guard let function = declaration.as(FunctionDeclSyntax.self),
+            let body = function.body
+        else {
+            throw MacroExpansionErrorMessage("expected a function with a body")
+        }
+
+        let operationName = StringLiteralExprSyntax(content: function.name.text)
+        let withSpanCall: ExprSyntax = "withSpan(\(operationName))"
+        let withSpanExpr: ExprSyntax = "\(withSpanCall) { span in \(body.statements) }"
+
+        return ["\(withSpanExpr)"]
+    }
+}
+#endif
+
+@main
+struct TracingMacroPlugin: CompilerPlugin {
+    #if compiler(>=6.0)
+    let providingMacros: [Macro.Type] = [
+        TracedMacro.self
+    ]
+    #else
+    let providingMacros: [Macro.Type] = []
+    #endif
+}

Tests/TracingMacrosTests/TracedTests.swift

@@ -0,0 +1,93 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Distributed Tracing open source project
+//
+// Copyright (c) 2020-2024 Apple Inc. and the Swift Distributed Tracing project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift Distributed Tracing project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftSyntaxMacrosTestSupport
+import Tracing
+import TracingMacros
+import TracingMacrosImplementation
+import XCTest
+
+final class TracedMacroTests: XCTestCase {
+    #if compiler(>=6.0)
+    func test_tracedMacro_requires_body() {
+        assertMacroExpansion(
+            """
+            @Traced
+            func funcWithoutBody()
+            """,
+            expandedSource: """
+                func funcWithoutBody()
+                """,
+            diagnostics: [
+                .init(message: "expected a function with a body", line: 1, column: 1)
+            ],
+            macros: ["Traced": TracedMacro.self]
+        )
+    }
+
+    func test_tracedMacro_sync_nothrow() {
+        assertMacroExpansion(
+            """
+            @Traced
+            func syncNonthrowingExample(param: Int) {
+                print(param)
+            }
+            """,
+            expandedSource: """
+                func syncNonthrowingExample(param: Int) {
+                    withSpan("syncNonthrowingExample") { span in
+                        print(param)
+                    }
+                }
+                """,
+            macros: ["Traced": TracedMacro.self]
+        )
+    }
+
+    func test_tracedMacro_accessSpan() {
+        assertMacroExpansion(
+            """
+            @Traced
+            func example(param: Int) {
+                span.attributes["param"] = param
+            }
+            """,
+            expandedSource: """
+                func example(param: Int) {
+                    withSpan("example") { span in
+                        span.attributes["param"] = param
+                    }
+                }
+                """,
+            macros: ["Traced": TracedMacro.self]
+        )
+    }
+    #endif
+}
+
+#if compiler(>=6.0)
+
+// MARK: Compile tests
+
+@Traced
+func syncNonthrowingExample(param: Int) {
+    print(param)
+}
+
+@Traced
+func example(param: Int) {
+    span.attributes["param"] = param
+}
+
+#endif