also implement function based matching

Author: ktoso

Sources/Tracing/NoOpTracer.swift

@@ -25,6 +25,7 @@ public struct NoOpTracer: Tracer {
         baggage: Baggage,
         ofKind kind: SpanKind,
         at time: DispatchWallTime,
+        function: String,
         file fileID: String,
         line: UInt
     ) -> Span {

Sources/Tracing/Tracer.swift

@@ -30,13 +30,15 @@ public protocol Tracer: Instrument {
     ///   - baggage: The `Baggage` providing information on where to start the new ``Span``.
     ///   - kind: The ``SpanKind`` of the new ``Span``.
     ///   - time: The `DispatchTime` at which to start the new ``Span``.
-    ///   - file: The `fileID` where the span was started.
+    ///   - function: The function name in which the span was started
+    ///   - fileID: The `fileID` where the span was started.
     ///   - line: The file line where the span was started.
     func startSpan(
         _ operationName: String,
         baggage: Baggage,
         ofKind kind: SpanKind,
         at time: DispatchWallTime,
+        function: String,
         file fileID: String,
         line: UInt
     ) -> Span
@@ -57,14 +59,19 @@ extension Tracer {
     ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
     ///   - baggage: Baggage potentially containing trace identifiers of a parent ``Span``.
     ///   - kind: The ``SpanKind`` of the ``Span`` to be created. Defaults to ``SpanKind/internal``.
+    ///   - function: The function name in which the span was started
+    ///   - fileID: The `fileID` where the span was started.
+    ///   - line: The file line where the span was started.
     public func startSpan(
         _ operationName: String,
         baggage: Baggage,
         ofKind kind: SpanKind = .internal,
+        function: String = #function,
         file fileID: String = #fileID,
         line: UInt = #line
     ) -> Span {
-        self.startSpan(operationName, baggage: baggage, ofKind: kind, at: .now(), file: fileID, line: line)
+        self.startSpan(operationName, baggage: baggage, ofKind: kind, at: .now(),
+                function: function, file: fileID, line: line)
     }
 }
 
@@ -81,17 +88,22 @@ extension Tracer {
     ///   - baggage: Baggage potentially containing trace identifiers of a parent ``Span``.
     ///   - kind: The ``SpanKind`` of the ``Span`` to be created. Defaults to ``SpanKind/internal``.
     ///   - operation: operation to wrap in a span start/end and execute immediately
+    ///   - function: The function name in which the span was started
+    ///   - fileID: The `fileID` where the span was started.
+    ///   - line: The file line where the span was started.
     /// - Returns: the value returned by `operation`
     /// - Throws: the error the `operation` has thrown (if any)
     public func withSpan<T>(
         _ operationName: String,
         baggage: Baggage,
         ofKind kind: SpanKind = .internal,
+        function: String = #function,
         file fileID: String = #fileID,
         line: UInt = #line,
         _ operation: (Span) throws -> T
     ) rethrows -> T {
-        let span = self.startSpan(operationName, baggage: baggage, ofKind: kind, at: .now(), file: fileID, line: line)
+        let span = self.startSpan(operationName, baggage: baggage, ofKind: kind, at: .now(),
+                function: function, file: fileID, line: line)
         defer { span.end() }
         do {
             return try operation(span)
@@ -117,16 +129,21 @@ extension Tracer {
     ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
     ///   - kind: The ``SpanKind`` of the ``Span`` to be created. Defaults to ``SpanKind/internal``.
     ///   - operation: operation to wrap in a span start/end and execute immediately
+    ///   - function: The function name in which the span was started
+    ///   - fileID: The `fileID` where the span was started.
+    ///   - line: The file line where the span was started.
     /// - Returns: the value returned by `operation`
     /// - Throws: the error the `operation` has thrown (if any)
     public func withSpan<T>(
         _ operationName: String,
         ofKind kind: SpanKind = .internal,
+        function: String = #function,
         file fileID: String = #fileID,
         line: UInt = #line,
         _ operation: (Span) throws -> T
     ) rethrows -> T {
-        try self.withSpan(operationName, baggage: .current ?? .topLevel, ofKind: kind, file: fileID, line: line) { span in
+        try self.withSpan(operationName, baggage: .current ?? .topLevel, ofKind: kind,
+                function: function, file: fileID, line: line) { span in
             try Baggage.$current.withValue(span.baggage) {
                 try operation(span)
             }
@@ -142,16 +159,21 @@ extension Tracer {
     ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
     ///   - kind: The ``SpanKind`` of the ``Span`` to be created. Defaults to ``SpanKind/internal``.
     ///   - operation: operation to wrap in a span start/end and execute immediately
+    ///   - function: The function name in which the span was started
+    ///   - fileID: The `fileID` where the span was started.
+    ///   - line: The file line where the span was started.
     /// - Returns: the value returned by `operation`
     /// - Throws: the error the `operation` has thrown (if any)
     public func withSpan<T>(
         _ operationName: String,
         ofKind kind: SpanKind = .internal,
+        function: String = #function,
         file fileID: String = #fileID,
         line: UInt = #line,
         _ operation: (Span) async throws -> T
     ) async rethrows -> T {
-        let span = self.startSpan(operationName, baggage: .current ?? .topLevel, ofKind: kind, file: fileID, line: line)
+        let span = self.startSpan(operationName, baggage: .current ?? .topLevel, ofKind: kind,
+                function: function, file: fileID, line: line)
         defer { span.end() }
         do {
             return try await Baggage.$current.withValue(span.baggage) {
@@ -174,17 +196,21 @@ extension Tracer {
     //               task local and modified before passing into this function. The baggage will be made the current task-local baggage for the duration of the `operation`.
     ///   - kind: The `SpanKind` of the `Span` to be created. Defaults to `.internal`.
     ///   - operation: operation to wrap in a span start/end and execute immediately
+    ///   - function: The function name in which the span was started
+    ///   - fileID: The `fileID` where the span was started.
+    ///   - line: The file line where the span was started.
     /// - Returns: the value returned by `operation`
     /// - Throws: the error the `operation` has thrown (if any)
     public func withSpan<T>(
         _ operationName: String,
         baggage: Baggage,
         ofKind kind: SpanKind = .internal,
+        function: String = #function,
         file fileID: String = #fileID,
         line: UInt = #line,
         _ operation: (Span) async throws -> T
     ) async rethrows -> T {
-        let span = self.startSpan(operationName, baggage: baggage, ofKind: kind, file: fileID, line: line)
+        let span = self.startSpan(operationName, baggage: baggage, ofKind: kind, function: function, file: fileID, line: line)
         defer { span.end() }
         do {
             return try await Baggage.$current.withValue(span.baggage) {

Tests/TracingTests/DynamicTracepointTracerTests+XCTest.swift

@@ -26,7 +26,8 @@ extension DynamicTracepointTracerTests {
    @available(*, deprecated, message: "not actually deprecated. Just deprecated to allow deprecated tests (which test deprecated functionality) without warnings")
    static var allTests : [(String, (DynamicTracepointTracerTests) -> () throws -> Void)] {
       return [
-                ("test_adhoc_enableAdHoc", test_adhoc_enableAdHoc),
+                ("test_adhoc_enableBySourceLoc", test_adhoc_enableBySourceLoc),
+                ("test_adhoc_enableByFunction", test_adhoc_enableByFunction),
            ]
    }
 }

Tests/TracingTests/DynamicTracepointTracerTests.swift

@@ -23,7 +23,7 @@ final class DynamicTracepointTracerTests: XCTestCase {
         InstrumentationSystem.bootstrapInternal(nil)
     }
 
-    func test_adhoc_enableAdHoc() {
+    func test_adhoc_enableBySourceLoc() {
         let tracer = DynamicTracepointTestTracer()
 
         InstrumentationSystem.bootstrapInternal(tracer)
@@ -32,36 +32,101 @@ final class DynamicTracepointTracerTests: XCTestCase {
         }
 
         let fileID = #fileID
-        let line: UInt = 7777 // trick number, see withSpan below.
-        tracer.enableTracepoint(fileID: fileID, line: line)
+        let fakeLine: UInt = 77 // trick number, see withSpan below.
+        let fakeNextLine: UInt = fakeLine + 11
+        tracer.enableTracepoint(fileID: fileID, line: fakeLine)
         // Imagine this is set via some "ops command", e.g. `<control> <pid, or ssh or something> trace enable Sample.swift:1234`
         // Effectively enabling tracepoints is similar to tracer bullets, tho bullets are generally "one off",
         // but here we could attach a trace-rate, so e.g.: control `<pid> trace enable Sample:1234 .2` to set 20% sampling rate etc.
 
         tracer.withSpan("dont") { _ in
             // don't capture this span...
         }
-        tracer.withSpan("yes", file: #fileID, line: 7777) { _ in
+        tracer.withSpan("yes", line: fakeLine) { _ in
             // do capture this span, and all child spans of it!
-            tracer.withSpan("yes-inner", file: #fileID, line: 8888) { _ in
+            tracer.withSpan("yes-inner", line: fakeNextLine) { _ in
                 // since the parent of this span was captured, this shall be captured as well
             }
         }
 
         XCTAssertEqual(tracer.spans.count, 2)
         for span in tracer.spans {
-            XCTAssertEqual(span.baggage.traceID, "trace-id-fake-\(fileID)-\(line)")
+            XCTAssertEqual(span.baggage.traceID, "trace-id-fake-\(fileID)-\(fakeLine)")
+        }
+        XCTAssertEqual(tracer.spans[0].baggage.spanID, "span-id-fake-\(fileID)-\(fakeLine)")
+        XCTAssertEqual(tracer.spans[1].baggage.spanID, "span-id-fake-\(fileID)-\(fakeNextLine)")
+    }
+
+    func test_adhoc_enableByFunction() {
+        let tracer = DynamicTracepointTestTracer()
+
+        InstrumentationSystem.bootstrapInternal(tracer)
+        defer {
+            InstrumentationSystem.bootstrapInternal(NoOpTracer())
+        }
+
+        let fileID = #fileID
+        tracer.enableTracepoint(function: "traceMeLogic(fakeLine:)")
+
+        let fakeLine: UInt = 66
+        let fakeNextLine: UInt = fakeLine + 11
+
+        logic(fakeLine: 55)
+        traceMeLogic(fakeLine: fakeLine)
+
+        XCTAssertEqual(tracer.spans.count, 2)
+        for span in tracer.spans {
+            XCTAssertEqual(span.baggage.traceID, "trace-id-fake-\(fileID)-\(fakeLine)")
+        }
+        XCTAssertEqual(tracer.spans[0].baggage.spanID, "span-id-fake-\(fileID)-\(fakeLine)")
+        XCTAssertEqual(tracer.spans[1].baggage.spanID, "span-id-fake-\(fileID)-\(fakeNextLine)")
+    }
+
+    func logic(fakeLine: UInt) {
+        InstrumentationSystem.tracer.withSpan("\(#function)-dont", line: fakeLine) { _ in
+
+        }
+    }
+    func traceMeLogic(fakeLine: UInt) {
+        InstrumentationSystem.tracer.withSpan("\(#function)-yes", line: fakeLine) { _ in
+            InstrumentationSystem.tracer.withSpan("\(#function)-yes-inside", line: fakeLine + 11) { _ in
+                // inside
+            }
         }
-        XCTAssertEqual(tracer.spans[0].baggage.spanID, "span-id-fake-\(fileID)-\(line)")
-        XCTAssertEqual(tracer.spans[1].baggage.spanID, "span-id-fake-\(fileID)-8888")
     }
 }
 
 final class DynamicTracepointTestTracer: Tracer {
     private(set) var activeTracepoints: Set<TracepointID> = []
+
     struct TracepointID: Hashable {
-        let fileID: String
-        let line: UInt
+        let function: String?
+        let fileID: String?
+        let line: UInt?
+
+        func matches(tracepoint: TracepointID) -> Bool {
+            var match = true
+            if let fun = self.function {
+                match = match && fun == tracepoint.function
+                if !match { // short-circuit further checks
+                    return false
+                }
+            }
+            if let fid = self.fileID {
+                match = match && fid == tracepoint.fileID
+                if !match { // short-circuit further checks
+                    return false
+                }
+            }
+            if let l = self.line {
+                match = match && l == tracepoint.line
+                if !match { // short-circuit further checks
+                    return false
+                }
+            }
+
+            return match 
+        }
     }
 
     private(set) var spans: [TracepointSpan] = []
@@ -72,22 +137,22 @@ final class DynamicTracepointTestTracer: Tracer {
                    baggage: InstrumentationBaggage.Baggage,
                    ofKind kind: Tracing.SpanKind,
                    at time: DispatchWallTime,
+                   function: String,
                    file fileID: String,
-                   line: UInt) -> Tracing.Span
-    {
-        let tracepoint = TracepointID(fileID: fileID, line: line)
+                   line: UInt) -> Tracing.Span {
+        let tracepoint = TracepointID(function: function, fileID: fileID, line: line)
         guard self.shouldRecord(tracepoint: tracepoint) else {
             return NoOpTracer.NoOpSpan(baggage: baggage)
         }
 
         let span = TracepointSpan(
-            operationName: operationName,
-            startTime: time,
-            baggage: baggage,
-            kind: kind,
-            file: fileID,
-            line: line,
-            onEnd: onEndSpan
+                operationName: operationName,
+                startTime: time,
+                baggage: baggage,
+                kind: kind,
+                file: fileID,
+                line: line,
+                onEnd: onEndSpan
         )
         self.spans.append(span)
         return span
@@ -115,15 +180,26 @@ final class DynamicTracepointTestTracer: Tracer {
     }
 
     func isActive(tracepoint: TracepointID) -> Bool {
-        self.activeTracepoints.contains(tracepoint)
+        for activeTracepoint in self.activeTracepoints {
+            if activeTracepoint.matches(tracepoint: tracepoint) {
+                return true
+            }
+        }
+        return false
     }
 
     @discardableResult
-    func enableTracepoint(fileID: String, line: UInt) -> Bool {
-        self.activeTracepoints.insert(TracepointID(fileID: fileID, line: line)).inserted
+    func enableTracepoint(fileID: String, line: UInt? = nil) -> Bool {
+        self.activeTracepoints.insert(TracepointID(function: nil, fileID: fileID, line: line)).inserted
     }
 
-    func forceFlush() {}
+    @discardableResult
+    func enableTracepoint(function: String, fileID: String? = nil, line: UInt? = nil) -> Bool {
+        self.activeTracepoints.insert(TracepointID(function: function, fileID: fileID, line: line)).inserted
+    }
+
+    func forceFlush() {
+    }
 
     func extract<Carrier, Extract>(_ carrier: Carrier, into baggage: inout Baggage, using extractor: Extract) where Extract: Extractor, Extract.Carrier == Carrier {
         let traceID = extractor.extract(key: "trace-id", from: carrier) ?? UUID().uuidString
@@ -159,8 +235,7 @@ extension DynamicTracepointTestTracer {
              kind: SpanKind,
              file fileID: String,
              line: UInt,
-             onEnd: @escaping (Span) -> Void)
-        {
+             onEnd: @escaping (Span) -> Void) {
             self.operationName = operationName
             self.startTime = startTime
             self.baggage = baggage

Tests/TracingTests/TestTracer.swift

@@ -27,6 +27,7 @@ final class TestTracer: Tracer {
         baggage: Baggage,
         ofKind kind: SpanKind,
         at time: DispatchWallTime,
+        function: String,
         file fileID: String,
         line: UInt
     ) -> Span {

Tests/TracingTests/TracedLockTests.swift

@@ -64,6 +64,7 @@ private final class TracedLockPrintlnTracer: Tracer {
         baggage: Baggage,
         ofKind kind: SpanKind,
         at time: DispatchWallTime,
+        function: String,
         file fileID: String,
         line: UInt
     ) -> Span {