From 61aaf2e6ed89238e5a90c657905b063aaa9ff132 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 23 Sep 2021 09:37:18 -0700 Subject: [PATCH] Simplify tutorials (#2406) --- OpenTelemetry.sln | 16 +---- docs/metrics/getting-started-gauge/Program.cs | 45 ------------- docs/metrics/getting-started-gauge/README.md | 61 ----------------- .../getting-started-histogram/README.md | 67 ------------------- .../getting-started-histogram.csproj | 6 -- .../Program.cs | 45 ------------- .../README.md | 63 ----------------- .../getting-started-observable-counter.csproj | 6 -- .../Program.cs | 27 +++++++- .../learning-more-instruments/README.md | 3 + .../learning-more-instruments.csproj} | 0 .../ConsoleExporterMetricsExtensions.cs | 7 ++ .../ConsoleExporterOptions.cs | 5 +- 13 files changed, 39 insertions(+), 312 deletions(-) delete mode 100644 docs/metrics/getting-started-gauge/Program.cs delete mode 100644 docs/metrics/getting-started-gauge/README.md delete mode 100644 docs/metrics/getting-started-histogram/README.md delete mode 100644 docs/metrics/getting-started-histogram/getting-started-histogram.csproj delete mode 100644 docs/metrics/getting-started-observable-counter/Program.cs delete mode 100644 docs/metrics/getting-started-observable-counter/README.md delete mode 100644 docs/metrics/getting-started-observable-counter/getting-started-observable-counter.csproj rename docs/metrics/{getting-started-histogram => learning-more-instruments}/Program.cs (55%) create mode 100644 docs/metrics/learning-more-instruments/README.md rename docs/metrics/{getting-started-gauge/getting-started-observable-gauge.csproj => learning-more-instruments/learning-more-instruments.csproj} (100%) diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index 8cec81b40bc..570f9212a42 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -212,11 +212,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenTelemetry.Instrumentati EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule.Tests", "test\OpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule.Tests\OpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule.Tests.csproj", "{4D7201BC-7124-4401-AD65-FAB58A053D45}" EndProject -Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "getting-started-histogram", "docs\metrics\getting-started-histogram\getting-started-histogram.csproj", "{92ED77A6-37B4-447D-B4C4-15DB005A589C}" -EndProject -Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "getting-started-observable-gauge", "docs\metrics\getting-started-gauge\getting-started-observable-gauge.csproj", "{E7F491CC-C37E-4A56-9CA7-8F77F59E0614}" -EndProject -Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "getting-started-observable-counter", "docs\metrics\getting-started-observable-counter\getting-started-observable-counter.csproj", "{43005998-0247-4620-AF88-27DACD48712E}" +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "learning-more-instruments", "docs\metrics\learning-more-instruments\learning-more-instruments.csproj", "{E7F491CC-C37E-4A56-9CA7-8F77F59E0614}" EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "getting-started", "docs\metrics\getting-started\getting-started.csproj", "{EA60B549-F712-4ABE-8E44-FCA83B78C06E}" EndProject @@ -430,18 +426,10 @@ Global {4D7201BC-7124-4401-AD65-FAB58A053D45}.Debug|Any CPU.Build.0 = Debug|Any CPU {4D7201BC-7124-4401-AD65-FAB58A053D45}.Release|Any CPU.ActiveCfg = Release|Any CPU {4D7201BC-7124-4401-AD65-FAB58A053D45}.Release|Any CPU.Build.0 = Release|Any CPU - {92ED77A6-37B4-447D-B4C4-15DB005A589C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {92ED77A6-37B4-447D-B4C4-15DB005A589C}.Debug|Any CPU.Build.0 = Debug|Any CPU - {92ED77A6-37B4-447D-B4C4-15DB005A589C}.Release|Any CPU.ActiveCfg = Release|Any CPU - {92ED77A6-37B4-447D-B4C4-15DB005A589C}.Release|Any CPU.Build.0 = Release|Any CPU {E7F491CC-C37E-4A56-9CA7-8F77F59E0614}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {E7F491CC-C37E-4A56-9CA7-8F77F59E0614}.Debug|Any CPU.Build.0 = Debug|Any CPU {E7F491CC-C37E-4A56-9CA7-8F77F59E0614}.Release|Any CPU.ActiveCfg = Release|Any CPU {E7F491CC-C37E-4A56-9CA7-8F77F59E0614}.Release|Any CPU.Build.0 = Release|Any CPU - {43005998-0247-4620-AF88-27DACD48712E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {43005998-0247-4620-AF88-27DACD48712E}.Debug|Any CPU.Build.0 = Debug|Any CPU - {43005998-0247-4620-AF88-27DACD48712E}.Release|Any CPU.ActiveCfg = Release|Any CPU - {43005998-0247-4620-AF88-27DACD48712E}.Release|Any CPU.Build.0 = Release|Any CPU {EA60B549-F712-4ABE-8E44-FCA83B78C06E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {EA60B549-F712-4ABE-8E44-FCA83B78C06E}.Debug|Any CPU.Build.0 = Debug|Any CPU {EA60B549-F712-4ABE-8E44-FCA83B78C06E}.Release|Any CPU.ActiveCfg = Release|Any CPU @@ -485,9 +473,7 @@ Global {972396A8-E35B-499C-9BA1-765E9B8822E1} = {77C7929A-2EED-4AA6-8705-B5C443C8AA0F} {08D29501-F0A3-468F-B18D-BD1821A72383} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818} {64E3D8BB-93AB-4571-93F7-ED8D64DFFD06} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818} - {92ED77A6-37B4-447D-B4C4-15DB005A589C} = {3277B1C0-BDFE-4460-9B0D-D9A661FB48DB} {E7F491CC-C37E-4A56-9CA7-8F77F59E0614} = {3277B1C0-BDFE-4460-9B0D-D9A661FB48DB} - {43005998-0247-4620-AF88-27DACD48712E} = {3277B1C0-BDFE-4460-9B0D-D9A661FB48DB} {EA60B549-F712-4ABE-8E44-FCA83B78C06E} = {3277B1C0-BDFE-4460-9B0D-D9A661FB48DB} {A885DBE2-4B82-432C-A77B-19844D7BBC96} = {0169B149-FB8B-46F4-9EF7-8A0E69F8FAAF} {1F9D7748-D099-4E25-97F5-9C969D6FF969} = {3277B1C0-BDFE-4460-9B0D-D9A661FB48DB} diff --git a/docs/metrics/getting-started-gauge/Program.cs b/docs/metrics/getting-started-gauge/Program.cs deleted file mode 100644 index 3082222ee33..00000000000 --- a/docs/metrics/getting-started-gauge/Program.cs +++ /dev/null @@ -1,45 +0,0 @@ -// -// Copyright The OpenTelemetry 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. -// - -using System; -using System.Collections.Generic; -using System.Diagnostics.Metrics; -using System.Threading.Tasks; -using OpenTelemetry; -using OpenTelemetry.Metrics; - -public class Program -{ - private static readonly Meter MyMeter = new Meter("MyCompany.MyProduct.MyLibrary", "1.0"); - - public static async Task Main(string[] args) - { - using var meterProvider = Sdk.CreateMeterProviderBuilder() - .AddSource("MyCompany.MyProduct.MyLibrary") - .AddConsoleExporter() - .Build(); - - var random = new Random(); - MyMeter.CreateObservableGauge( - "MyGauge", - () => new List>() - { - new(random.Next(1, 1000), new("tag1", "value1"), new("tag2", "value2")), - }); - - await Task.Delay(10000); - } -} diff --git a/docs/metrics/getting-started-gauge/README.md b/docs/metrics/getting-started-gauge/README.md deleted file mode 100644 index 6185d374e68..00000000000 --- a/docs/metrics/getting-started-gauge/README.md +++ /dev/null @@ -1,61 +0,0 @@ -# Getting Started with OpenTelemetry .NET in 5 Minutes - -First, download and install the [.NET Core -SDK](https://dotnet.microsoft.com/download) on your computer. - -Create a new console application and run it: - -```sh -dotnet new console --output getting-started-observable-gauge -cd getting-started-observable-gauge -dotnet run -``` - -You should see the following output: - -```text -Hello World! -``` - -Install the -[OpenTelemetry.Exporter.Console](../../../src/OpenTelemetry.Exporter.Console/README.md) -package: - -```sh -dotnet add package --prerelease OpenTelemetry.Exporter.Console -``` - -Update the `Program.cs` file with the code from [Program.cs](./Program.cs): - -Run the application again (using `dotnet run`) and you should see the metric -output from the console, similar to shown below: - - -```text -Service.Nameunknown_service:getting-started-observable-gauge -Export 15:44:05.262 15:44:05.263 Gauge [tag1=value1;tag2=value2] LongGauge, Meter: MyCompany.MyProduct.MyLibrary/1.0 -Value: 306 -Export 15:44:05.262 15:44:06.290 Gauge [tag1=value1;tag2=value2] LongGauge, Meter: MyCompany.MyProduct.MyLibrary/1.0 -Value: 693 -Export 15:44:05.262 15:44:07.302 Gauge [tag1=value1;tag2=value2] LongGauge, Meter: MyCompany.MyProduct.MyLibrary/1.0 -Value: 78 -``` - - -Congratulations! You are now collecting metrics using OpenTelemetry. - -What does the above program do? - -The program creates a -[Meter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#meter) -instance named "MyCompany.MyProduct.MyLibrary" and then creates a [Asynchronous -Gauge](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#asynchronous-gauge) -instrument from it. This Gauge reports a randomly generated number as its -measurement until exited after 10 seconds. - -An OpenTelemetry -[MeterProvider](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#meterprovider) -is configured to subscribe to instruments from the Meter -`MyCompany.MyProduct.MyLibrary`, and aggregate the measurements in-memory. The -pre-aggregated metrics are exported every 1 second to a `ConsoleExporter`. -`ConsoleExporter` simply displays it on the console. diff --git a/docs/metrics/getting-started-histogram/README.md b/docs/metrics/getting-started-histogram/README.md deleted file mode 100644 index fd57a48c7fd..00000000000 --- a/docs/metrics/getting-started-histogram/README.md +++ /dev/null @@ -1,67 +0,0 @@ -# Getting Started with OpenTelemetry .NET in 5 Minutes - -First, download and install the [.NET Core -SDK](https://dotnet.microsoft.com/download) on your computer. - -Create a new console application and run it: - -```sh -dotnet new console --output getting-started-histogram -cd getting-started-histogram -dotnet run -``` - -You should see the following output: - -```text -Hello World! -``` - -Install the -[OpenTelemetry.Exporter.Console](../../../src/OpenTelemetry.Exporter.Console/README.md) -package: - -```sh -dotnet add package --prerelease OpenTelemetry.Exporter.Console -``` - -Update the `Program.cs` file with the code from [Program.cs](./Program.cs): - -Run the application again (using `dotnet run`) and you should see the metric -output from the console, similar to shown below: - - -```text -Export (2021-09-02T01:02:09.8013446Z, 2021-09-02T01:02:19.9749573Z] histogram tag1=value1;tag2=value2 Histogram, Meter: MyCompany.MyProduct.MyLibrary/1.0 -Value: Sum: 304929 Count: 623 -(-Infinity, 0]: 0 -(0, 5]: 5 -(5, 10]: 5 -(10, 25]: 14 -(25, 50]: 15 -(50, 75]: 18 -(75, 100]: 17 -(100, 250]: 91 -(250, 500]: 158 -(500, 1000]: 300 -(1000, +Infinity): 0 -``` - - -Congratulations! You are now collecting histogram metrics using OpenTelemetry. - -What does the above program do? - -The program creates a -[Meter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#meter) -instance named "MyCompany.MyProduct.MyLibrary" and then creates a -[Histogram](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#histogram) -instrument from it. This histogram is used to repeatedly report random metric -measurements until it reaches a certain number of loops. - -An OpenTelemetry -[MeterProvider](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#meterprovider) -is configured to subscribe to instruments from the Meter -`MyCompany.MyProduct.MyLibrary`, and aggregate the measurements in-memory. The -pre-aggregated metrics are exported every 1 second to a `ConsoleExporter`. -`ConsoleExporter` simply displays it on the console. diff --git a/docs/metrics/getting-started-histogram/getting-started-histogram.csproj b/docs/metrics/getting-started-histogram/getting-started-histogram.csproj deleted file mode 100644 index 9f5b6b79bc3..00000000000 --- a/docs/metrics/getting-started-histogram/getting-started-histogram.csproj +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - diff --git a/docs/metrics/getting-started-observable-counter/Program.cs b/docs/metrics/getting-started-observable-counter/Program.cs deleted file mode 100644 index 7663f7bbef4..00000000000 --- a/docs/metrics/getting-started-observable-counter/Program.cs +++ /dev/null @@ -1,45 +0,0 @@ -// -// Copyright The OpenTelemetry 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. -// - -using System.Collections.Generic; -using System.Diagnostics; -using System.Diagnostics.Metrics; -using System.Threading.Tasks; -using OpenTelemetry; -using OpenTelemetry.Metrics; - -public class Program -{ - private static readonly Meter MyMeter = new Meter("MyCompany.MyProduct.MyLibrary", "1.0"); - - public static async Task Main(string[] args) - { - using var meterProvider = Sdk.CreateMeterProviderBuilder() - .AddSource("MyCompany.MyProduct.MyLibrary") - .AddConsoleExporter() - .Build(); - - var process = Process.GetCurrentProcess(); - MyMeter.CreateObservableCounter( - "ProcessCpuTime", - () => new List>() - { - new(process.TotalProcessorTime.TotalMilliseconds, new("tag1", "value1"), new("tag2", "value2")), - }); - - await Task.Delay(10000); - } -} diff --git a/docs/metrics/getting-started-observable-counter/README.md b/docs/metrics/getting-started-observable-counter/README.md deleted file mode 100644 index c470b1e45ee..00000000000 --- a/docs/metrics/getting-started-observable-counter/README.md +++ /dev/null @@ -1,63 +0,0 @@ -# Getting Started with OpenTelemetry .NET in 5 Minutes - -First, download and install the [.NET Core -SDK](https://dotnet.microsoft.com/download) on your computer. - -Create a new console application and run it: - -```sh -dotnet new console --output getting-started-observable-counter -cd getting-started-observable-counter -dotnet run -``` - -You should see the following output: - -```text -Hello World! -``` - -Install the -[OpenTelemetry.Exporter.Console](../../../src/OpenTelemetry.Exporter.Console/README.md) -package: - -```sh -dotnet add package --prerelease OpenTelemetry.Exporter.Console -``` - -Update the `Program.cs` file with the code from [Program.cs](./Program.cs): - -Run the application again (using `dotnet run`) and you should see the metric -output from the console, similar to shown below: - - -```text -Service.Nameunknown_service:getting-started-observable-counter -Export 16:35:25.669 16:35:25.670 observable-counter [tag1=value1;tag2=value2] LongSum, Meter: MyCompany.MyProduct.MyLibrary/1.0 -Value: 10 -Export 16:35:25.669 16:35:26.698 observable-counter [tag1=value1;tag2=value2] LongSum, Meter: MyCompany.MyProduct.MyLibrary/1.0 -Value: 20 -Export 16:35:25.669 16:35:27.711 observable-counter [tag1=value1;tag2=value2] LongSum, Meter: MyCompany.MyProduct.MyLibrary/1.0 -Value: 30 -Export 16:35:25.669 16:35:28.729 observable-counter [tag1=value1;tag2=value2] LongSum, Meter: MyCompany.MyProduct.MyLibrary/1.0 -Value: 40 -``` - - -Congratulations! You are now collecting metrics using OpenTelemetry. - -What does the above program do? - -The program creates a -[Meter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#meter) -instance named "MyCompany.MyProduct.MyLibrary" and then creates a [Asynchronous -Counter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#asynchronous-counter) -instrument from it. This Counter reports an ever increasing number as its -measurement until exited after 10 seconds. - -An OpenTelemetry -[MeterProvider](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#meterprovider) -is configured to subscribe to instruments from the Meter -`MyCompany.MyProduct.MyLibrary`, and aggregate the measurements in-memory. The -pre-aggregated metrics are exported every 1 second to a `ConsoleExporter`. -`ConsoleExporter` simply displays it on the console. diff --git a/docs/metrics/getting-started-observable-counter/getting-started-observable-counter.csproj b/docs/metrics/getting-started-observable-counter/getting-started-observable-counter.csproj deleted file mode 100644 index 9f5b6b79bc3..00000000000 --- a/docs/metrics/getting-started-observable-counter/getting-started-observable-counter.csproj +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - diff --git a/docs/metrics/getting-started-histogram/Program.cs b/docs/metrics/learning-more-instruments/Program.cs similarity index 55% rename from docs/metrics/getting-started-histogram/Program.cs rename to docs/metrics/learning-more-instruments/Program.cs index b28b0f9e5c3..0691e96e692 100644 --- a/docs/metrics/getting-started-histogram/Program.cs +++ b/docs/metrics/learning-more-instruments/Program.cs @@ -15,6 +15,8 @@ // using System; +using System.Collections.Generic; +using System.Diagnostics; using System.Diagnostics.Metrics; using OpenTelemetry; using OpenTelemetry.Metrics; @@ -30,12 +32,33 @@ public static void Main(string[] args) .AddConsoleExporter() .Build(); + var process = Process.GetCurrentProcess(); + + MyMeter.CreateObservableCounter("Thread.CpuTime", () => GetThreadCpuTime(process), "seconds"); + + MyMeter.CreateObservableGauge("Thread.State", () => GetThreadState(process)); + var random = new Random(); var histogram = MyMeter.CreateHistogram("MyHistogram"); + for (int i = 0; i < 1000; i++) + { + histogram.Record(random.Next(1, 1000)); + } + } - for (int i = 0; i < 20000000; i++) + private static IEnumerable> GetThreadCpuTime(Process process) + { + foreach (ProcessThread thread in process.Threads) + { + yield return new(thread.TotalProcessorTime.TotalMilliseconds, new("ProcessId", process.Id), new("ThreadId", thread.Id)); + } + } + + private static IEnumerable> GetThreadState(Process process) + { + foreach (ProcessThread thread in process.Threads) { - histogram.Record(random.Next(1, 1000), new("tag1", "value1"), new("tag2", "value2")); + yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id)); } } } diff --git a/docs/metrics/learning-more-instruments/README.md b/docs/metrics/learning-more-instruments/README.md new file mode 100644 index 00000000000..768f0c52382 --- /dev/null +++ b/docs/metrics/learning-more-instruments/README.md @@ -0,0 +1,3 @@ +# Learning more about Instruments + +TBD diff --git a/docs/metrics/getting-started-gauge/getting-started-observable-gauge.csproj b/docs/metrics/learning-more-instruments/learning-more-instruments.csproj similarity index 100% rename from docs/metrics/getting-started-gauge/getting-started-observable-gauge.csproj rename to docs/metrics/learning-more-instruments/learning-more-instruments.csproj diff --git a/src/OpenTelemetry.Exporter.Console/ConsoleExporterMetricsExtensions.cs b/src/OpenTelemetry.Exporter.Console/ConsoleExporterMetricsExtensions.cs index 6ad8ba1402f..258d418ce92 100644 --- a/src/OpenTelemetry.Exporter.Console/ConsoleExporterMetricsExtensions.cs +++ b/src/OpenTelemetry.Exporter.Console/ConsoleExporterMetricsExtensions.cs @@ -15,6 +15,7 @@ // using System; +using System.Threading; using OpenTelemetry.Exporter; namespace OpenTelemetry.Metrics @@ -39,6 +40,12 @@ public static MeterProviderBuilder AddConsoleExporter(this MeterProviderBuilder configure?.Invoke(options); var exporter = new ConsoleMetricExporter(options); + + if (options.MetricExportIntervalMilliseconds == Timeout.Infinite) + { + return builder.AddMetricReader(new BaseExportingMetricReader(exporter)); + } + return builder.AddMetricReader(new PeriodicExportingMetricReader(exporter, options.MetricExportIntervalMilliseconds)); } } diff --git a/src/OpenTelemetry.Exporter.Console/ConsoleExporterOptions.cs b/src/OpenTelemetry.Exporter.Console/ConsoleExporterOptions.cs index 85ab099748b..3c75ef2d9d1 100644 --- a/src/OpenTelemetry.Exporter.Console/ConsoleExporterOptions.cs +++ b/src/OpenTelemetry.Exporter.Console/ConsoleExporterOptions.cs @@ -14,6 +14,7 @@ // limitations under the License. // +using System.Threading; using OpenTelemetry.Metrics; namespace OpenTelemetry.Exporter @@ -26,9 +27,9 @@ public class ConsoleExporterOptions public ConsoleExporterOutputTargets Targets { get; set; } = ConsoleExporterOutputTargets.Console; /// - /// Gets or sets the metric export interval in milliseconds. The default value is 1000 milliseconds. + /// Gets or sets the metric export interval in milliseconds. The default value is Timeout.Infinite. /// - public int MetricExportIntervalMilliseconds { get; set; } = 1000; + public int MetricExportIntervalMilliseconds { get; set; } = Timeout.Infinite; /// /// Gets or sets the AggregationTemporality used for Histogram