Adding Resource API - v0 (#81)

Simon Zeltser · SergeyKanzhelev · commit 68bd833e65eb · 2019-01-03T16:28:49.000-08:00
* Adding Resource API - v0 - Added IResource definition based on https://github.com/census-instrumentation/opencensus-proto/blob/master/src/opencensus/proto/resource/v1/resource.proto - Added abstract class that implements IResource. Currently it's a scheleton for adding custom resources. This is needed so that the library can identify the resource for which telemetry is collected. * Addressing comments - mainly avoiding exceptions * Updates to the build process (#76) * snupkg, update the linux image and remove travis * removed publish command. It's unnecessary * remove duplicated commands * added comment * use buildProperties instead of arguments * removed comment and updated to ANY 2.2 * latest 2.2 * Adding Resource API - v0 - Added IResource definition based on https://github.com/census-instrumentation/opencensus-proto/blob/master/src/opencensus/proto/resource/v1/resource.proto - Added abstract class that implements IResource. Currently it's a scheleton for adding custom resources. This is needed so that the library can identify the resource for which telemetry is collected. * Addressing comments - mainly avoiding exceptions * Catch up docs updates after release (#79) * readme and changelog updates * fix issues * fix the license warnings (#83) * fix the license and apply NuGet/Announcements#32 * missed a few files * Make span.Name settable, update it with the route info for ASP.NET Core (#80) * better name * make it work * revert wrong addition * addressed code review * fix build failure and added comment for the sampler * added changelog entry * added route into the attributs as well * IList -> IEnumerable (few of them) (#84) * few IList replaced with IEnumerable * parent links from IList to IEnumerable * a few more of IList -> IEnumerable * one more * stats event with IEnumerable now * smal utils method should not use IList * another utility method * allow net45 compilation for abstractions so some common SDKs may take a dependency on it (#86) * Event logging - docs and a single event example. (#85) * documents * first warning was implemented * first version of docs complete * 1) Removed argument.check method and replaced with direct argument checking 2) Added a few events logging 3) Added tests for Resource parsing (labels and resource type) * Fixing build break * Addressed comments: - Changed IList to IEnumerable - Refined error messages to more details.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ the release.
 - Application Insights exporter improvements - now understands http attributes
   and process links, annotations and messages.
 - ASP.NET Core collector now uses `http.route` for the span name.
+- Initial implementation of Resource Specification.
 
 ## 0.1.0-alpha-33381
 
diff --git a/src/OpenCensus.Abstractions/Resources/IResource.cs b/src/OpenCensus.Abstractions/Resources/IResource.cs
@@ -0,0 +1,40 @@
+﻿// <copyright file="IResource.cs" company="OpenCensus Authors">
+// Copyright 2018, OpenCensus Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace OpenCensus.Resources
+{
+    using System.Collections.Generic;
+    using OpenCensus.Tags;
+
+    /// <summary>
+    /// Represents a resource, which captures identifying information about the entities
+    /// for which signals(stats or traces) are reported. It further provides a framework for detection
+    /// of resource information from the environment and progressive population as signals propagate from
+    /// the core instrumentation library to a backend's exporter.
+    /// </summary>
+    public interface IResource
+    {
+        /// <summary>
+        /// Gets Type identifier for the resource.
+        /// </summary>
+        string Type { get; }
+
+        /// <summary>
+        /// Gets the map of the labels/tags that describe the resource.
+        /// </summary>
+        IEnumerable<ITag> Tags { get; }
+    }
+}
diff --git a/src/OpenCensus.Exporter.Stackdriver/OpenCensus.Exporter.Stackdriver.csproj b/src/OpenCensus.Exporter.Stackdriver/OpenCensus.Exporter.Stackdriver.csproj
@@ -1,9 +1,10 @@
 ﻿<Project Sdk="Microsoft.NET.Sdk">
   <Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildProjectDirectory), 'OpenCensus.sln'))\build\Common.prod.props" />
+  
   <PropertyGroup>
     <TargetFrameworks>net46;netstandard2.0</TargetFrameworks>
     <TargetFrameworks Condition="$(OS) != 'Windows_NT'">netstandard2.0</TargetFrameworks>
-    <Description>Stackdriver Exporter for OpenCensus.</Description>
+    <Description>Stackdriver .NET Exporter for OpenCensus.</Description>
     <IncludeSymbols>True</IncludeSymbols>
     <PackageTags>Tracing;OpenCensus;Management;Monitoring;Stackdriver;Google;GCP;distributed-tracing</PackageTags>
     <PackageIconUrl>https://opencensus.io/images/opencensus-logo.png</PackageIconUrl>
