Add support to emit CUIs with the duration specified.

PiperOrigin-RevId: 852491650

Author: Mobile Ads Developer Relations

source/plugin/Assets/GoogleMobileAds/Common/Insight.cs

@@ -7,6 +7,12 @@ namespace GoogleMobileAds.Common
     [Serializable]
     public class Insight
     {
+        /// <summary>
+        /// Used to calculate timestamps since the Unix Epoch for .NET Framework 3.5+.
+        /// </summary>
+        internal static readonly DateTime UnixEpoch =
+            new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+
         private static AdPlatform _platform;
         private static string _appId;
         private static string _appVersionName;
@@ -42,7 +48,7 @@ public Insight()
         {
             Success = true;
             StartTimeEpochMillis = (long)DateTime.UtcNow
-                .Subtract(new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc))
+                .Subtract(UnixEpoch)
                 .TotalMilliseconds;
             Platform = _platform;
             AppId = _appId;

source/plugin/Assets/GoogleMobileAds/Common/ProdTracer.cs

@@ -1,21 +1,175 @@
 using System;
+using System.Collections.Generic;
+using System.Threading;
 
 namespace GoogleMobileAds.Common
 {
+    /// <summary>
+    /// Serializable class to hold trace information.
+    /// </summary>
+    [Serializable]
+    internal class TraceInfo
+    {
+        public string Id;
+        /// <summary>
+        /// The name of the trace operation. This is stored on the stack to be retrieved during
+        /// `Dispose()` so the final end-of-trace insight can be emitted with the correct operation
+        /// name.
+        /// </summary>
+        public string OperationName;
+        public long StartTimeEpochMillis;
+    }
+
+    /// <summary>
+    /// Implements tracing by emitting insights (CUIs). It is safe to reuse the same `Tracer`
+    /// instance across multiple threads because the instance itself is stateless, holding only a
+    /// reference to the insights emitter. The actual trace context (the stack of active traces) is
+    /// managed via the `ThreadStatic _traceStack' field.
+    ///
+    /// This design ensures that each thread maintains its own independent trace tree structure
+    /// (nested or single-level), preventing conflicts between concurrent operations on different
+    /// threads.
+    /// </summary>
     public class Tracer : ITracer
     {
-        private class NoOpTrace : ITrace
+        // `AsyncLocal` was intentionally skipped because we need to support .NET Framework 3.5+.
+        [ThreadStatic]
+        private static Stack<TraceInfo> _traceStack;
+        private readonly IInsightsEmitter _insightsEmitter;
+
+        public Tracer(IInsightsEmitter insightsEmitter)
         {
-            public void Dispose() {}
+            _insightsEmitter = insightsEmitter;
         }
 
-        private static readonly NoOpTrace _noOpTrace = new NoOpTrace();
+        internal IInsightsEmitter Emitter
+        {
+            get { return _insightsEmitter; }
+        }
 
-        public Tracer(IInsightsEmitter insightsEmitter) {}
+        /// <summary>
+        /// Retrieves the trace stack for the current thread.
+        /// </summary>
+        internal Stack<TraceInfo> GetTraceStack()
+        {
+            // We lazy-initialize the stack as a singleton to ensure each thread has its
+            // own dedicated context for managing traces.
+            if (_traceStack == null)
+            {
+                _traceStack = new Stack<TraceInfo>();
+            }
+            return _traceStack;
+        }
 
+        /// <summary>
+        /// Starts a new trace.
+        /// </summary>
+        /// <param name="name">The name of the trace operation.</param>
+        /// <returns>A Trace instance.</returns>
         public ITrace StartTrace(string name)
         {
-            return _noOpTrace;
+            Stack<TraceInfo> traceStack = GetTraceStack();
+
+            // If there is already an active trace on this thread's stack,
+            // it becomes the parent of the new trace we are starting.
+            string parentId = traceStack.Count > 0 ? traceStack.Peek().Id : null;
+
+            long startTime = (long)DateTime.UtcNow
+                .Subtract(Insight.UnixEpoch)
+                .TotalMilliseconds;
+
+            TraceInfo traceInfo = new TraceInfo
+            {
+                Id = Guid.NewGuid().ToString(),
+                OperationName = name,
+                StartTimeEpochMillis = startTime,
+            };
+
+            traceStack.Push(traceInfo);
+
+            _insightsEmitter.Emit(new Insight
+            {
+                Tracing = new Insight.TracingActivity
+                {
+                    Id = traceInfo.Id,
+                    OperationName = name,
+                    ParentId = parentId,
+                }
+            });
+
+            return new Trace(traceInfo, parentId, this);
+        }
+
+        /// <summary>
+        /// Represents an active trace.
+        /// </summary>
+        private class Trace : ITrace
+        {
+            private readonly TraceInfo _traceInfo;
+            private readonly string _parentId;
+            private readonly Tracer _tracer;
+            private bool _isDisposed = false;
+            private readonly object _disposeLock = new object();
+
+            public Trace(TraceInfo traceInfo, string parentId, Tracer tracer)
+            {
+                _traceInfo = traceInfo;
+                // We capture the parentId on init to ensure the end-of-trace insight is consistent
+                // with the start-of-trace insight, even if the stack state is modified in between.
+                _parentId = parentId;
+                _tracer = tracer;
+            }
+
+            /// <summary>
+            /// Ends the trace, emits an end-of-trace insight, and cleans up the trace stack.
+            /// This method is thread-safe and idempotent, ensuring that it can be called
+            /// multiple times without causing errors or duplicate insights.
+            /// </summary>
+            public void Dispose()
+            {
+                // Ensures thread-safe idempotency for the disposal logic.
+                lock (_disposeLock)
+                {
+                    if (_isDisposed) return;
+                    _isDisposed = true;
+                }
+                // If LIFO order is maintained, verify current trace is top
+                // before popping to ensure the trace tree structure remains valid.
+                Stack<TraceInfo> traceStack = _tracer.GetTraceStack();
+                if (traceStack.Count > 0 && traceStack.Peek().Id == _traceInfo.Id)
+                {
+                    traceStack.Pop();
+                }
+
+                // If LIFO order is broken, this branch will handle cleanup.
+                else if (traceStack.Count > 0)
+                {
+                    // If top of the stack is not the current trace, this indicates that traces are
+                    // not being disposed in LIFO order (e.g., parent disposed before child), or
+                    // traces are being disposed on different threads without context.
+                    // The stack is likely corrupted, so we clear it to prevent further issues.
+                    traceStack.Clear();
+                }
+
+                long endTime = (long)DateTime.UtcNow
+                    .Subtract(Insight.UnixEpoch)
+                    .TotalMilliseconds;
+
+                // Ensure duration is non-negative.
+                long duration = Math.Max(0, endTime - _traceInfo.StartTimeEpochMillis);
+
+                _tracer.Emitter.Emit(new Insight
+                {
+                    Tracing = new Insight.TracingActivity
+                    {
+                        Id = _traceInfo.Id,
+                        OperationName = _traceInfo.OperationName,
+                        ParentId = _parentId,
+                        DurationMillis = duration,
+                        HasEnded = true,
+                    }
+                });
+            }
         }
     }
 }