Simplify tutorials (#2406)

This commit is contained in:
Reiley Yang 2021-09-23 09:37:18 -07:00 committed by GitHub
parent 78baf7c261
commit 61aaf2e6ed
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 40 additions and 313 deletions

View File

@ -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}

View File

@ -1,45 +0,0 @@
// <copyright file="Program.cs" company="OpenTelemetry Authors">
// 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.
// </copyright>
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<long>(
"MyGauge",
() => new List<Measurement<long>>()
{
new(random.Next(1, 1000), new("tag1", "value1"), new("tag2", "value2")),
});
await Task.Delay(10000);
}
}

View File

@ -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:
<!-- markdownlint-disable MD013 -->
```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
```
<!-- markdownlint-enable MD013 -->
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.

View File

@ -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:
<!-- markdownlint-disable MD013 -->
```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
```
<!-- markdownlint-enable MD013 -->
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.

View File

@ -1,6 +0,0 @@
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<ProjectReference Include="$(RepoRoot)\src\OpenTelemetry\OpenTelemetry.csproj" />
<ProjectReference Include="$(RepoRoot)\src\OpenTelemetry.Exporter.Console\OpenTelemetry.Exporter.Console.csproj" />
</ItemGroup>
</Project>

View File

@ -1,45 +0,0 @@
// <copyright file="Program.cs" company="OpenTelemetry Authors">
// 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.
// </copyright>
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<double>(
"ProcessCpuTime",
() => new List<Measurement<double>>()
{
new(process.TotalProcessorTime.TotalMilliseconds, new("tag1", "value1"), new("tag2", "value2")),
});
await Task.Delay(10000);
}
}

View File

@ -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:
<!-- markdownlint-disable MD013 -->
```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
```
<!-- markdownlint-enable MD013 -->
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.

View File

@ -1,6 +0,0 @@
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<ProjectReference Include="$(RepoRoot)\src\OpenTelemetry\OpenTelemetry.csproj" />
<ProjectReference Include="$(RepoRoot)\src\OpenTelemetry.Exporter.Console\OpenTelemetry.Exporter.Console.csproj" />
</ItemGroup>
</Project>

View File

@ -15,6 +15,8 @@
// </copyright>
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Diagnostics.Metrics;
using OpenTelemetry;
using OpenTelemetry.Metrics;
@ -30,12 +32,33 @@ public class Program
.AddConsoleExporter()
.Build();
var process = Process.GetCurrentProcess();
MyMeter.CreateObservableCounter<double>("Thread.CpuTime", () => GetThreadCpuTime(process), "seconds");
MyMeter.CreateObservableGauge<int>("Thread.State", () => GetThreadState(process));
var random = new Random();
var histogram = MyMeter.CreateHistogram<long>("MyHistogram");
for (int i = 0; i < 20000000; i++)
for (int i = 0; i < 1000; i++)
{
histogram.Record(random.Next(1, 1000), new("tag1", "value1"), new("tag2", "value2"));
histogram.Record(random.Next(1, 1000));
}
}
private static IEnumerable<Measurement<double>> 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<Measurement<int>> GetThreadState(Process process)
{
foreach (ProcessThread thread in process.Threads)
{
yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
}
}
}

View File

@ -0,0 +1,3 @@
# Learning more about Instruments
TBD

View File

@ -15,6 +15,7 @@
// </copyright>
using System;
using System.Threading;
using OpenTelemetry.Exporter;
namespace OpenTelemetry.Metrics
@ -39,6 +40,12 @@ namespace OpenTelemetry.Metrics
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));
}
}

View File

@ -14,6 +14,7 @@
// limitations under the License.
// </copyright>
using System.Threading;
using OpenTelemetry.Metrics;
namespace OpenTelemetry.Exporter
@ -26,9 +27,9 @@ namespace OpenTelemetry.Exporter
public ConsoleExporterOutputTargets Targets { get; set; } = ConsoleExporterOutputTargets.Console;
/// <summary>
/// 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 <c>Timeout.Infinite</c>.
/// </summary>
public int MetricExportIntervalMilliseconds { get; set; } = 1000;
public int MetricExportIntervalMilliseconds { get; set; } = Timeout.Infinite;
/// <summary>
/// Gets or sets the AggregationTemporality used for Histogram