Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a getting started doc for metric #2132

Merged
merged 8 commits into from
Jul 14, 2021
Merged

Add a getting started doc for metric #2132

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0b23319
Add a getting started doc for metric
cijothomas Jul 13, 2021
af3aa22
change exit
cijothomas Jul 13, 2021
6dfcde1
wording
cijothomas Jul 13, 2021
879688f
fix length
cijothomas Jul 13, 2021
921e2fe
add await and delay in tight loop
cijothomas Jul 13, 2021
52ea444
static meter and instr
cijothomas Jul 13, 2021
414e1a4
exit after 10 sec
cijothomas Jul 13, 2021
96cabf3
using token
cijothomas Jul 13, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions OpenTelemetry.sln
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,6 @@ EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "metrics", "metrics", "{3277B1C0-BDFE-4460-9B0D-D9A661FB48DB}"
ProjectSection(SolutionItems) = preProject
docs\metrics\building-your-own-exporter.md = docs\metrics\building-your-own-exporter.md
docs\metrics\getting-started.md = docs\metrics\getting-started.md
EndProjectSection
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "logs", "logs", "{3862190B-E2C5-418E-AFDC-DB281FB5C705}"
Expand Down Expand Up @@ -209,6 +208,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "exception-reporting", "docs
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "customizing-the-sdk", "docs\trace\customizing-the-sdk\customizing-the-sdk.csproj", "{64E3D8BB-93AB-4571-93F7-ED8D64DFFD06}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "getting-started", "docs\metrics\getting-started\getting-started.csproj", "{DFB0AD2F-11BE-4BCD-A77B-1018C3344FA8}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Expand Down Expand Up @@ -407,10 +408,10 @@ Global
{64E3D8BB-93AB-4571-93F7-ED8D64DFFD06}.Debug|Any CPU.Build.0 = Debug|Any CPU
{64E3D8BB-93AB-4571-93F7-ED8D64DFFD06}.Release|Any CPU.ActiveCfg = Release|Any CPU
{64E3D8BB-93AB-4571-93F7-ED8D64DFFD06}.Release|Any CPU.Build.0 = Release|Any CPU
{4481390E-52F5-46A6-8510-3B1433ABAFE6}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{4481390E-52F5-46A6-8510-3B1433ABAFE6}.Debug|Any CPU.Build.0 = Debug|Any CPU
{4481390E-52F5-46A6-8510-3B1433ABAFE6}.Release|Any CPU.ActiveCfg = Release|Any CPU
{4481390E-52F5-46A6-8510-3B1433ABAFE6}.Release|Any CPU.Build.0 = Release|Any CPU
{DFB0AD2F-11BE-4BCD-A77B-1018C3344FA8}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{DFB0AD2F-11BE-4BCD-A77B-1018C3344FA8}.Debug|Any CPU.Build.0 = Debug|Any CPU
{DFB0AD2F-11BE-4BCD-A77B-1018C3344FA8}.Release|Any CPU.ActiveCfg = Release|Any CPU
{DFB0AD2F-11BE-4BCD-A77B-1018C3344FA8}.Release|Any CPU.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
Expand Down Expand Up @@ -443,6 +444,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}
{DFB0AD2F-11BE-4BCD-A77B-1018C3344FA8} = {3277B1C0-BDFE-4460-9B0D-D9A661FB48DB}
EndGlobalSection
GlobalSection(ExtensibilityGlobals) = postSolution
SolutionGuid = {55639B5C-0770-4A22-AB56-859604650521}
Expand Down
3 changes: 0 additions & 3 deletions docs/metrics/building-your-own-exporter.md
View file
Open in desktop

This file was deleted.

12 changes: 0 additions & 12 deletions docs/metrics/getting-started.md
View file
Open in desktop

This file was deleted.

55 changes: 55 additions & 0 deletions docs/metrics/getting-started/Program.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
// <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;
using System.Threading.Tasks;
using OpenTelemetry;
using OpenTelemetry.Metrics;

