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

Changed getting started docs for .NET to coded instrumentation #3364

Merged
merged 1 commit into from
Nov 8, 2023
Merged

Changed getting started docs for .NET to coded instrumentation #3364

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
186 changes: 64 additions & 122 deletions content/en/docs/instrumentation/net/getting-started.md
View file
Open in desktop
martinjt marked this conversation as resolved.
Show resolved Hide resolved
martinjt marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,8 @@ weight: 10

This page will show you how to get started with OpenTelemetry in .NET.

You will learn how you can instrument a simple .NET application automatically,
in such a way that [traces][], [metrics][] and [logs][] are emitted to the
console.
You will learn how you can instrument a simple .NET application, in such a way
that [traces][], [metrics][] and [logs][] are emitted to the console.

## Prerequisites

Expand All @@ -21,8 +20,10 @@ Ensure that you have the following installed locally:

The following example uses a basic
[Minimal API with ASP.NET Core](https://learn.microsoft.com/aspnet/core/tutorials/min-web-api)
application. If you are not using ASP.NET Core, that's OK — you can still use
OpenTelemetry .NET Automatic Instrumentation.
application. If you are not using a minimal API with ASP.NET Core, that's OK —
you can use OpenTelemetry .NET with other frameworks as well. For a complete
list of libraries for supported frameworks, see the
[registry](/ecosystem/registry/?component=instrumentation&language=dotnet).

For more elaborate examples, see
[examples](/docs/instrumentation/net/examples/).
Expand All @@ -45,14 +46,7 @@ using System.Globalization;
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var logger = app.Logger;

int RollDice()
{
return Random.Shared.Next(1, 7);
}

string HandleRollDice(string? player)
string HandleRollDice([FromServices]ILogger<Program> logger, string? player)
martinjt marked this conversation as resolved.
Show resolved Hide resolved
{
var result = RollDice();

Expand Down Expand Up @@ -103,97 +97,60 @@ dotnet run

## Instrumentation

Next, you'll use a [OpenTelemetry .NET Automatic Instrumentation](../automatic)
to instrument the application at launch time. While you can [configure .NET
Automatic Instrumentation][] in a number of ways, the steps below use Unix-shell
or PowerShell scripts.

> **Note**: PowerShell commands require elevated (administrator) privileges.

1. Download installation scripts from [Releases][] of the
`opentelemetry-dotnet-instrumentation` repository:

{{< tabpane text=true >}} {{% tab Unix-shell %}}

```sh
curl -L -O https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh
```

{{% /tab %}} {{% tab PowerShell - Windows %}}

```powershell
$module_url = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path -UseBasicParsing
```

{{% /tab %}} {{< /tabpane >}}
Next we'll install the instrumentation
[NuGet packages from OpenTelemetry](https://www.nuget.org/profiles/OpenTelemetry)
that will generate the telemetry, and set them up.

2. Execute following script to download automatic instrumentation for your
development environment:

{{< tabpane text=true >}} {{% tab Unix-shell %}}

```sh
./otel-dotnet-auto-install.sh
```

{{% /tab %}} {{% tab PowerShell - Windows %}}

```powershell
Import-Module $download_path
Install-OpenTelemetryCore
```

{{% /tab %}} {{< /tabpane >}}

3. Set and export variables that specify a [console exporter][], then execute
script configuring other necessary environment variables using a notation
suitable for your shell/terminal environment &mdash; we illustrate a notation
for bash-like shells and PowerShell:

{{< tabpane text=true >}} {{% tab Unix-shell %}}
1. Add the packages

```sh
export OTEL_TRACES_EXPORTER=none \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED=true \
OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED=true \
OTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED=true
OTEL_SERVICE_NAME=RollDiceService
. $HOME/.otel-dotnet-auto/instrument.sh
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.AspNetCore --prerelease
dotnet add package OpenTelemetry.Exporter.Console
```

{{% /tab %}} {{% tab PowerShell - Windows %}}

```powershell
$env:OTEL_TRACES_EXPORTER="none"
$env:OTEL_METRICS_EXPORTER="none"
$env:OTEL_LOGS_EXPORTER="none"
$env:OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED="true"
$env:OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED="true"
$env:OTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED="true"
Register-OpenTelemetryForCurrentSession -OTelServiceName "RollDiceService"
2. Setup the OpenTelemetry code

```csharp
var builder = WebApplication.CreateBuilder(args);

const string serviceName = "roll-dice";

builder.Logging.AddOpenTelemetry(options =>
{
options
.SetResourceBuilder(
ResourceBuilder.CreateDefault()
.AddService(serviceName))
.AddConsoleExporter();
});
builder.Services.AddOpenTelemetry()
.ConfigureResource(resource => resource.AddService(serviceName))
.WithTracing(tracing => tracing
.AddAspNetCoreInstrumentation()
.AddConsoleExporter())
.WithMetrics(metrics => metrics
.AddAspNetCoreInstrumentation()
.AddConsoleExporter());

var app = builder.Build();
```

{{% /tab %}} {{< /tabpane >}}

4. Run your **application** once again:
3. Run your **application** once again:

```sh
dotnet run
```

Note the output from the `dotnet run`.

5. From _another_ terminal, send a request using `curl`:
4. From _another_ terminal, send a request using `curl`:

```sh
curl localhost:8080/rolldice
```

6. After about 30 sec, stop the server process.
5. After about 30 sec, stop the server process.

At this point, you should see trace and log output from the server and client
that looks something like this (output is line-wrapped for readability):
Expand All @@ -202,49 +159,49 @@ that looks something like this (output is line-wrapped for readability):
<summary>Traces and Logs</summary>

```log
LogRecord.Timestamp: 2023-08-14T06:44:53.9279186Z
LogRecord.TraceId: 3961d22b5f90bf7662ad4933318743fe
LogRecord.SpanId: 93d5fcea422ff0ac
LogRecord.Timestamp: 2023-10-23T12:13:30.2704325Z
LogRecord.TraceId: 324333ec3bbca04ba7f4be4bf3618cb1
LogRecord.SpanId: e7d3814e31e504eb
LogRecord.TraceFlags: Recorded
LogRecord.CategoryName: simple-dotnet
LogRecord.LogLevel: Information
LogRecord.StateValues (Key:Value):
LogRecord.CategoryName: Program
LogRecord.Severity: Info
LogRecord.SeverityText: Information
LogRecord.Body: Anonymous player is rolling the dice: {result}
LogRecord.Attributes (Key:Value):
result: 1
OriginalFormat (a.k.a Body): Anonymous player is rolling the dice: {result}

Resource associated with LogRecord:
service.name: simple-dotnet
telemetry.auto.version: 0.7.0
service.name: roll-dice
service.instance.id: f20134f3-293f-4cb2-ace3-724b5571ca9a
telemetry.sdk.name: opentelemetry
telemetry.sdk.language: dotnet
telemetry.sdk.version: 1.4.0.802
telemetry.sdk.version: 1.6.0

info: simple-dotnet[0]
Anonymous player is rolling the dice: 1
Activity.TraceId: 3961d22b5f90bf7662ad4933318743fe
Activity.SpanId: 93d5fcea422ff0ac
Activity.TraceId: 324333ec3bbca04ba7f4be4bf3618cb1
Activity.SpanId: e7d3814e31e504eb
Activity.TraceFlags: Recorded
Activity.ActivitySourceName: OpenTelemetry.Instrumentation.AspNetCore
Activity.ActivitySourceName: Microsoft.AspNetCore
Activity.DisplayName: /rolldice
Activity.Kind: Server
Activity.StartTime: 2023-08-14T06:44:53.9278162Z
Activity.Duration: 00:00:00.0049754
Activity.StartTime: 2023-10-23T12:13:30.2163005Z
Activity.Duration: 00:00:00.0585187
Activity.Tags:
net.host.name: localhost
net.host.name: 127.0.0.1
net.host.port: 8080
http.method: GET
http.scheme: http
http.target: /rolldice
http.url: http://localhost:8080/rolldice
http.url: http://127.0.0.1:8080/rolldice
http.flavor: 1.1
http.user_agent: curl/8.0.1
http.user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (HTML, like Gecko) Chrome/118.0.0.0 Safari/537.36 Edg/118.0.2088.61
http.status_code: 200
Resource associated with Activity:
service.name: simple-dotnet
telemetry.auto.version: 0.7.0
service.name: roll-dice
service.instance.id: 36bfe322-51b8-4976-90fc-9186376d6ad0
telemetry.sdk.name: opentelemetry
telemetry.sdk.language: dotnet
telemetry.sdk.version: 1.4.0.802
telemetry.sdk.version: 1.6.0
```

</details>
Expand All @@ -256,16 +213,6 @@ collected (sample excerpt shown):
<summary>Metrics</summary>

```log
Export process.runtime.dotnet.gc.collections.count, Number of garbage collections that have occurred since process start., Meter: OpenTelemetry.Instrumentation.Runtime/1.1.0.2
(2023-08-14T06:12:05.8500776Z, 2023-08-14T06:12:23.7750288Z] generation: gen2 LongSum
Value: 2
(2023-08-14T06:12:05.8500776Z, 2023-08-14T06:12:23.7750288Z] generation: gen1 LongSum
Value: 2
(2023-08-14T06:12:05.8500776Z, 2023-08-14T06:12:23.7750288Z] generation: gen0 LongSum
Value: 6

...

Export http.client.duration, Measures the duration of outbound HTTP requests., Unit: ms, Meter: OpenTelemetry.Instrumentation.Http/1.0.0.0
(2023-08-14T06:12:06.2661140Z, 2023-08-14T06:12:23.7750388Z] http.flavor: 1.1 http.method: POST http.scheme: https http.status_code: 200 net.peer.name: dc.services.visualstudio.com Histogram
Value: Sum: 1330.4766000000002 Count: 5 Min: 50.0333 Max: 465.7936
Expand Down Expand Up @@ -303,11 +250,6 @@ For more:
[traces]: /docs/concepts/signals/traces/
[metrics]: /docs/concepts/signals/metrics/
[logs]: /docs/concepts/signals/logs/
[configure .NET Automatic Instrumentation]: ../automatic
[console exporter]:
https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/config.md#internal-logs
[exporter]:
https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/config.md#exporters
[manual instrumentation]: ../manual
[releases]:
https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases
4 changes: 4 additions & 0 deletions static/refcache.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6211,6 +6211,10 @@
"StatusCode": 200,
"LastSeen": "2023-09-06T15:04:45.63516+02:00"
},
"https://www.nuget.org/profiles/OpenTelemetry": {
"StatusCode": 200,
"LastSeen": "2023-11-08T13:31:10.247781347Z"
},
"https://www.observeany.com/learn/opentelemetry-receiver": {
"StatusCode": 200,
"LastSeen": "2023-08-17T09:39:20.114053+08:00"
Expand Down