Make the @Traced macro take a TracedOperationName

**Motivation:**

We want to allow richer customization of the operation name in the
`@Traced` macro, in particular the difference between the different ways
you can view a function name.

**Modifications:**

- Add a TracedOperationName type that represents the kinds of operation
  names we want to support.
- Change the `@Traced` macro interface and expansion to use the new
  operation name type.

**Result:**

Now you can write `@Traced(.baseName)`, `@Traced(.fullName)` as well as
`@Traced("custom name here")`, giving more flexibility between types of
operation names.

Author: porglezomp

Sources/TracingMacros/Docs.docc/TracedOperationName.md

@@ -0,0 +1,38 @@
+# ``TracingMacros/TracedOperationName``
+
+### Examples
+
+The default behavior is to use the base name of the function, but you can
+explicitly specify this as well. This creates a span named `"preheatOven"`:
+```swift
+@Traced(.baseName)
+func preheatOven(temperature: Int)
+```
+
+You can request the full name of the function as the span name, this
+creates a span named `"preheatOven(temperature:)"`:
+```swift
+@Traced(.fullName)
+func preheatOven(temperature: Int)
+```
+
+And it is also initializable with a string literal for fully custom names,
+this creates a span explicitly named `"preheat oven"`:
+```swift
+@Traced("preheat oven")
+func preheatOven(temperature: Int)
+```
+And if you need to load an existing string value as a name, you can use
+`.string(someString)` to adapt it.
+
+
+## Topics
+
+### Create Operation Names
+- ``baseName``
+- ``fullName``
+- ``string(_:)``
+- ``init(stringLiteral:)``
+
+### Convert an Operation Name to a String
+- ``operationName(baseName:fullName:)``

Sources/TracingMacros/Docs.docc/index.md

@@ -0,0 +1,19 @@
+# ``TracingMacros``
+
+Macro helpers for Tracing.
+
+## Overview
+
+The TracingMacros module provides optional macros to make it easier to write traced code.
+
+The ``Traced(_:context:ofKind:span:)`` macro lets you avoid the extra indentation that comes with
+adopting traced code, and avoids having to keep the throws/try and async/await
+in-sync with the body. You can just attach `@Traced` to a function and get
+started.
+
+## Topics
+
+### Tracing functions
+- ``Traced(_:context:ofKind:span:)``
+- ``TracedOperationName``
+

Sources/TracingMacros/TracedMacro.swift

@@ -14,25 +14,82 @@
 @_exported import ServiceContextModule
 import Tracing
 
+/// A span name for a traced operation, either derived from the function name or explicitly specified.
+///
+/// When using the ``Traced(_:context:ofKind:span:)`` macro, you can use this to customize the span name.
+public struct TracedOperationName: ExpressibleByStringLiteral {
+    @usableFromInline
+    let value: Name
+
+    @usableFromInline
+    enum Name {
+        case baseName
+        case fullName
+        case string(String)
+    }
+
+    internal init(value: Name) {
+        self.value = value
+    }
+
+    /// Use a literal string as an operation name.
+    public init(stringLiteral: String) {
+        value = .string(stringLiteral)
+    }
+
+    /// Use the base name of the attached function.
+    ///
+    /// For `func preheatOven(temperature: Int)` this is `"preheatOven"`.
+    public static let baseName = TracedOperationName(value: .baseName)
+
+    /// Use the full name of the attached function.
+    ///
+    /// For `func preheatOven(temperature: Int)` this is `"preheatOven(temperature:)"`.
+    /// This is provided by the `#function` macro.
+    public static let fullName = TracedOperationName(value: .fullName)
+
+    /// Use an explicitly specified operation name.
+    public static func string(_ text: String) -> Self {
+        .init(value: .string(text))
+    }
+
+    /// Helper logic to support the `Traced` macro turning this operation name into a string.
+    /// Provided as an inference guide.
+    ///
+    /// - Parameters:
+    ///   - baseName: The value to use for the ``baseName`` case. Must be
+    ///     specified explicitly because there's no equivalent of `#function`.
+    ///   - fullName: The value to use for the ``fullName`` case.
+    @inlinable
+    @_documentation(visibility: internal)
+    public static func _getOperationName(_ name: Self, baseName: String, fullName: String = #function) -> String {
+        switch name.value {
+        case .baseName: baseName
+        case .fullName: fullName
+        case let .string(text): text
+        }
+    }
+}
+
 #if compiler(>=6.0)
 /// Instrument a function to place the entire body inside a span.
 ///
-/// This macro is equivalent to calling ``/Tracing/withSpan`` in the body, but saves an
+/// This macro is equivalent to calling ``withSpan`` in the body, but saves an
 /// indentation level and duplication. It introduces a `span` variable into the
 /// body of the function which can be used to add attributes to the span.
 ///
-/// Parameters are passed directly to ``/Tracing/withSpan`` where applicable,
+/// Parameters are passed directly to ``withSpan`` where applicable,
 /// and omitting the parameters from the macro omit them from the call, falling
 /// back to the default.
 ///
 /// - Parameters:
