8000 Add dotnet docs from /docs folder of opentelemetry-dotnet (#7474) · open-telemetry/opentelemetry.io@bb92749 · GitHub
[go: up one dir, main page]
Skip to content

Commit bb92749

Browse files
theletterfmartincostelloopentelemetrybotcijothomastiffany76
authored
Add dotnet docs from /docs folder of opentelemetry-dotnet (#7474)
Co-authored-by: Martin Costello <martin@martincostello.com> Co-authored-by: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> Co-authored-by: Cijo Thomas <cithomas@microsoft.com> Co-authored-by: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com>
1 parent c6df1ca commit bb92749

28 files changed

+3614
-59
lines changed

‎content/en/announcements/kubecon-india.md‎

Lines changed: 0 additions & 28 deletions
This file was deleted.

‎content/en/docs/languages/dotnet/_index.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,24 @@ weight: 12
99

1010
{{% docs/languages/index-intro dotnet /%}}
1111

12-
## Version Support
12+
## Version support
1313

1414
OpenTelemetry for .NET supports all officially supported versions of
1515
[.NET](https://dotnet.microsoft.com/download/dotnet) and
1616
[.NET Framework](https://dotnet.microsoft.com/download/dotnet-framework) except
1717
for .NET Framework 3.5 SP1.
1818

19+
## Signals
20+
21+
OpenTelemetry .NET supports the following signals:
22+
23+
- [Traces](/docs/languages/dotnet/traces): Learn how to collect distributed
24+
traces in your .NET applications.
25+
- [Metrics](/docs/languages/dotnet/metrics): Learn how to collect metrics in
26+
your .NET applications.
27+
- [Logs](/docs/languages/dotnet/logs): Learn how to collect logs in your .NET
28+
applications.
29+
1930
## Repositories
2031

2132
OpenTelemetry .NET consists of the following repositories:

‎content/en/docs/languages/dotnet/getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Getting Started
33
description: Get telemetry for your app in less than 5 minutes!
4-
weight: 10
4+
weight: 8
55
cSpell:ignore: ASPNETCORE rolldice
66
---
77

‎content/en/docs/languages/dotnet/instrumentation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Instrumentation
3-
weight: 20
3+
weight: 36
44
aliases: [manual]
55
description: Instrumentation for OpenTelemetry .NET
66
cSpell:ignore: dicelib rolldice

‎content/en/docs/languages/dotnet/logs/_index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: OpenTelemetry .NET logs
3+
linkTitle: Logs
4+
description: Use OpenTelemetry .NET to collect and export log telemetry data
5+
weight: 35
6+
---
7+
8+
This section contains information about using OpenTelemetry .NET for logging.
9+
10+
OpenTelemetry .NET Logs provides integration with `ILogger` to collect, process,
11+
and export log data as part of your observability solution.

‎content/en/docs/languages/dotnet/logs/complex-objects.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
---
2+
title: Logging complex objects
3+
linkTitle: Complex objects
4+
description: Learn how to log complex objects with OpenTelemetry .NET
5+
weight: 20
6+
# prettier-ignore
7+
cSpell:ignore: BrandName CompanyName Contoso FoodRecallNotice Listeria monocytogenes ProductDescription ProductType RecallReasonDescription
8+
---
9+
10+
In the
11+
[Getting Started with OpenTelemetry .NET Logs - Console](/docs/languages/dotnet/logs/getting-started-console/)
12+
guide, we learned how to log primitive data types. This guide will show you how
13+
to log complex objects.
14+
15+
## Complex object logging in .NET
16+
17+
Complex object logging was introduced in .NET 8.0 through the
18+
[`LogPropertiesAttribute`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.logpropertiesattribute).
19+
This attribute and the corresponding code generation logic are provided by an
20+
extension package called
21+
[`Microsoft.Extensions.Telemetry.Abstractions`](https://www.nuget.org/packages/Microsoft.Extensions.Telemetry.Abstractions/).
22+
23+
## Prerequisites
24+
25+
- Complete the
26+
[Getting Started with Console](/docs/languages/dotnet/logs/getting-started-console/)
27+
tutorial.
28+
29+
## Implementation steps
30+
31+
### 1. Install the required package
32+
33+
Install the `Microsoft.Extensions.Telemetry.Abstractions` package:
34+
35+
```shell
36+
dotnet add package Microsoft.Extensions.Telemetry.Abstractions
37+
```
38+
39+
### 2. Define a complex data type
40+
41+
Create a struct to represent your complex object:
42+
43+
```csharp
44+
public struct FoodRecallNotice
45+
{
46+
public string? BrandName { get; set; }
47+
public string? ProductDescription { get; set; }
48+
public string? ProductType { get; set; }
49+
public string? RecallReasonDescription { get; set; }
50+
public string? CompanyName { get; set; }
51+
}
52+
```
53+
54+
### 3. Create a logger extension method with LogPropertiesAttribute
55+
56+
Define an extension method for your logger that uses the Define an extension
57+
method to `ILogger` that uses the
58+
59+
```csharp
60+
using Microsoft.Extensions.Logging;
61+
62+
internal static partial class LoggerExtensions
63+
{
64+
[LoggerMessage(LogLevel.Critical)]
65+
public static partial void FoodRecallNotice(
66+
this ILogger logger,
67+
[LogProperties(OmitReferenceName = true)] in FoodRecallNotice foodRecallNotice);
68+
}
69+
```
70+
71+
The `[LogProperties(OmitReferenceName = true)]` attribute instructs the source
72+
generator to:
73+
74+
- Include all properties of the `FoodRecallNotice` as individual log attributes
75+
- Omit the reference name (the parameter name) from the attribute keys
76+
77+
### 4. Log the complex object
78+
79+
Create an instance of your complex object and log it:
80+
81+
```csharp
82+
// Create a complex object
83+
var foodRecallNotice = new FoodRecallNotice
84+
{
85+
BrandName = "Contoso",
86+
ProductDescription = "Salads",
87+
ProductType = "Food & Beverages",
88+
RecallReasonDescription = "due to a possible health risk from Listeria monocytogenes",
89+
CompanyName = "Contoso Fresh Vegetables, Inc.",
90+
};
91+
92+
// Log the complex object
93+
logger.FoodRecallNotice(foodRecallNotice);
94+
```
95+
96+
### 5. Run the application
97+
98+
Run the application, for example using `dotnet run`, and you should see the log
99+
output on the console:
100+
101+
```text
102+
LogRecord.Timestamp: 2024-01-12T19:01:16.0604084Z
103+
LogRecord.CategoryName: Program
104+
LogRecord.Severity: Fatal
105+
LogRecord.SeverityText: Critical
106+
LogRecord.FormattedMessage:
107+
LogRecord.Body:
108+
LogRecord.Attributes (Key:Value):
109+
CompanyName: Contoso Fresh Vegetables, Inc.
110+
RecallReasonDescription: due to a possible health risk from Listeria monocytogenes
111+
ProductType: Food & Beverages
112+
ProductDescription: Salads
113+
BrandName: Contoso
114+
LogRecord.EventId: 252550133
115+
LogRecord.EventName: FoodRecallNotice
116+
```
117+
118+
Notice that each property of the `FoodRecallNotice` object appears as a separate
119+
attribute in the log record.
120+
121+
## LogPropertiesAttribute options
122+
123+
The `LogPropertiesAttribute` provides several options to control how properties
124+
are included in logs:
125+
126+
- **OmitReferenceName**: When set to `true`, the parameter name is omitted from
127+
attribute keys. In the example above, attribute keys are just the property
128+
names (for example, "BrandName") rather than "foodRecallNotice.BrandName".
129+
130+
- **IncludeProperties**: Used to specify which properties should be included. If
131+
not specified, all properties are included.
132+
133+
- **ExcludeProperties**: Used to specify which properties should be excluded
134+
from logging.
135+
136+
- **IncludeSensitive**: When set to `true`, properties marked with `[Sensitive]`
137+
attribute are included in logs. The default is `false`.
138+
139+
## Complete example
140+
141+
Here's a complete example that puts everything together:
142+
143+
```csharp
144+
using System;
145+
using Microsoft.Extensions.Logging;
146+
using OpenTelemetry;
147+
using OpenTelemetry.Logs;
148+
149+
// Complex object definition
150+
public struct FoodRecallNotice
151+
{
152+
public string? BrandName { get; set; }
153+
public string? ProductDescription { get; set; }
154+
public string? ProductType { get; set; }
155+
public string? RecallReasonDescription { get; set; }
156+
public string? CompanyName { get; set; }
157+
}
158+
159+
// Logger extension method
160+
internal static partial class LoggerExtensions
161+
{
162+
[LoggerMessage(LogLevel.Critical)]
163+
public static partial void FoodRecallNotice(
164+
this ILogger logger,
165+
[LogProperties(OmitReferenceName = true)] in FoodRecallNotice foodRecallNotice);
166+
}
167+
168+
// Main program
169+
class Program
170+
{
171+
static void Main(string[] args)
172+
{
173+
// Create a logger factory with OpenTelemetry
174+
using var loggerFactory = LoggerFactory.Create(builder =>
175+
{
176+
builder.AddOpenTelemetry(options =>
177+
{
178+
options.AddConsoleExporter();
179+
});
180+
});
181+
182+
// Get a logger instance
183+
var logger = loggerFactory.CreateLogger<Program>();
184+
185+
// Create a complex object
186+
var foodRecallNotice = new FoodRecallNotice
187+
{
188+
BrandName = "Contoso",
189+
ProductDescription = "Salads",
190+
ProductType = "Food & Beverages",
191+
RecallReasonDescription = "due to a possible health risk from Listeria monocytogenes",
192+
CompanyName = "Contoso Fresh Vegetables, Inc.",
193+
};
194+
195+
// Log the complex object
196+
logger.FoodRecallNotice(foodRecallNotice);
197+
198+
Console.WriteLine("Press any key to exit");
199+
Console.ReadKey();
200+
}
201+
}
202+
```
203+
204+
## Learn more
205+
206+
- [Microsoft.Extensions.Logging.LogPropertiesAttribute](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.logpropertiesattribute)
207+
- [Microsoft.Extensions.Telemetry.Abstractions](https://github.com/dotnet/extensions/blob/main/src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/README.md)
208+
- [Log Correlation in OpenTelemetry .NET](/docs/languages/dotnet/logs/correlation/)
209+
- [OpenTelemetry Logs Data Model](/docs/specs/otel/logs/data-model/)

0 commit comments

Comments
 (0)
0