Merge pull request #20 from Dynatrace/release_171

Release v1.7.1

README.md

@@ -25,7 +25,7 @@ This is the official .NET implementation of the [Dynatrace OneAgent SDK](https:/
   * [Add custom request attributes](#add-custom-request-attributes)
   * [Logging callback](#logging-callback)
   * [SdkState and IOneAgentInfo](#sdkstate-and-ioneagentinfo)
-  * [Metrics](#metrics)
+  * [Metrics (deprecated)](#metrics)
 * [Further reading](#further-readings)
 * [Help & Support](#help--support)
 * [Release notes](#release-notes)
@@ -86,7 +86,7 @@ Common concepts of the Dynatrace OneAgent SDK are explained the
 
 ### IOneAgentSdk object
 
-Use `OneAgentSdkFactory.CreateInstance` to obtain an instace of `IOneAgentSDK`, which is used to create tracers
+Use `OneAgentSdkFactory.CreateInstance` to obtain an instance of `IOneAgentSDK`, which is used to create tracers
 and info objects.
 You should reuse this object over the whole application and if possible CLR lifetime:
 
@@ -142,7 +142,7 @@ public static async Task SampleMethodAsync()
 
 ```
 
->*Note*: Previous versions of the OneAgent SDK supported tracing of asynchronous methods (which are C# methods that are marked with the `async` keyword) using the method `StartAsync()`. This method has been deprecated and the recommended way of tracing asynchronous code are the `TraceAsync` methods (see below).
+>*Note*: Previous versions of the OneAgent SDK supported tracing of asynchronous methods (which are C# methods that are marked with the `async` keyword) using the method `StartAsync()`. This method has been deprecated for technical reasons and the recommended way of tracing asynchronous code are the `TraceAsync` methods (see below).
 
 Additionally the SDK also offers a convenient `Trace` method. This method can be called in both asynchronous and
 synchronous methods. In case of an async method you can pass the given async method to the `TraceAsync` method and
@@ -203,7 +203,7 @@ A more detailed specification of the features can be found in
 
 |Feature                                                                         |Required OneAgent SDK for .NET  version|
 |:-------------------------------------------------------------------------------|:--------------------------------------|
-|Metrics                                                                         |>=1.7.0                                |
+|Metrics (Note: This feature has been **deprecated**)                            |>=1.7.0                                |
 |Support for W3C Trace Context (`IOutgoingWebRequestTracer.InjectTracingHeaders`)|>=1.6.0                                |
 |Trace incoming web requests                                                     |>=1.5.0                                |
 |Trace outgoing web requests                                                     |>=1.4.0                                |
@@ -698,17 +698,25 @@ if (agentInfo.AgentFound)
 See [SdkState.cs](./src/Api/Enums/SdkState.cs) and [IOneAgentInfo.cs](./src/Api/Infos/IOneAgentInfo.cs)
 for further information.
 
-### Metrics
+<a name="metrics"></a>
 
-**The metrics API is currently part of a preview program and will not work for users outside of the preview program. Visit [Dynatrace Help](https://www.dynatrace.com/support/help/whats-new/preview-and-early-adopter-releases/) for details.**
+### Metrics (deprecated)
+
+> **Note**: The metrics API was part of a
+> [Dynatrace preview program](https://www.dynatrace.com/support/help/whats-new/preview-and-early-adopter-releases/)
+> that has been **discontinued**. All metrics-related APIs and types described below
+> have been **deprecated** and will be removed in a future release.
+> The [Metric ingestion](https://www.dynatrace.com/support/help/how-to-use-dynatrace/metrics/metric-ingestion/)
+> page provides further information on how to replace these APIs and how to report
+> metrics data from now on.
 
 The SDK supports two **metric value types**: `Integer` and `Float` (double precision floating point).
 You should prefer integer metrics as they are more efficient, unless the loss of precision is unacceptable (but
-consider using a different unit, e.g. integer microseconds instead of floating point seconds).
+consider using a different unit, e.g. integer microseconds instead of floating-point seconds).
 
 There are different **kinds of metrics**:
 
-* **Counter**: For all metrics that are counting something like sent/received bytes to/from network.
+* **Counter**: For all metrics that are counting something like sent/received bytes to/from the network.
 Counters should only be used when tracking things in flow, as opposed to state. It reports the `sum`
 only and is the most lightweight metric kind.
 * **Gauge**: For metrics that periodically sample a current state, e.g. temperatures, total number
@@ -720,32 +728,13 @@ Each combination of metric value type and kind has its own create-function, name
 
 When creating a metric following information needs to be provided:
 
-* `metricKey` Mandatory - a string identifying the metric. Maximum size is 100 bytes.
+* `metricKey` Mandatory - a string identifying the metric. The maximum size is 100 bytes.
 Although it is not recommended, you may create multiple metric instances with the same name, as long as you use the same creation function (metric value type and kind are the same) and the same options.
 Otherwise, using the same metric name multiple times is an error. All metrics with the same name will be aggregated together as if you used only one metric instance.
 * `unit` Optional - a string that will be displayed when browsing for metrics in the Dynatrace UI.
 * `dimensionName` Optional - a string specifying the name of the dimension added to the metric.
 If a name is given here, it's required to set a dimension value during booking samples on the metric. A dimension is like an additional label attached to values, for example a "disk.written.bytes" metric could have a dimension name of "disk-id" and when adding values to it a dimension value would be "/dev/sda1".
 
-```cs
-IOneAgentSdk oneAgentSdk = OneAgentSdkFactory.CreateInstance();
-
-// create metrics
-IIntegerCounter intCounter = oneAgentSdk.CreateIntegerCounterMetric("aIntCounter");
-IFloatGauge floatGauge = oneAgentSdk.CreateFloatGaugeMetric("aFloatGauge", null, "aDimName" );
-IIntegerStatistics intStatistics = oneAgentSdk.CreateIntegerStatisticsMetric("aIntStat", "aUnit");
-
-// report values
-var random = new System.Random();
-intCounter.IncreaseBy(random.Next(10));
-floatGauge.SetValue(10.0 * random.NextDouble(), "firstDimValue");
-floatGauge.SetValue(10.0 * random.NextDouble(), "secondDimValue");
-intStatistics.AddValue(random.Next(100));
-```
-
-See [MetricSamples.cs](samples/MetricSamples.cs) for more details.
-
-
 ## Further readings
 
 * [What is the OneAgent SDK?](https://www.dynatrace.com/support/help/extend-dynatrace/oneagent-sdk/what-is-oneagent-sdk/) in the Dynatrace documentation
@@ -775,7 +764,7 @@ SLAs don't apply for GitHub tickets
 ### Customers can open a ticket on the [Dynatrace support portal](https://support.dynatrace.com/supportportal/) to
 
 * Get support from the Dynatrace technical support engineering team
-* Manage and resolve product related technical issues
+* Manage and resolve product-related technical issues
 
 SLAs apply according to the customer's support level.
 
@@ -785,6 +774,7 @@ see also [Releases](https://github.com/Dynatrace/OneAgent-SDK-for-dotnet/release
 
 |Version    |Description                                  |
 |:----------|:--------------------------------------------|
+|1.8.0      |Deprecates metrics-related types and APIs |
 |1.7.0      |Adds metrics support (preview only) and deprecates `ITracer.StartAsync` API method |
 |1.6.0      |Adds W3C Trace Context support (`IOutgoingWebRequestTracer.InjectTracingHeaders`)|
 |1.5.0      |Adds incoming web request tracing |

samples/Dynatrace.OneAgent.Sdk.Sample.csproj

@@ -7,7 +7,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Dynatrace.OneAgent.Sdk" Version="1.7.0" />
+    <PackageReference Include="Dynatrace.OneAgent.Sdk" Version="1.7.1" />
   </ItemGroup>
 
 </Project>

samples/SampleApplication.cs

@@ -101,7 +101,6 @@ public static void Main(string[] args)
                 typeof(InProcessLinkTracerSamples),
                 typeof(CustomRequestAttributeSamples),
                 typeof(WebRequestTracerSamples),
-                typeof(MetricSamples),
                 typeof(CombinedSamples)
             };
             var testMethods = GetTestMethods(testClasses).ToList();

src/Api/Enums/ChannelType.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/Enums/DatabaseVendor.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/Enums/MessageDestinationType.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/Enums/MessageSystemVendor.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/Enums/SdkState.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/IDatabaseRequestTracer.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/IInProcessLink.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/IInProcessLinkTracer.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/IIncomingMessageProcessTracer.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/IIncomingMessageReceiveTracer.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/IIncomingRemoteCallTracer.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/IIncomingTaggable.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/IIncomingWebRequestTracer.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/ILoggingCallback.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/IOneAgentSdk.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -14,6 +14,7 @@
 // limitations under the License.
 //
 
+using System;
 using Dynatrace.OneAgent.Sdk.Api.Enums;
 using Dynatrace.OneAgent.Sdk.Api.Infos;
 using Dynatrace.OneAgent.Sdk.Api.Metrics;
@@ -248,6 +249,7 @@ public interface IOneAgentSdk
         /// The metric instance being used for reporting. Returned instances are thread safe and should be reused whenever possible.
         /// Calling this method twice or more with same metric key might return same instance.
         /// </returns>
+        [ObsoleteAttribute("This method is obsolete. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-dotnet#metrics for details.", false)] 
         IIntegerCounter CreateIntegerCounterMetric(string metricKey, string unit = null, string dimensionName = null);
 
         /// <summary>
@@ -257,6 +259,7 @@ public interface IOneAgentSdk
         /// <param name="unit">See <see cref="CreateIntegerCounterMetric(string, string, string)"/></param>
         /// <param name="dimensionName">See parameter <c>dimensionName</c> for <see cref="CreateIntegerCounterMetric(string, string, string)"/></param>
         /// <returns>For details see return value of <see cref="CreateIntegerCounterMetric(string, string, string)"/></returns>
+        [ObsoleteAttribute("This method is obsolete. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-dotnet#metrics for details.", false)] 
         IFloatCounter CreateFloatCounterMetric(string metricKey, string unit = null, string dimensionName = null);
 
         /// <summary>
@@ -270,6 +273,7 @@ public interface IOneAgentSdk
         /// <param name="unit">See <see cref="CreateIntegerCounterMetric(string, string, string)"/></param>
         /// <param name="dimensionName">See parameter <c>dimensionName</c> for <see cref="CreateIntegerCounterMetric(string, string, string)"/></param>
         /// <returns>For details see return value of <see cref="CreateIntegerCounterMetric(string, string, string)"/></returns>
+        [ObsoleteAttribute("This method is obsolete. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-dotnet#metrics for details.", false)] 
         IIntegerGauge CreateIntegerGaugeMetric(string metricKey, string unit = null, string dimensionName = null);
 
         /// <summary>
@@ -279,6 +283,7 @@ public interface IOneAgentSdk
         /// <param name="unit">See <see cref="CreateIntegerCounterMetric(string, string, string)"/></param>
         /// <param name="dimensionName">See parameter <c>dimensionName</c> for <see cref="CreateIntegerCounterMetric(string, string, string)"/></param>
         /// <returns>For details see return value of <see cref="CreateIntegerCounterMetric(string, string, string)"/></returns>
+        [ObsoleteAttribute("This method is obsolete. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-dotnet#metrics for details.", false)] 
         IFloatGauge CreateFloatGaugeMetric(string metricKey, string unit = null, string dimensionName = null);
 
         /// <summary>
@@ -292,6 +297,7 @@ public interface IOneAgentSdk
         /// <param name="unit">See <see cref="CreateIntegerCounterMetric(string, string, string)"/></param>
         /// <param name="dimensionName">See parameter <c>dimensionName</c> for <see cref="CreateIntegerCounterMetric(string, string, string)"/></param>
         /// <returns>For details see return value of <see cref="CreateIntegerCounterMetric(string, string, string)"/></returns>
+        [ObsoleteAttribute("This method is obsolete. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-dotnet#metrics for details.", false)] 
         IIntegerStatistics CreateIntegerStatisticsMetric(string metricKey, string unit = null, string dimensionName = null);
 
         /// <summary>
@@ -301,6 +307,7 @@ public interface IOneAgentSdk
         /// <param name="unit">See <see cref="CreateIntegerCounterMetric(string, string, string)"/></param>
         /// <param name="dimensionName">See parameter <c>dimensionName</c> for <see cref="CreateIntegerCounterMetric(string, string, string)"/></param>
         /// <returns>For details see return value of <see cref="CreateIntegerCounterMetric(string, string, string)"/></returns>
+        [ObsoleteAttribute("This method is obsolete. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-dotnet#metrics for details.", false)] 
         IFloatStatistics CreateFloatStatisticsMetric(string metricKey, string unit = null, string dimensionName = null);
 
         #endregion

src/Api/IOutgoingMessageTracer.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

src/Api/IOutgoingRemoteCallTracer.cs

@@ -1,5 +1,5 @@
 //
-// Copyright 2019 Dynatrace LLC
+// Copyright 2021 Dynatrace LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.