Skip to content

Commit c729c84

Browse files
andrewlocklucaspimentelpierotibouzacharycmontoya
authored
Add README for Datadog.Trace NuGet package (DataDog#2069)
* Remove obsolete build pipeline references from Readme * Add a readme file for Datadog.Trace NuGet package * Apply suggestions from code review Co-authored-by: Lucas Pimentel-Ordyna <lucas.pimentel@datadoghq.com> * Fix AdoNet description We reinstated it in DataDog#2137, so you can use both * Add recent api changes * Revamp documentations in the repo Root readme contains links to components, and download and build status only. Tracer readme ccontains development information and link to the nuget documentation. Profiler readme has been fixed * Apply suggestions from code review Co-authored-by: Zach Montoya <zach.montoya@datadoghq.com> * Implement Zach's suggestions * Apply suggestions from code review * Update docs/Datadog.Trace/README.md Co-authored-by: Zach Montoya <zach.montoya@datadoghq.com> * Update docs/Datadog.Trace/README.md Co-authored-by: Zach Montoya <zach.montoya@datadoghq.com> * Update README.md * Update docs/Datadog.Trace/README.md Co-authored-by: Zach Montoya <zach.montoya@datadoghq.com> * Apply suggestions from code review * add VS2022 and .NET 5 * Apply suggestions from code review * profiler * wip * nest optional aspnet core runtimes * more tweaks * aspnet core runtimes * Apply suggestions from code review * Final changes from Zach? * Update docs/README.md Co-authored-by: Lucas Pimentel-Ordyna <lucas.pimentel@datadoghq.com> Co-authored-by: Pierre Bonet <pierre.bonet@datadoghq.com> Co-authored-by: Zach Montoya <zach.montoya@datadoghq.com>
1 parent 25cf4fa commit c729c84

File tree

5 files changed

+414
-127
lines changed

5 files changed

+414
-127
lines changed

‎docs/Datadog.Trace/README.md

+282
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
# Datadog.Trace NuGet package
2+
3+
This package contains the Datadog .NET APM tracer for configuring custom instrumentation.
4+
5+
> If you are only using automatic instrumentation, **you do not need this package**. Please [read our documentation](https://docs.datadoghq.com/tracing/setup/dotnet) for details on how to install the tracer for automatic instrumentation.
6+
7+
## Getting Started
8+
9+
1. Configure the Datadog agent for APM [as described in our documentation](https://docs.datadoghq.com/tracing/setup_overview/setup/dotnet-core#configure-the-datadog-agent-for-apm).
10+
2. For automatic instrumentation, install and enable the tracer [as described in our documentation](https://docs.datadoghq.com/tracing/setup_overview/setup/dotnet-core/?tab=windows#install-the-tracer).
11+
3. Configure custom instrumentation, as shown below
12+
4. [View your live data on Datadog](https://app.datadoghq.com/apm/traces).
13+
14+
### Configuring Datadog in code
15+
16+
There are multiple ways to configure your application: using environment variables, a `web.config` file, or a `datadog.json` file, [as described in our documentation](https://docs.datadoghq.com/tracing/setup_overview/setup/dotnet-core/#configuration). This NuGet package also allows you to configure settings in code.
17+
18+
To override configuration settings, create an instance of `TracerSettings`, and pass it to the static `Tracer.Configure()` method:
19+
20+
```csharp
21+
using Datadog.Trace;
22+
23+
// Create a settings object using the existing
24+
// environment variables and config sources
25+
var settings = TracerSettings.FromDefaultSources();
26+
27+
// Override a value
28+
settings.GlobalTags.Add("SomeKey", "SomeValue");
29+
30+
// Replace the tracer configuration
31+
Tracer.Configure(settings);
32+
```
33+
34+
Calling `Tracer.Configure()` will replace the settings for all subsequent traces, both for custom instrumentation and for automatic instrumentation.
35+
36+
> :warning: Replacing the configuration should be done once, as early as possible in your application.
37+
38+
### Create custom traces
39+
40+
To create and activate a custom span, use `Tracer.Instance.StartActive()`. If a trace is already active (when created by automatic instrumentation, for example), the span will be part of the current trace. If there is no current trace, a new one will be started.
41+
42+
> :warning: Ensure you dispose of the scope returned from StartActive. Disposing the scope will close the span, and ensure the trace is flushed to Datadog once all its spans are closed.
43+
44+
```csharp
45+
using Datadog.Trace;
46+
47+
// Start a new span
48+
using (var scope = Tracer.Instance.StartActive("custom-operation"))
49+
{
50+
// Do something
51+
}
52+
```
53+
54+
## Release Notes
55+
56+
You can view the [notes for the latest release on GitHub](https://github.com/DataDog/dd-trace-dotnet/releases).
57+
58+
## Upgrading from 1.x to 2.0
59+
60+
.NET Tracer 2.0 introduces several breaking changes to the API which allow various performance improvements, add new features, and deprecate problematic ways of using the package. Most of these changes do not require any changes to your code, but some patterns are no longer supported or recommended.
61+
62+
This section describes some of the most important breaking changes. For full details see [the release notes on GitHub](https://github.com/DataDog/dd-trace-dotnet/releases/tag/v2.0.0).
63+
64+
### Supported .NET versions
65+
66+
.NET Tracer 2.0 adds support for .NET 6.0 and raises the minimum supported version of .NET Framework from .NET Framework 4.5 to .NET Framework 4.6.1. If you are currently targeting version < 4.6.1, we suggest you upgrade [in line with Microsoft's guidance](https://docs.microsoft.com/en-us/lifecycle/products/microsoft-net-framework).
67+
68+
For full details of supported versions, see [our documentation on .NET Framework compatibility requirements](https://docs.datadoghq.com/tracing/setup_overview/compatibility_requirements/dotnet-framework) and [.NET/.NET Core compatibility requirements](https://docs.datadoghq.com/tracing/setup_overview/compatibility_requirements/dotnet-core).
69+
70+
### Singleton `Tracer` instances
71+
72+
In .NET Tracer 1.x, you could create new `Tracer` instances with different settings for each instance, using the `Tracer` constructor. In .NET Tracer 2.0 this constructor is marked `[Obsolete]` and it is no longer possible to create `Tracer` instances with different settings. This was done to avoid multiple problematic patterns that were hard for users to detect.
73+
74+
To update your code:
75+
76+
```csharp
77+
using Datadog.Trace;
78+
79+
// Create your settings as before
80+
var settings = new TracerSettings();
81+
82+
// var tracer = new Tracer(settings) // <- Delete this line
83+
Tracer.Configure(settings); // <- Add this line
84+
```
85+
86+
### Immutable `Tracer.Settings`
87+
88+
In .NET Tracer 1.x the `TracerSettings` object passed into a `Tracer` instance could be modified later. Depending on the changes, the tracer may or may not respect the changes. In .NET Tracer 2.0, an `ImmutableTracerSettings` object is created when the `Tracer` instance is configured. The property `Tracer.Settings` now returns `ImmutableTracerSettings`, not `TracerSettings`. Subsequent changes to the original `TracerSettings` instance will not be observed by `Tracer`.
89+
90+
To update your code:
91+
92+
```csharp
93+
using Datadog.Trace;
94+
95+
var settings = TracerSettings.FromDefaultSources();
96+
settings.TraceEnabled = false; // TracerSettings are mutable
97+
98+
Tracer.Configure(settings);
99+
100+
// All properties on Tracer.Settings are now read-only
101+
// Tracer.Instance.Settings.TraceEnabled = false; // <- DOES NOT COMPILE
102+
```
103+
104+
### Exporter settings
105+
106+
Exporter-related settings were grouped into the `TracerSettings.Exporter` property.
107+
108+
To update your code:
109+
110+
```csharp
111+
using Datadog.Trace;
112+
113+
var settings = TracerSettings.FromDefaultSources();
114+
115+
// settings.AgentUri = "http://localhost:8126"; // <- Delete this line
116+
settings.Exporter.AgentUri = "http://localhost:8126"; // <- Add this line
117+
118+
Tracer.Configure(settings);
119+
```
120+
121+
### Configure ADO.NET integrations individually
122+
123+
In .NET Tracer 1.x, you could configure automatic instrumentation of all ADO.NET integrations using the `AdoNet` integration ID. In .NET Tracer 2.0, you can now configure specific integrations using the following integration IDs:
124+
125+
* `MySql`
126+
* `Npgsql` (PostgreSQL)
127+
* `Oracle`
128+
* `SqlClient` (SQL Server)
129+
* `Sqlite`
130+
131+
See our documentation for a [complete list of supported integration IDs](https://docs.datadoghq.com/tracing/setup_overview/compatibility_requirements/dotnet-core/#integrations). Note that you can still disable _all_ ADO.NET integrations using the `AdoNet` integration ID.
132+
133+
This change also removes the now-obsolete `TracerSettings.AdoNetExcludedTypes` setting and the corresponding environment variable `DD_TRACE_ADONET_EXCLUDED_TYPES`. Replace usages of these with `TracerSettings.Integrations["<INTEGRATION_NAME>"].Enabled` and `DD_TRACE_<INTEGRATION_NAME>_ENABLED`, respectively:
134+
135+
```csharp
136+
using Datadog.Trace;
137+
138+
var settings = TracerSettings.FromDefaultSources();
139+
140+
// settings.AdoNetExcludedTypes.Add("MySql"); // <- Delete this line
141+
settings.Integrations["MySql"].Enabled = false; // <- Add this line
142+
```
143+
144+
### `ElasticsearchNet5` integration ID removed
145+
146+
In .NET Tracer 1.x, the integration ID for version 5.x of `Elasticsearch.Net` was `ElasticsearchNet5`, and the integration ID for versions 6 and above was `ElasticsearchNet`. In .NET Tracer 2.0, `ElasticsearchNet5` was removed. Use `ElasticsearchNet` for all versions of `Elasticsearch.Net`.
147+
148+
To update your code:
149+
150+
```csharp
151+
using Datadog.Trace;
152+
153+
var settings = TracerSettings.FromDefaultSources();
154+
155+
settings.Integrations["ElasticsearchNet5"].Enabled = false; // <- Delete this line
156+
settings.Integrations["ElasticsearchNet"].Enabled = false; // <- Add this line
157+
```
158+
159+
### Obsolete APIs have been removed
160+
161+
The following deprecated APIs were removed.
162+
163+
* `TracerSettings.DebugEnabled` was removed. Set the `DD_TRACE_DEBUG` environment variable to `1` to enable debug mode.
164+
* `Tags.ForceDrop` and `Tags.ForceKeep` were removed. Use `Tags.ManualDrop` and `Tags.ManualKeep` respectively instead.
165+
* `SpanTypes` associated with automatic instrumentation spans, such as `MongoDb` and `Redis`, were removed.
166+
* `Tags` associated with automatic instrumentation spans, such as `AmqpCommand` and `CosmosDbContainer`, were removed.
167+
* `Tracer.Create()` was removed. Use `Tracer.Configure()` instead.
168+
* `TracerSettings.AdoNetExcludedTypes` was removed. Use `TracerSettings.Integrations` to configure ADO.NET automatic instrumentation.
169+
* Various internal APIs not intended for public consumption were removed.
170+
171+
In addition, some settings were marked obsolete in 2.0:
172+
173+
* Environment variables `DD_TRACE_ANALYTICS_ENABLED`, `DD_TRACE_{0}_ANALYTICS_ENABLED`, and `DD_TRACE_{0}_ANALYTICS_SAMPLE_RATE` for controlling App Analytics are obsolete. App Analytics has been replaced with Tracing Without Limits. See [our documentation for details](https://docs.datadoghq.com/tracing/legacy_app_analytics/).
174+
* `TracerSettings.AnalyticsEnabled`, `IntegrationSettings.AnalyticsEnabled`, and `IntegrationSettings.AnalyticsSampleRate` were marked obsolete.
175+
* Environment variable `DD_TRACE_LOG_PATH` is deprecated. Use `DD_TRACE_LOG_DIRECTORY` instead.
176+
177+
### Introduction of interfaces `ISpan`, `IScope`, and `ITracer`
178+
179+
.NET Tracer 2.0 makes the public `Scope` and `Span` classes internal. Instead, we now expose public `IScope` and `ISpan` interfaces and the tracer API was updated accordingly. If you are currently using explicit types (instead of inferring types with `var`), replace usages of `Scope` with `IScope` and `Span` with `ISpan`.
180+
181+
This Tracer release also adds the new `ITracer` interface, implemented by the `Tracer` class. The type of static property `Tracer.Instance` is still `Tracer`, so use of `ITracer` is not required, but the new interface can be useful for testing with mocks and dependency injection.
182+
183+
To update your `Scope/Span` code:
184+
185+
```csharp
186+
using Datadog.Trace;
187+
188+
// No changes required here (using var)
189+
using (var scope = Tracer.Instance.StartActive("my-operation"))
190+
{
191+
var span = scope.Span;
192+
// ...
193+
}
194+
195+
// No longer compiles (Scope and Span are no longer public)
196+
using (Scope scope = Tracer.Instance.StartActive("my-operation"))
197+
{
198+
Span span = scope.Span;
199+
// ...
200+
}
201+
202+
// Correct usage with explicit types (using IScope and ISpan)
203+
using (IScope scope = Tracer.Instance.StartActive("my-operation"))
204+
{
205+
ISpan span = scope.Span;
206+
// ...
207+
}
208+
```
209+
210+
### Simplification of the tracer interface
211+
212+
In addition to returning `IScope`, several parameters parameters in the `Tracer.StartActive` method signature were replaced with a single `SpanCreationSettings`. The span's service name can no longer be set from `Tracer.StartActive`. Instead, set `Span.ServiceName` after creating the span.
213+
214+
To update your `Scope/Span` code:
215+
216+
```csharp
217+
using Datadog.Trace;
218+
219+
// No changes required here (using only operation name)
220+
using (var scope = Tracer.Instance.StartActive("my-operation"))
221+
{
222+
// ...
223+
}
224+
225+
// No longer compiles (most parameters removed)
226+
using (var scope = Tracer.Instance.StartActive("my-operation", parent: spanContext, serviceName: "my-service", ...))
227+
{
228+
// ...
229+
}
230+
231+
// Correct usage
232+
var spanCreationSettings = new SpanCreationSettings() { Parent = spanContext };
233+
using (var scope = Tracer.Instance.StartActive("my-operation", spanCreationSettings))
234+
{
235+
scope.Span.ServiceName = "my-service";
236+
// ...
237+
}
238+
239+
```
240+
241+
### Incorrect integration names are ignored
242+
243+
In .NET Tracer 2.0, any changes made to an `IntegrationSettings` object for an unknown `IntegrationId` will not be persisted. Instead, a warning will be logged describing the invalid access.
244+
245+
```csharp
246+
using Datadog.Trace;
247+
248+
var tracerSettings = TracerSettings.FromDefaultSources();
249+
250+
// Accessing settings for an unknown integration will log a warning
251+
var settings = tracerSettings.Integrations["MyRandomIntegration"];
252+
253+
// changes are not persisted
254+
settings.Enabled = false;
255+
256+
// isEnabled is null, not false
257+
bool? isEnabled = tracerSettings.Integrations["MyRandomIntegration"].Enabled;
258+
```
259+
260+
### Automatic instrumentation changes
261+
262+
#### `DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED` enabled by default
263+
264+
.NET Tracer 1.26.0 added the `DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED` feature flag, which enables improved span names for ASP.NET and ASP.NET Core automatic instrumentation spans, an additional span for ASP.NET Core requests, and additional tags.
265+
266+
In .NET Tracer 2.0, `DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED` is **enabled** by default. Due to the change in span names, you may need to update your monitors and dashboards to use the new resource names.
267+
268+
If you do not wish to take advantage of the improved route names, you can disable the feature by setting the `DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED` environment variable to `0`.
269+
270+
#### Call-site instrumentation removed
271+
272+
Call-site automatic instrumentation was removed in .NET Tracer 2.0 and replaced with call-target instrumentation. This was the default mode [since version 1.28.0](https://github.com/DataDog/dd-trace-dotnet/releases/tag/v1.28.0) on .NET Framework 4.6 or above and .NET Core / .NET 5. Call-target instrumentation provides performance and reliability improvements over call-site instrumentation.
273+
274+
Note: Call-target instrumentation does not support instrumenting custom implementations of `DbCommand` yet. If you find ADO.NET spans are missing from your traces after upgrading, please raise an issue on GitHub, or contact [support](https://docs.datadoghq.com/help).
275+
276+
#### `DD_INTEGRATIONS` environment variable no longer needed
277+
278+
The `integrations.json` file is no longer required for instrumentation. You can remove references to this file, for example by deleting the `DD_INTEGRATIONS` environment variable.
279+
280+
## Get in touch
281+
282+
If you have questions, feedback, or feature requests, reach our [support](https://docs.datadoghq.com/help).

0 commit comments

Comments
 (0)