-///   - operationName: The name of the operation being traced. Defaults to the name of the function.
-///   - context: The `ServiceContext` providing information on where to start the new ``/Tracing/Span``.
-///   - kind: The ``/Tracing/SpanKind`` of the new ``/Tracing/Span``.
+///   - operationName: The name of the operation being traced.
+///   - context: The `ServiceContext` providing information on where to start the new ``Span``.
+///   - kind: The ``SpanKind`` of the new ``Span``.
 ///   - spanName: The name of the span variable to introduce in the function. Pass `"_"` to omit it.
 @attached(body)
 public macro Traced(
-    _ operationName: String? = nil,
+    _ operationName: TracedOperationName = .baseName,
     context: ServiceContext? = nil,
     ofKind kind: SpanKind? = nil,
     span spanName: String = "span"

Sources/TracingMacrosImplementation/TracedMacro.swift

@@ -31,13 +31,20 @@ public struct TracedMacro: BodyMacro {
 
         // Construct a withSpan call matching the invocation of the @Traced macro
         let (operationName, context, kind, spanName) = try extractArguments(from: node)
+        let baseNameExpr = ExprSyntax(StringLiteralExprSyntax(content: function.name.text))
 
         var withSpanCall = FunctionCallExprSyntax("withSpan()" as ExprSyntax)!
-        withSpanCall.arguments.append(
-            LabeledExprSyntax(
-                expression: operationName ?? ExprSyntax(StringLiteralExprSyntax(content: function.name.text))
-            )
-        )
+        let operationNameExpr: ExprSyntax
+        if let operationName {
+            if operationName.is(StringLiteralExprSyntax.self) {
+                operationNameExpr = operationName
+            } else {
+                operationNameExpr = "TracedOperationName._getOperationName(\(operationName), baseName: \(baseNameExpr))"
+            }
+        } else {
+            operationNameExpr = baseNameExpr
+        }
+        withSpanCall.arguments.append(LabeledExprSyntax(expression: operationNameExpr))
         func appendComma() {
             withSpanCall.arguments[withSpanCall.arguments.index(before: withSpanCall.arguments.endIndex)]
                 .trailingComma = .commaToken()

Tests/TracingMacrosTests/TracedTests.swift

@@ -18,9 +18,8 @@ import TracingMacros
 import TracingMacrosImplementation
 import XCTest
 
-#if compiler(>=6.0)
-
 final class TracedMacroTests: XCTestCase {
+    #if compiler(>=6.0)
     func test_tracedMacro_requires_body() {
         assertMacroExpansion(
             """
@@ -237,15 +236,49 @@ final class TracedMacroTests: XCTestCase {
             """
             let globalName = "example"
 
-            @Traced(globalName)
+            @Traced(.string(globalName))
             func example(param: Int) {
                 span.attributes["param"] = param
             }
             """,
             expandedSource: """
                 let globalName = "example"
                 func example(param: Int) {
-                    withSpan(globalName) { span in
+                    withSpan(TracedOperationName._getOperationName(.string(globalName), baseName: "example")) { span in
+                        span.attributes["param"] = param
+                    }
+                }
+                """,
+            macros: ["Traced": TracedMacro.self]
+        )
+
+        assertMacroExpansion(
+            """
+            @Traced(.baseName)
+            func useBaseName(param: Int) {
+                span.attributes["param"] = param
+            }
+            """,
+            expandedSource: """
+                func useBaseName(param: Int) {
+                    withSpan(TracedOperationName._getOperationName(.baseName, baseName: "useBaseName")) { span in
+                        span.attributes["param"] = param
+                    }
+                }
+                """,
+            macros: ["Traced": TracedMacro.self]
+        )
+
+        assertMacroExpansion(
+            """
+            @Traced(.fullName)
+            func useFullName(param: Int) {
+                span.attributes["param"] = param
+            }
+            """,
+            expandedSource: """
+                func useFullName(param: Int) {
+                    withSpan(TracedOperationName._getOperationName(.fullName, baseName: "useFullName")) { span in
                         span.attributes["param"] = param
                     }
                 }
@@ -411,8 +444,31 @@ final class TracedMacroTests: XCTestCase {
             macros: ["Traced": TracedMacro.self]
         )
     }
+
+    #endif
+
+    func test_operationNameBehavior() {
+        XCTAssertEqual(
+            TracedOperationName._getOperationName("example custom", baseName: "test_operationNameBehavior"),
+            "example custom"
+        )
+        XCTAssertEqual(
+            TracedOperationName._getOperationName(.string("example literal"), baseName: "test_operationNameBehavior"),
+            "example literal"
+        )
+        XCTAssertEqual(
+            TracedOperationName._getOperationName(.baseName, baseName: "test_operationNameBehavior"),
+            "test_operationNameBehavior"
+        )
+        XCTAssertEqual(
+            TracedOperationName._getOperationName(.fullName, baseName: "test_operationNameBehavior"),
+            "test_operationNameBehavior()"
+        )
+    }
 }
 
+#if compiler(>=6.0)
+
 // MARK: Compile tests
 
 @Traced
@@ -458,6 +514,23 @@ func example(param: Int) {
     span.attributes["param"] = param
 }
 
+let globalName = "example"
+
+@Traced(.string(globalName))
+func withDynamicOperationName(param: Int) {
+    span.attributes["param"] = param
+}
+
+@Traced(.baseName)
+func useBaseName(param: Int) {
+    span.attributes["param"] = param
+}
+
+@Traced(.fullName)
+func useFullName(param: Int) {
+    span.attributes["param"] = param
+}
+
 @Traced("custom span name", context: .topLevel, ofKind: .client, span: "customSpan")
 func exampleWithParams(span: Int) {
     customSpan.attributes["span"] = span + 1