diff --git a/src/OpenCensus/Implementation/Constants.cs b/src/OpenCensus/Implementation/Constants.cs
@@ -0,0 +1,44 @@
+﻿// <copyright file="Resource.cs" company="OpenCensus Authors">
+// Copyright 2018, OpenCensus Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of theLicense at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace OpenCensus.Implementation
+{
+    /// <summary>
+    /// Constants enforced by OpenCensus specifications.
+    /// </summary>
+    internal class Constants
+    {
+        /// <summary>
+        /// Maximum length of the resource type name.
+        /// </summary>
+        public const int MaxResourceTypeNameLength = 255;
+
+        /// <summary>
+        /// Special resource type name that is assigned if nothing else is detected.
+        /// </summary>
+        public const string GlobalResourceType = "Global";
+
+        /// <summary>
+        /// OpenCensus Resource Type Environment Variable Name.
+        /// </summary>
+        public const string ResourceTypeEnvironmentVariable = "OC_RESOURCE_TYPE";
+
+        /// <summary>
+        /// OpenCensus Resource Labels Environment Variable Name.
+        /// </summary>
+        public const string ResourceLabelsEnvironmentVariable = "OC_RESOURCE_LABELS";
+    }
+}
diff --git a/src/OpenCensus/Implementation/OpenCensusEventSource.cs b/src/OpenCensus/Implementation/OpenCensusEventSource.cs
@@ -41,6 +41,27 @@ public void ExporterThrownExceptionWarning(string ex)
             this.WriteEvent(1, ex);
         }
 
+        [Event(2, Message = "Failed to parse a resource tag. {0} should be an ASCII string with a length greater than 0 and not exceeding {1} characters.", Level = EventLevel.Warning)]
+        public void InvalidCharactersInResourceElement(string element)
+        {
+            this.WriteEvent(2, element, Constants.MaxResourceTypeNameLength);
+        }
+
+        [NonEvent]
+        public void FailedReadingEnvironmentVariableWarning(string environmentVariableName, Exception ex)
+        {
+            if (Log.IsEnabled(EventLevel.Warning, EventKeywords.All))
+            {
+                this.FailedReadingEnvironmentVariableWarning(environmentVariableName, ToInvariantString(ex));
+            }
+        }
+
+        [Event(3, Message = "Failed to read environment variable {0}. Main library failed with security exception: {1}", Level = EventLevel.Warning)]
+        public void FailedReadingEnvironmentVariableWarning(string environmentVariableName, string ex)
+        {
+            this.WriteEvent(3, environmentVariableName, ex);
+        }
+
         /// <summary>
         /// Returns a culture-independent string representation of the given <paramref name="exception"/> object, 
         /// appropriate for diagnostics tracing.
