Dynatrace.OpenTelemetry.Exporter.Metrics
1.0.0
Prefix Reserved
Dynatrace supports native OpenTelemetry protocol (OTLP) ingest for traces, metrics and logs.
Therefore, the proprietary Dynatrace OpenTelemetry metrics exporter is deprecated in favor of exporting via OTLP/HTTP.
Please refer to the [migration guide](https://www.dynatrace.com/support/help/shortlink/migrating-dynatrace-metrics-exporter-otlp-exporter#migrate-applications) for instructions on how to migrate to the OTLP HTTP exporter, as well as reasoning and benefits for this transition.
For an example on how to configure the OTLP exporter in a .NET application, check out the [.NET integration walk-through](https://www.dynatrace.com/support/help/shortlink/otel-wt-dotnet#tabgroup--dynatrace-docs--otlp-export) page in the Dynatrace documentation.
See the version list below for details.
dotnet add package Dynatrace.OpenTelemetry.Exporter.Metrics --version 1.0.0
NuGet\Install-Package Dynatrace.OpenTelemetry.Exporter.Metrics -Version 1.0.0
<PackageReference Include="Dynatrace.OpenTelemetry.Exporter.Metrics" Version="1.0.0" />
paket add Dynatrace.OpenTelemetry.Exporter.Metrics --version 1.0.0
#r "nuget: Dynatrace.OpenTelemetry.Exporter.Metrics, 1.0.0"
// Install Dynatrace.OpenTelemetry.Exporter.Metrics as a Cake Addin #addin nuget:?package=Dynatrace.OpenTelemetry.Exporter.Metrics&version=1.0.0 // Install Dynatrace.OpenTelemetry.Exporter.Metrics as a Cake Tool #tool nuget:?package=Dynatrace.OpenTelemetry.Exporter.Metrics&version=1.0.0
Dynatrace OpenTelemetry Metrics Exporter for .NET
This exporter allows exporting metrics created using the OpenTelemetry SDK for .NET directly to Dynatrace.
More information on exporting OpenTelemetry metrics to Dynatrace can be found in the Dynatrace documentation.
This exporter is built against the OpenTelemetry .NET SDK v1.2.0 which is the first stable release for the metrics SDK and should be compatible with this and later versions.
Getting started
The general setup of OpenTelemetry .NET is explained in the official Getting Started Guide.
To add the exporter to your project, install the Dynatrace.OpenTelemetry.Exporter.Metrics package to your project. This can be done through the NuGet package manager in Visual Studio or by running the following command in your project folder:
dotnet add package Dynatrace.OpenTelemetry.Exporter.Metrics
This exporter package targets .NET Standard 2.0 and can therefore be included on .NET Core 2.0 and above, as well as .NET Framework 4.6.1 and above.
Setup
To set up a Dynatrace metrics exporter, add the following code to your project:
// A Meter instance is obtained via the System.Diagnostics.DiagnosticSource package
var meter = new Meter("my_meter", "0.0.1");
// Configure the MeterProvider with the DynatraceMetricsExporter
// using the extension method .AddDynatraceExporter().
// Without passing any configuration, the exporter will attempt
// to export to the local OneAgent endpoint.
var provider = Sdk.CreateMeterProviderBuilder()
.AddMeter(meter.Name)
.AddDynatraceExporter()
.Build();
// Use the meter to create a counter instrument.
var myCounter = meter.CreateCounter<long>("my_counter");
var attributes = new TagList
{
{ "my_label", "value1" }
};
// Record a metric. The export interval can be configured during the AddDynatraceExporter() call above.
// By default, metrics are exported in 1 minute intervals (60000ms).
myCounter.Add(100, attributes);
If no local OneAgent is available or metrics should be exported directly to the backend, the DynatraceMetricsExporter
can be set up with an endpoint and an API token.
The 'Ingest metrics' (metrics.ingest
) permission is required for the token,
and it is recommended to restrict the token access to that scope.
More information about the token setup can be found here.
// Not required, but potentially helpful.
// The exporter logs information about preparing and exporting metrics.
var loggerFactory = LoggerFactory.Create(builder =>
{
builder.SetMinimumLevel(LogLevel.Debug).AddConsole();
});
var meter = new Meter("my_meter", "0.0.1");
// Configure the MeterProvider with the DynatraceMetricsExporter
// using the extension method .AddDynatraceExporter().
// You can customize the exporter by providing an Action<DynatraceExporterOptions>.
using var provider = Sdk.CreateMeterProviderBuilder()
.AddMeter(meter.Name)
.AddDynatraceExporter(cfg =>
{
cfg.Url = "https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest";
cfg.ApiToken = "YOUR_API_TOKEN";
}, loggerFactory)
.Build();
// Use the meter to create a counter instrument.
var myCounter = meter.CreateCounter<long>("my_counter");
var attributes = new TagList
{
{ "my_label", "value1" }
};
// Record a metric which will be exported to the provided Url.
myCounter.Add(100, attributes);
The example below shows all the other optional properties that can be
configured in the DynatraceExporterOptions
.
Read the Configuration section to learn more about each of them.
using var provider = Sdk.CreateMeterProviderBuilder()
.AddMeter(meter.Name)
.AddDynatraceExporter(cfg =>
{
cfg.Prefix = "metric.key.prefix";
cfg.DefaultDimensions = new List<KeyValuePair<string, string>>()
{
new KeyValuePair<string, string>("defaultDim1", "value1"),
new KeyValuePair<string, string>("defaultDim2", "value2")
};
cfg.EnrichWithDynatraceMetadata = true;
cfg.MetricExportIntervalMilliseconds = 10000;
}, loggerFactory)
.Build();
Example application
We provide an example command line application which exports metrics to Dynatrace.
To run it, change into the folder and use dotnet run
:
cd src/Examples.Console
dotnet run
Without any further configuration, the example app will try to export to a local OneAgent endpoint, which requires no authentication. More information about the local OneAgent endpoint can be found below.
The example app provides a number of command line options, which can be retrieved by running dotnet run --project src/Examples.Console/Examples.Console.csproj -- --help
.
Note the --
separating the dotnet command and the parameters passed to the application.
Everything after the dashes is passed to the application.
If no local OneAgent is available, the app can be configured with an endpoint and a metrics ingest token like this:
cd src/Examples.Console
dotnet run -- -u "https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest" -t "YOUR_API_TOKEN"
Configuration
The DynatraceExporterOptions
class contains all the available configuration.
The DynatraceExporterOptions
can be provided either via the AddDynatraceExporter()
extension method
on the MeterProviderBuilder
, or by manually passing it to the DynatraceMetricsExporter
constructor.
The DynatraceExporterOptions
class contains the following properties:
Dynatrace API Endpoint (Url
)
A OneAgent installed on the host can provide a local endpoint for ingesting metrics without the need for an API token. The OneAgent metric API documentation provides information on how to enable the local OneAgent endpoint, if necessary. Using the local API endpoint, the host ID and host name context are automatically added to each metric as dimensions.
If no OneAgent is running on the host or if metrics should be sent to a different endpoint, the Url
property allows for setting that endpoint.
The metrics ingest endpoint URL follows the format:
https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest
on SaaS deployments.https://{your-domain}/e/{your-environment-id}/api/v2/metrics/ingest
on managed deployments.
Dynatrace API Token (ApiToken
)
If metrics are not sent to the local OneAgent endpoint but directly to a Dynatrace server, an API token has to be provided for authentication.
The Dynatrace API token to be used by the exporter can be specified using the ApiToken
property.
The token could, for example, be read from an environment variable or command line arguments.
It should not be hardcoded, especially if the code is stored in a VCS.
Creating an API token for your Dynatrace environment is described in the Dynatrace API documentation.
The permission required for sending metrics is Ingest metrics
(metrics.ingest
) and it is recommended to limit scope to only this permission.
Metric Key Prefix (Prefix
)
The Prefix
property allows specifying an optional prefix, which is prepended to each metric key, separated by a dot (e.g. a prefix of <prefix>
and a metric name of <name>
will lead to a combined metric name of <prefix>.<name>
).
In the example, a prefix of otel.dotnet
is used, which leads to metrics named otel.dotnet.metric_name
, and allows for clear distinction between metrics from different sources in the Dynatrace metrics UI.
Default Dimensions (DefaultDimensions
)
The DefaultDimensions
property can be used to optionally specify a List<KeyValuePair<string, string>>
, which will be added as dimensions to all data points.
Dimension keys will be normalized, de-duplicated, and only one dimension value per key will be sent to the server.
Dimensions set on instruments will overwrite default dimensions if they share the same name after normalization.
OneAgent metadata will overwrite all dimensions described above, but it only uses Dynatrace-reserved keys starting with dt.*
.
The reserved dimension dt.metrics.source=opentelemetry
will automatically be added to every exported metric when using the exporter.
Enrich metrics with Dynatrace Metadata (EnrichWithDynatraceMetadata
)
If the EnrichWithDynatraceMetadata
property is set to true, the exporter will retrieve host and process metadata from the OneAgent, if available, and set it as dimensions to all exported metrics.
The EnrichWithDynatraceMetadata
property on the options object can be used to disable Dynatrace metadata export.
If running on a host with a OneAgent, setting this option will instruct the exporter to read and export metadata collected by the OneAgent to the Dynatrace endpoint.
This option is set to true
by default.
If the OneAgent is running locally, but this option is set to false, no Dynatrace metadata will be exported.
More information on the underlying OneAgent feature that is used by the exporter can be found in the
Dynatrace documentation.
Export interval (MetricExportIntervalMilliseconds
)
The interval to collect metrics. This value is passed and used by the Periodic Metric Reader.
This option is set to 1 minute (60000ms) by default.
Known issues and limitations
Typed attributes support
The OpenTelemetry specification has a concept of Attributes. These attributes consist of key-value pairs, where the keys are strings and the values are either primitive types or arrays of uniform primitive types.
The OpenTelemetry .NET SDK implementation of this works with a KeyValuePair<string, object>
, meaning the value
can be of any type.
At the moment, this exporter only supports attributes with a string value type. This means that if attributes of any other type are used, they will be ignored and only the string-valued attributes are going to be sent to Dynatrace.
Histograms
OpenTelemetry Histograms are exported to Dynatrace as statistical summaries consisting of a minimum and maximum value,
the total sum of all values, and the count of the values summarized. min
and max
values are not directly
available on the metric data point as of 1.2.0 of the .NET SDK.
This exporter performs estimations based on the boundaries of the first and last buckets that contain values.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Dynatrace.MetricUtils (>= 0.3.0)
- OpenTelemetry (>= 1.2.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated | |
---|---|---|---|
1.0.1 | 609,051 | 1/17/2023 | |
1.0.0 | 416,387 | 6/14/2022 | |
0.4.0-beta | 10,470 | 1/18/2022 | |
0.3.2-beta | 171 | 1/12/2022 | |
0.3.0-beta | 8,302 | 11/22/2021 | |
0.1.0-beta | 466 | 11/20/2020 |