ResourceBuilder API

[CodeBlanch]

Changes - V2.5

Switched Resources API to use a builder pattern.

• Resource implements the specification.
• ResourceBuilder can be used to build up a final Resource from Resources or IResourceDetectors which will be merged together.
• Extension methods on ResourceBuilder give user's a friendly API to work with and extension authors something to extend.
• TracerProviderSdk now uses ResourceBuilder to do its work. SetResource is now SetResourceBuilder.
• Made Resource semantic conventions internal.

Public API Changes

    public class ResourceBuilder
    {
        private ResourceBuilder();
        public static ResourceBuilder CreateDefault();
        public static ResourceBuilder CreateEmpty();

        public ResourceBuilder AddResource(Resource resource);
        public ResourceBuilder Clear();
        public Resource Build();

        // Note: Not public, but might be in the future.
        internal ResourceBuilder AddDetector(IResourceDetector resourceDetector)
    }

    public static class ResourceBuilderExtensions
    {
        public static ResourceBuilder AddService(
            this ResourceBuilder resourceBuilder,
            string serviceName,
            string serviceNamespace = null,
            string serviceVersion = null,
            bool autoGenerateServiceInstanceId = true,
            string serviceInstanceId = null);
        public static ResourceBuilder AddTelemetrySdk(this ResourceBuilder resourceBuilder);
        public static ResourceBuilder AddAttributes(this ResourceBuilder resourceBuilder, IEnumerable<KeyValuePair<string, object>> attributes);
        public static ResourceBuilder AddEnvironmentVariableDetector(this ResourceBuilder resourceBuilder);
    }

    public static class TracerProviderBuilderExtensions
    {
        // Removed
        - public static TracerProviderBuilder SetResource(this TracerProviderBuilder tracerProviderBuilder, Resource resource);

        // Added
        + public static TracerProviderBuilder SetResourceBuilder(this TracerProviderBuilder tracerProviderBuilder, ResourceBuilder resourceBuilder);
    }

Usage

            var resourceBuilder = ResourceBuilder.CreateDefault()
                .AddEnvironmentVariableDetector()
                .AddService("MyService")
                .AddAttributes(new Dictionary<string, object>
                {
                    ["service.datacenter"] = 1,
                });

            var tracerProvider = Sdk.CreateTracerProviderBuilder()
                 .SetResourceBuilder(resourceBuilder)
                 .Build();

TODOs

• CHANGELOG.md updated for non-trivial changes
• Changes in public API reviewed

[codecov]

Codecov Report

Merging #1533 (5e08d0f) into master (65762cd) will decrease coverage by 0.00%.
The diff coverage is 91.22%.

@@            Coverage Diff             @@
##           master    #1533      +/-   ##
==========================================
- Coverage   80.98%   80.98%   -0.01%     
==========================================
  Files         236      237       +1     
  Lines        6433     6453      +20     
==========================================
+ Hits         5210     5226      +16     
- Misses       1223     1227       +4     

Impacted Files	Coverage Δ
...rc/OpenTelemetry.Exporter.Jaeger/JaegerExporter.cs	84.94% <ø> (ø)
...rc/OpenTelemetry.Exporter.Zipkin/ZipkinExporter.cs	88.04% <ø> (ø)
src/OpenTelemetry/Internal/PeerServiceResolver.cs	100.00% <ø> (ø)
src/OpenTelemetry/Resources/Resource.cs	93.33% <ø> (-2.13%)	⬇️
...Telemetry/Trace/TracerProviderBuilderExtensions.cs	70.58% <0.00%> (ø)
...rc/OpenTelemetry/Trace/TracerProviderBuilderSdk.cs	87.03% <90.00%> (+6.26%)	⬆️
src/OpenTelemetry/Resources/ResourceBuilder.cs	90.47% <90.47%> (ø)
...enTelemetry/Resources/ResourceBuilderExtensions.cs	95.65% <95.65%> (ø)
...try.Exporter.OpenTelemetryProtocol/OtlpExporter.cs	58.53% <100.00%> (ø)
...ZPages/Implementation/ZPagesExporterEventSource.cs	56.25% <0.00%> (-6.25%)	⬇️
... and 3 more

[alanwest]

Should the public constants be internal? We don't expose semantic attribute keys but we do resource keys.

My gut says yes. These seem similar to the SemanticConventions class that we've kept internal.

[reyang]

LGTM.

[cijothomas]

Please add entry to changelog.md as this is breaking existing APIs.

[CodeBlanch]

@cijothomas You see the two use cases in the description? How you feel about that? I thought about removing SetResource but I felt like that was still useful.