diff --git a/src/OpenCensus/Resources/Resource.cs b/src/OpenCensus/Resources/Resource.cs
@@ -0,0 +1,187 @@
+﻿// <copyright file="Resource.cs" company="OpenCensus Authors">
+// Copyright 2018, OpenCensus Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of theLicense at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace OpenCensus.Resources
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Security;
+    using System.Text.RegularExpressions;
+    using OpenCensus.Implementation;
+    using OpenCensus.Tags;
+    using OpenCensus.Utils;
+
+    /// <summary>
+    /// Represents a resource that captures identification information about the entities for which signals (stats or traces)
+    /// are reported. It further provides a framework for detection of resource information from the environment and progressive
+    /// population as signals propagate from the core instrumentation library to a backend's exporter.
+    /// </summary>
+    public abstract class Resource : IResource
+    {
+        /// <summary>
+        /// Tag list splitter.
+        /// </summary>
+        private const char LabelListSplitter = ',';
+
+        /// <summary>
+        /// Key-value splitter.
+        /// </summary>
+        private const char LabelKeyValueSplitter = '=';
+
+        /// <summary>
+        /// Environment identification (for example, AKS/GKE/etc).
+        /// </summary>
+        private static readonly string EnvironmentType;
+
+        private static readonly ITag[] EnvironmentToLabelMap;
+
+        static Resource()
+        {
+            string openCensusResourceType;
+            string openCensusEnvironmentTags;
+
+            try
+            {
+                openCensusResourceType = Environment.GetEnvironmentVariable(Constants.ResourceTypeEnvironmentVariable);
+            }
+            catch (SecurityException ex)
+            {
+                openCensusResourceType = Constants.GlobalResourceType;
+
+                Log.FailedReadingEnvironmentVariableWarning(Constants.ResourceTypeEnvironmentVariable, ex);
+            }
+
+            try
+            {
+                openCensusEnvironmentTags = Environment.GetEnvironmentVariable(Constants.ResourceLabelsEnvironmentVariable);
+            }
+            catch (SecurityException ex)
+            {
+                openCensusEnvironmentTags = string.Empty;
+
+                Log.FailedReadingEnvironmentVariableWarning(Constants.ResourceLabelsEnvironmentVariable, ex);
+            }
+
+            TryParseResourceType(openCensusResourceType, out EnvironmentType);
+            EnvironmentToLabelMap = ParseResourceLabels(Environment.GetEnvironmentVariable(Constants.ResourceLabelsEnvironmentVariable));
+        }
+
+        /// <summary>
+        /// Gets or sets the identification of the resource.
+        /// </summary>
+        public abstract string Type { get; protected set; }
+
+        /// <summary>
+        /// Gets the map between the tag and its value.
+        /// </summary>
+        public abstract IEnumerable<ITag> Tags { get; }
+
+        private static OpenCensusEventSource Log => OpenCensusEventSource.Log;
+
+        /// <summary>
+        /// Creates a label/tag map from the OC_RESOURCE_LABELS environment variable.
+        /// OC_RESOURCE_LABELS: A comma-separated list of labels describing the source in more detail,
+        /// e.g. “key1=val1,key2=val2”. Domain names and paths are accepted as label keys.
+        /// Values may be quoted or unquoted in general. If a value contains whitespaces, =, or " characters, it must
+        /// always be quoted.
+        /// </summary>
+        /// <param name="rawEnvironmentTags">Environment tags as a raw, comma separated string</param>
+        /// <returns>Environment Tags as a list.</returns>
+        internal static ITag[] ParseResourceLabels(string rawEnvironmentTags)
+        {
+            if (rawEnvironmentTags == null)
+            {
+                return new ITag[0] { };
+            }
+            else
+            {
+                var labels = new List<ITag>();
+                string[] rawLabels = rawEnvironmentTags.Split(LabelListSplitter);
+
+                Regex regex = new Regex("^\"|\"$", RegexOptions.Compiled);
+                
+                foreach (var rawLabel in rawLabels)
+                {
+                    string[] keyValuePair = rawLabel.Split(LabelKeyValueSplitter);
+                    if (keyValuePair.Length != 2)
+                    {
+                        continue;
+                    }
+
+                    string key = keyValuePair[0].Trim();
+                    string value = Regex.Replace(keyValuePair[1].Trim(), "^\"|\"$", string.Empty);
+
+                    if (!IsValidAndNotEmpty(key))
+                    {
+                        Log.InvalidCharactersInResourceElement("Label key");
+                        return new ITag[0] { };
+                    }
+
+                    if (!IsValid(value))
+                    {
+                        Log.InvalidCharactersInResourceElement("Label key");
+                        return new ITag[0] { };
+                    }
+
+                    labels.Add(new Tag(TagKey.Create(key), TagValue.Create(value)));
+                }
+
+                return labels.ToArray();
+            }
+        }
+
+        internal static bool TryParseResourceType(string rawEnvironmentType, out string resourceType)
+        {
+            if (string.IsNullOrEmpty(rawEnvironmentType))
+            {
+                resourceType = Constants.GlobalResourceType;
+                return false;
+            }
+
+            if (rawEnvironmentType.Length > Constants.MaxResourceTypeNameLength)
+            {
+                Log.InvalidCharactersInResourceElement(rawEnvironmentType);
+                resourceType = Constants.GlobalResourceType;
+                return false;
+            }
+
+            resourceType = rawEnvironmentType.Trim();
+            return true;
+        }
+
+        /// <summary>
+        /// Checks whether given string is a valid printable ASCII string with a length not exeeding
+        /// <see cref="Constants.MaxResourceTypeNameLength"/> characters.
+        /// </summary>
+        /// <param name="name">The string.</param>
+        /// <returns>Whether given string is valid.</returns>
+        private static bool IsValid(string name)
+        {
+            return name.Length <= Constants.MaxResourceTypeNameLength && StringUtil.IsPrintableString(name);
+        }
+
+        /// <summary>
+        /// Checks whether given string is a valid printable ASCII string with a length
+        /// greater than 0 and not exceeding <see cref="Constants.MaxResourceTypeNameLength"/> characters.
+        /// </summary>
+        /// <param name="name">The string.</param>
+        /// <returns>Whether given string is valid.</returns>
+        private static bool IsValidAndNotEmpty(string name)
+        {
+            return !string.IsNullOrEmpty(name) && IsValid(name);
+        }
+    }
+}
diff --git a/test/OpenCensus.Tests/Impl/Resources/ResourceTest.cs b/test/OpenCensus.Tests/Impl/Resources/ResourceTest.cs
