From b1d6918e0fd0bb6bf5de8c5283d5261bc0a5f8d0 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Mon, 23 Aug 2021 16:17:29 -0700 Subject: [PATCH] Add docs for Gauge instrument (#2276) --- OpenTelemetry.sln | 9 ++- docs/metrics/getting-started-gauge/Program.cs | 52 ++++++++++++++++ docs/metrics/getting-started-gauge/README.md | 61 +++++++++++++++++++ .../getting-started-async-gauge.csproj | 6 ++ .../getting-started-histogram/README.md | 2 +- .../ConsoleMetricExporter.cs | 4 +- 6 files changed, 130 insertions(+), 4 deletions(-) create mode 100644 docs/metrics/getting-started-gauge/Program.cs create mode 100644 docs/metrics/getting-started-gauge/README.md create mode 100644 docs/metrics/getting-started-gauge/getting-started-async-gauge.csproj diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index ec69c97b5..54b985dee 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -214,7 +214,9 @@ 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("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "getting-started-histogram", "docs\metrics\getting-started-histogram\getting-started-histogram.csproj", "{92ED77A6-37B4-447D-B4C4-15DB005A589C}" +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("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "getting-started-async-gauge", "docs\metrics\getting-started-gauge\getting-started-async-gauge.csproj", "{E7F491CC-C37E-4A56-9CA7-8F77F59E0614}" EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution @@ -430,6 +432,10 @@ Global {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 EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE @@ -463,6 +469,7 @@ Global {64E3D8BB-93AB-4571-93F7-ED8D64DFFD06} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818} {DFB0AD2F-11BE-4BCD-A77B-1018C3344FA8} = {3277B1C0-BDFE-4460-9B0D-D9A661FB48DB} {92ED77A6-37B4-447D-B4C4-15DB005A589C} = {3277B1C0-BDFE-4460-9B0D-D9A661FB48DB} + {E7F491CC-C37E-4A56-9CA7-8F77F59E0614} = {3277B1C0-BDFE-4460-9B0D-D9A661FB48DB} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {55639B5C-0770-4A22-AB56-859604650521} diff --git a/docs/metrics/getting-started-gauge/Program.cs b/docs/metrics/getting-started-gauge/Program.cs new file mode 100644 index 000000000..0ebe7f50e --- /dev/null +++ b/docs/metrics/getting-started-gauge/Program.cs @@ -0,0 +1,52 @@ +// +// 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; +using System.Threading.Tasks; +using OpenTelemetry; +using OpenTelemetry.Metrics; + +public class Program +{ + private static readonly Meter MyMeter = new Meter("TestMeter", "0.0.1"); + private static readonly Random RandomGenerator = new Random(); + + public static async Task Main(string[] args) + { + using var meterProvider = Sdk.CreateMeterProviderBuilder() + .AddSource("TestMeter") + .AddConsoleExporter() + .Build(); + + ObservableGauge gauge = MyMeter.CreateObservableGauge( + "Gauge", + () => + { + var tag1 = new KeyValuePair("tag1", "value1"); + var tag2 = new KeyValuePair("tag2", "value2"); + + return new List>() + { + new Measurement(RandomGenerator.Next(1, 1000), tag1, tag2), + }; + }); + + await Task.Delay(10000); + } +} diff --git a/docs/metrics/getting-started-gauge/README.md b/docs/metrics/getting-started-gauge/README.md new file mode 100644 index 000000000..576ba4973 --- /dev/null +++ b/docs/metrics/getting-started-gauge/README.md @@ -0,0 +1,61 @@ +# 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-async-gauge +cd getting-started-async-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 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-gauge +Export 15:44:05.262 15:44:05.263 Gauge [tag1=value1;tag2=value2] LongGauge, Meter: TestMeter/0.0.1 +Value: 306 +Export 15:44:05.262 15:44:06.290 Gauge [tag1=value1;tag2=value2] LongGauge, Meter: TestMeter/0.0.1 +Value: 693 +Export 15:44:05.262 15:44:07.302 Gauge [tag1=value1;tag2=value2] LongGauge, Meter: TestMeter/0.0.1 +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 "TestMeter" 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 randomnly 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 `TestMeter`, 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-gauge/getting-started-async-gauge.csproj b/docs/metrics/getting-started-gauge/getting-started-async-gauge.csproj new file mode 100644 index 000000000..9f5b6b79b --- /dev/null +++ b/docs/metrics/getting-started-gauge/getting-started-async-gauge.csproj @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/metrics/getting-started-histogram/README.md b/docs/metrics/getting-started-histogram/README.md index 0b8e9fabc..b3d864bde 100644 --- a/docs/metrics/getting-started-histogram/README.md +++ b/docs/metrics/getting-started-histogram/README.md @@ -7,7 +7,7 @@ Create a new console application and run it: ```sh dotnet new console --output getting-started-histogram -cd getting-started +cd getting-started-histogram dotnet run ``` diff --git a/src/OpenTelemetry.Exporter.Console/ConsoleMetricExporter.cs b/src/OpenTelemetry.Exporter.Console/ConsoleMetricExporter.cs index f07e7480f..a75d91893 100644 --- a/src/OpenTelemetry.Exporter.Console/ConsoleMetricExporter.cs +++ b/src/OpenTelemetry.Exporter.Console/ConsoleMetricExporter.cs @@ -75,13 +75,13 @@ namespace OpenTelemetry.Exporter case MetricType.LongGauge: { - // TODOs + valueDisplay = (metric as IGaugeMetric).LastValue.Value.ToString(); break; } case MetricType.DoubleGauge: { - // TODOs + valueDisplay = (metric as IGaugeMetric).LastValue.Value.ToString(); break; }