public class Program
{
public static void Main(string[] args)
{
using var provider = Sdk.CreateMeterProviderBuilder()
cijothomas marked this conversation as resolved.
Show resolved Hide resolved
.AddSource("TestMeter")
.AddExportProcessor(new MetricConsoleExporter())
.Build();

using var meter = new Meter("TestMeter", "0.0.1");
cijothomas marked this conversation as resolved.
Show resolved Hide resolved

Counter<int> counter = meter.CreateCounter<int>("counter");

var token = new CancellationTokenSource();
cijothomas marked this conversation as resolved.
Show resolved Hide resolved
Task writeMetricTask = new Task(() =>
{
while (!token.IsCancellationRequested)
{
counter.Add(
10,
new KeyValuePair<string, object>("tag1", "value1"),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a simpler way to do it in C#? e.g. counter.Add(10, ("tag1", "value1), ("tag2", "value2"))?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not aware of any easier ways. These are the .NET API.

public void Add(T delta);
        public void Add(T delta, KeyValuePair<string, object?> tag);
        public void Add(T delta, KeyValuePair<string, object?> tag1, KeyValuePair<string, object?> tag2);
        public void Add(T delta, KeyValuePair<string, object?> tag1, KeyValuePair<string, object?> tag2, KeyValuePair<string, object?> tag3);
        public void Add(T delta, ReadOnlySpan<KeyValuePair<string, object?>> tags);
        public void Add(T delta, params KeyValuePair<string, object?>[] tags);

new KeyValuePair<string, object>("tag2", "value2"));
cijothomas marked this conversation as resolved.
Show resolved Hide resolved
}
});
writeMetricTask.Start();

Console.WriteLine("Press enter to exit.");
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of taking user input, consider something simpler (e.g. wait for 5 seconds before exit), and put a placeholder comment for Flush (since most users might expect such behavior?).

Console.ReadLine();
token.Cancel();
}
}
59 changes: 59 additions & 0 deletions docs/metrics/getting-started/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# 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
cd getting-started
dotnet run
```

You should see the following output:

```text
Hello World!
```

Install the
[OpenTelemetry](../../../src/OpenTelemetry/README.md)
package:

```sh
dotnet add package OpenTelemetry
```

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[] 14:54:56.162 14:54:57.155 TestMeter:counter [tag1=value1;tag2=value2] SumMetricAggregator Value: 15977610, Details: Delta=True,Mon=True,Count=1597761,Sum=15977610
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: probably not related to this PR, "Mon" could be misleading and we might want "Monotonic".

"Delta=True" - consider something like "Temporality=Delta" (and "Temporality=Cumulative").

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agree. to be addressed when exporter is properly written inside Console exporter package.

Export[] 14:54:57.155 14:54:58.184 TestMeter:counter [tag1=value1;tag2=value2] SumMetricAggregator Value: 21656160, Details: Delta=True,Mon=True,Count=2165616,Sum=21656160
Export[] 14:54:58.184 14:54:59.195 TestMeter:counter [tag1=value1;tag2=value2] SumMetricAggregator Value: 20273630, Details: Delta=True,Mon=True,Count=2027363,Sum=20273630
Export[] 14:54:59.195 14:55:00.209 TestMeter:counter [tag1=value1;tag2=value2] SumMetricAggregator Value: 19113300, Details: Delta=True,Mon=True,Count=1911330,Sum=19113300
Export[] 14:55:00.209 14:55:01.220 TestMeter:counter [tag1=value1;tag2=value2] SumMetricAggregator Value: 17327600, Details: Delta=True,Mon=True,Count=1732760,Sum=17327600
```
<!-- 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 "TestMeter" and then creates a
[Counter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#counter)
instrument from it. This counter is used to repeatedly report metric
measurements until exited.

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.
5 changes: 5 additions & 0 deletions docs/metrics/getting-started/getting-started.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<ProjectReference Include="$(RepoRoot)\src\OpenTelemetry\OpenTelemetry.csproj" />
</ItemGroup>
</Project>
1 change: 0 additions & 1 deletion src/OpenTelemetry/Metrics/AggregatorStore.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,6 @@ internal MetricAgg[] MapToMetrics(string[] seqKey, object[] seqVal)

if (this.instrument.GetType().Name.Contains("Counter"))
{
metricpairs.Add(new MetricAgg(timeperiod, new SumMetricAggregator(name, dt, tags, false, true)));
metricpairs.Add(new MetricAgg(timeperiod, new SumMetricAggregator(name, dt, tags, true, true)));
cijothomas marked this conversation as resolved.
Show resolved Hide resolved
}
else if (this.instrument.GetType().Name.Contains("Gauge"))
Expand Down
1 change: 0 additions & 1 deletion src/OpenTelemetry/Metrics/MeterProviderSdk.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,6 @@ internal MeterProviderSdk(
{
InstrumentPublished = (instrument, listener) =>
{
Console.WriteLine($"Instrument {instrument.Meter.Name}:{instrument.Name} published.");
if (meterSourcesToSubscribe.ContainsKey(instrument.Meter.Name))
{
var instrumentState = new InstrumentState(this, instrument);
Expand Down
5 changes: 5 additions & 0 deletions src/OpenTelemetry/Metrics/Processors/MetricConsoleExporter.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,11 @@ public class MetricConsoleExporter : MetricProcessor
{
private string name;

public MetricConsoleExporter()
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a bit confusing to have the exporter class derived from processor class.
Not introduced by this PR so no need to block on it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yea. This is something that would be changed.
(Also the ConsoleExporter is not coming from the Exporter.Console package.. Will be fixing all of them in subsequent PRs)

: this(string.Empty)
{
}

public MetricConsoleExporter(string name)
{
this.name = name;
Expand Down