[Api] GetTracer supports schema URL (#6736)

Author: Kielek

src/OpenTelemetry.Api/.publicApi/Stable/PublicAPI.Unshipped.txt

@@ -0,0 +1,3 @@
+OpenTelemetry.Trace.TracerProvider.GetTracer(string! name, string? version = null, string? schemaUrl = null, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string!, object?>>? tags = null) -> OpenTelemetry.Trace.Tracer!
+OpenTelemetry.Trace.TracerProvider.GetTracer(string! name, string? version, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string!, object?>>? tags) -> OpenTelemetry.Trace.Tracer!
+*REMOVED*OpenTelemetry.Trace.TracerProvider.GetTracer(string! name, string? version = null, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string!, object?>>? tags = null) -> OpenTelemetry.Trace.Tracer!

src/OpenTelemetry.Api/CHANGELOG.md

@@ -6,6 +6,10 @@ Notes](../../RELEASENOTES.md).
 
 ## Unreleased
 
+* Added a new overload for `TracerProvider.GetTracer` which accepts an optional
+  `string? schemaUrl` parameter, allowing a schema URL to be set on the `Tracer`.
+  ([#6736](https://github.com/open-telemetry/opentelemetry-dotnet/pull/6736))
+
 ## 1.14.0
 
 Released 2025-Nov-12

src/OpenTelemetry.Api/Trace/TracerProvider.cs

@@ -40,7 +40,7 @@ public Tracer GetTracer(
 #endif
         string name,
         string? version) =>
-        this.GetTracer(name, version, null);
+        this.GetTracer(name, version, null, null);
 
     /// <summary>
     /// Gets a tracer with given name, version and tags.
@@ -49,12 +49,35 @@ public Tracer GetTracer(
     /// <param name="version">Version of the instrumentation library.</param>
     /// <param name="tags">Tags associated with the tracer.</param>
     /// <returns>Tracer instance.</returns>
+    // 1.14.0 BACKCOMPAT OVERLOAD -- DO NOT TOUCH
+    public Tracer GetTracer(
+#if NET
+        [AllowNull]
+#endif
+        string name,
+        string? version,
+        IEnumerable<KeyValuePair<string, object?>>? tags)
+    {
+        return this.GetTracer(name, version, null, tags);
+    }
+
+    /// <summary>
+    /// Gets a tracer with given name, version and tags.
+    /// </summary>
+    /// <param name="name">Name identifying the instrumentation library.</param>
+    /// <param name="version">Version of the instrumentation library.</param>
+    /// <param name="schemaUrl">Schema URL associated with the tracer.</param>
+    /// <param name="tags">Tags associated with the tracer.</param>
+    /// <returns>Tracer instance.</returns>
     public Tracer GetTracer(
 #if NET
         [AllowNull]
 #endif
         string name,
         string? version = null,
+#pragma warning disable CA1054 // Change the type of attribute from 'string' to 'System.Uri'
+        string? schemaUrl = null,
+#pragma warning restore CA1054 // Change the type of attribute from 'string' to 'System.Uri'
         IEnumerable<KeyValuePair<string, object?>>? tags = null)
     {
         var tracers = this.Tracers;
@@ -64,7 +87,7 @@ public Tracer GetTracer(
             return new(activitySource: null);
         }
 
-        var key = new TracerKey(name, version, tags);
+        var key = new TracerKey(name, version, schemaUrl, tags);
 
         if (!tracers.TryGetValue(key, out var tracer))
         {
@@ -77,7 +100,14 @@ public Tracer GetTracer(
                     return new(activitySource: null);
                 }
 
-                tracer = new(new(key.Name, key.Version, key.Tags));
+                var activitySourceOptions = new System.Diagnostics.ActivitySourceOptions(key.Name)
+                {
+                    Version = key.Version,
+                    Tags = key.Tags,
+                    TelemetrySchemaUrl = key.SchemaUrl,
+                };
+
+                tracer = new(new(activitySourceOptions));
                 bool result = tracers.TryAdd(key, tracer);
 #if DEBUG
                 System.Diagnostics.Debug.Assert(result, "Write into tracers cache failed");
@@ -118,19 +148,22 @@ internal readonly record struct TracerKey
     {
         public readonly string Name;
         public readonly string? Version;
+        public readonly string? SchemaUrl;
         public readonly KeyValuePair<string, object?>[]? Tags;
 
-        public TracerKey(string? name, string? version, IEnumerable<KeyValuePair<string, object?>>? tags)
+        public TracerKey(string? name, string? version, string? schemaUrl, IEnumerable<KeyValuePair<string, object?>>? tags)
         {
             this.Name = name ?? string.Empty;
             this.Version = version;
+            this.SchemaUrl = schemaUrl;
             this.Tags = GetOrderedTags(tags);
         }
 
         public bool Equals(TracerKey other)
         {
             if (!string.Equals(this.Name, other.Name, StringComparison.Ordinal) ||
-                !string.Equals(this.Version, other.Version, StringComparison.Ordinal))
+                !string.Equals(this.Version, other.Version, StringComparison.Ordinal) ||
+                !string.Equals(this.SchemaUrl, other.SchemaUrl, StringComparison.Ordinal))
             {
                 return false;
             }
@@ -146,9 +179,11 @@ public override int GetHashCode()
 #if NET
                 hash = (hash * 31) + (this.Name?.GetHashCode(StringComparison.Ordinal) ?? 0);
                 hash = (hash * 31) + (this.Version?.GetHashCode(StringComparison.Ordinal) ?? 0);
+                hash = (hash * 31) + (this.SchemaUrl?.GetHashCode(StringComparison.Ordinal) ?? 0);
 #else
                 hash = (hash * 31) + (this.Name?.GetHashCode() ?? 0);
                 hash = (hash * 31) + (this.Version?.GetHashCode() ?? 0);
+                hash = (hash * 31) + (this.SchemaUrl?.GetHashCode() ?? 0);
 #endif
 
                 hash = (hash * 31) + GetTagsHashCode(this.Tags);

test/OpenTelemetry.Api.Tests/Trace/TracerTests.cs

@@ -408,6 +408,55 @@ static void InnerTest()
         }
     }
 
+    [Fact]
+    public void GetTracer_WithSameSchemaUrl_ReturnsSameInstance()
+    {
+        var schemaUrl = "http://schema";
+
+        using var tracerProvider = new TestTracerProvider();
+        var tracer1 = tracerProvider.GetTracer("test", "1.0.0", schemaUrl);
+        var tracer2 = tracerProvider.GetTracer("test", "1.0.0", schemaUrl);
+
+        Assert.Same(tracer1, tracer2);
+    }
+
+    [Fact]
+    public void GetTracer_WithDifferentSchemaUrls_ReturnsDifferentInstances()
+    {
+        var schemaUrl1 = "http://schema1";
+        var schemaUrl2 = "http://schema2";
+
+        using var tracerProvider = new TestTracerProvider();
+        var tracer1 = tracerProvider.GetTracer("test", "1.0.0", schemaUrl1);
+        var tracer2 = tracerProvider.GetTracer("test", "1.0.0", schemaUrl2);
+
+        Assert.NotSame(tracer1, tracer2);
+    }
+
+    [Fact]
+    public void GetTracer_WithSchemaUrl_AppliesSchemaUrlToActivities()
+    {
+        var exportedItems = new List<Activity>();
+        var schemaUrl = "http://schema";
+
+        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+            .AddSource("test")
+            .AddInMemoryExporter(exportedItems)
+            .SetSampler(new AlwaysOnSampler())
+            .Build();
+
+        var tracer = tracerProvider.GetTracer("test", "1.0.0", schemaUrl);
+
+        using (tracer.StartActiveSpan("TestSpan"))
+        {
+            // Activity started by the tracer with schema URL
+        }
+
+        var activity = Assert.Single(exportedItems);
+
+        Assert.Equal(schemaUrl, activity.Source.TelemetrySchemaUrl);
+    }
+
     [Fact]
     public void GetTracer_WithSameTags_ReturnsSameInstance()
     {
@@ -535,7 +584,7 @@ public void GetTracer_WithTags_AppliesTagsToActivities()
 
         var tracer = tracerProvider.GetTracer("test", "1.0.0", tags);
 
-        using (var span = tracer.StartActiveSpan("TestSpan"))
+        using (tracer.StartActiveSpan("TestSpan"))
         {
             // Activity started by the tracer with tags
         }