IKuznetsov в 09:35, 15 октября 2025

2025-10-15T09:35:06Z

← Предыдущая		Версия 09:35, 15 октября 2025
Строка 121:		Строка 121:
	private static string DT_API_TOKEN = ""; // TODO: Provide the OpenTelemetry-scoped access token here		private static string DT_API_TOKEN = ""; // TODO: Provide the OpenTelemetry-scoped access token here

	private const string activitySource = "~~Dynatrace~~.DotNetApp.Sample"; // TODO: Provide a descriptive name for your application here		private const string activitySource = "astromkey.DotNetApp.Sample"; // TODO: Provide a descriptive name for your application here

	public static readonly ActivitySource MyActivitySource = new ActivitySource(activitySource);		public static readonly ActivitySource MyActivitySource = new ActivitySource(activitySource);
Строка 137:		Строка 137:
	foreach (string name in new string[] {"dt_metadata_e617c525669e072eebe3d0f08212e8f2.properties",		foreach (string name in new string[] {"dt_metadata_e617c525669e072eebe3d0f08212e8f2.properties",

	"/var/lib/~~dynatrace~~/enrichment/dt_metadata.properties",		"/var/lib/astromkey/enrichment/dt_metadata.properties",

	"/var/lib/~~dynatrace~~/enrichment/dt_host_metadata.properties"}) {		"/var/lib/astromkey/enrichment/dt_host_metadata.properties"}) {

	try {		try {
Строка 312:		Строка 312:
	private static string DT_API_TOKEN = ""; // TODO: Provide the OpenTelemetry-scoped access token here		private static string DT_API_TOKEN = ""; // TODO: Provide the OpenTelemetry-scoped access token here

	private const string activitySource = "~~Dynatrace~~.DotNetApp.Sample"; // TODO: Provide a descriptive name for your application here		private const string activitySource = "astromkey.DotNetApp.Sample"; // TODO: Provide a descriptive name for your application here

	public static readonly ActivitySource MyActivitySource = new ActivitySource(activitySource);		public static readonly ActivitySource MyActivitySource = new ActivitySource(activitySource);
Строка 336:		Строка 336:
	foreach (string name in new string[] {"dt_metadata_e617c525669e072eebe3d0f08212e8f2.properties",		foreach (string name in new string[] {"dt_metadata_e617c525669e072eebe3d0f08212e8f2.properties",

	"/var/lib/~~dynatrace~~/enrichment/dt_metadata.properties",		"/var/lib/astromkey/enrichment/dt_metadata.properties",

	"/var/lib/~~dynatrace~~/enrichment/dt_host_metadata.properties"}) {		"/var/lib/astromkey/enrichment/dt_host_metadata.properties"}) {

	try {		try {

IKuznetsov: Новая страница: «В этом пошаговом руководстве показано, как добавить возможность наблюдения в ваше '''.NET-п...»

2025-10-15T09:34:25Z

Новая страница: «В этом пошаговом руководстве показано, как добавить возможность наблюдения в ваше '''.NET-п...»

Новая страница

В этом пошаговом руководстве показано, как добавить возможность наблюдения в ваше '''.NET-приложение''' с помощью библиотек и инструментов '''.NET''' '''OpenTelemetry'''.
{| class="wikitable"
!Особенность
!Поддержка
|-
|Автоматические инструменты
|Да
|-
|Трассировки
|Да
|-
|Метрики
|Да
|-
|Логи
|Да
|}

== Предустановка ==

* Ключ-АСТРОМ версии '''1.254+'''
* Для трассировки включен '''контекст трассировки''' '''W3C'''.
*# Перейдите в '''Настройки > Предпочтения > Функции ЕдиногоАгента'''.
*# Включите опцию '''Отправлять HTTP-заголовки контекста трассировки W3C'''.

== Получение данных для доступа к Ключ-АСТРОМ ==

=== Определение базовых URL API ===
Подробную информацию о сборке базового '''URL-адреса''' конечной точки '''OTLP''' см. в разделе [[Экспорт с помощью OTLP]]. '''URL-адрес''' должен заканчиваться на <code>/api/v2/otlp</code>.

=== Получение токена доступа API ===
Токен доступа для сбора трассировок, логов и метрик можно создать в разделе [[Токен доступа|Токены доступа]].

Экспорт с помощью '''OTLP''' содержит более подробную информацию о формате и необходимых областях доступа.

== Выберите, как вы хотите инструментировать свое приложение ==
Для '''.NET OpenTelemetry''' поддерживает автоматическое и ручное инструментирование (или их комбинацию).
{| class="wikitable"
|Какой инструментарий выбрать?

Рекомендуется начать с автоматического измерения и добавить ручное измерение, если автоматический подход не работает или не дает достаточно информации.
|}

== Автоматическое инструментирование приложения (необязательно) ==
Автоматизированное инструментирование '''.NET''' можно настроить как во время разработки, так и позже, после развертывания.
{| class="wikitable"
|Расширение с помощью ЕдиногоАгента

В настоящее время невозможно автоматически дополнять сервисы информацией, относящейся к хосту. Для этого потребуется перейти на ручное инструментирование.
|}

=== В процессе разработки ===
1. Установите <code>[https://www.nuget.org/packages/OpenTelemetry.Extensions.Hosting OpenTelemetry.Extensions.Hosting]</code>.
{| class="wikitable"
|dotnet add package OpenTelemetry.Extensions.Hosting
|}
2. Установите соответствующую библиотеку инструментов для вашей платформы '''.NET''' (полный список доступен [https://www.nuget.org/packages?q=OpenTelemetry.Instrumentation здесь]).
{| class="wikitable"
|dotnet add package OpenTelemetry.Instrumentation.[FRAMEWORK_NAME]
|}

=== После развертывания ===

# Загрузите [https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest последнюю версию автоматического установщика] для целевой операционной системы.
# [https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation#shell-scripts Запустите (в Unix)] или [https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation#powershell-module-windows импортируйте (в Windows)] автоматический установщик, чтобы установить и настроить все необходимые библиотеки автоматического инструментирования.
# Запустите ваше приложение.

Помимо описанной выше настройки инструментария, необходимо также настроить соответствующие параметры экспорта с помощью переменных среды. Это включает '''URL''' конечной точки, токен аутентификации и временные настройки для метрик.
{| class="wikitable"
|OTEL_EXPORTER_OTLP_ENDPOINT=[URL]

OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token [TOKEN]"

OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
|}

== Инструментирование приложения вручную (необязательно) ==

=== Настройка ===
Шаги настройки немного различаются в зависимости от того, инструментируете ли вы обычное приложение '''.NET''' или приложение '''ASP.NET'''.

==== .NET ====
1. Установите следующие пакеты.
{| class="wikitable"
|dotnet add package Microsoft.Extensions.Logging

dotnet add package OpenTelemetry.Extensions.Hosting

dotnet add package OpenTelemetry

dotnet add package OpenTelemetry.Api

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
|}
2. Добавьте следующие операторы <code>using</code> в класс запуска, который инициирует загрузку вашего приложения.
{| class="wikitable"
|using OpenTelemetry;

using OpenTelemetry.Trace;

using OpenTelemetry.Exporter;

using OpenTelemetry.Metrics;

using OpenTelemetry.Logs;

using OpenTelemetry.Resources;

using OpenTelemetry.Context.Propagation;

using System.Diagnostics;

using System.Diagnostics.Metrics;

using Microsoft.Extensions.Logging;
|}
3. Добавьте эти поля в класс запуска, причем первые два должны содержать данные о доступе, если вы используете экспорт '''OTLP'''.
{| class="wikitable"
|private static string DT_API_URL = ""; // TODO: Provide your SaaS/Managed URL here

private static string DT_API_TOKEN = ""; // TODO: Provide the OpenTelemetry-scoped access token here

private const string activitySource = "Dynatrace.DotNetApp.Sample"; // TODO: Provide a descriptive name for your application here

public static readonly ActivitySource MyActivitySource = new ActivitySource(activitySource);

private static ILoggerFactory loggerFactoryOT;
|}
4. Добавьте метод <code>initOpenTelemetry</code> в класс запуска и вызовите его как можно раньше при запуске приложения. Это инициализирует '''OpenTelemetry''' для бэкенда Ключ-АСТРОМ и создаст поставщиков трассировки и метрик по умолчанию.
{| class="wikitable"
|private static void initOpenTelemetry(IServiceCollection services)

{

List<KeyValuePair<string, object>> dt_metadata = new List<KeyValuePair<string, object>>();

foreach (string name in new string[] {"dt_metadata_e617c525669e072eebe3d0f08212e8f2.properties",

"/var/lib/dynatrace/enrichment/dt_metadata.properties",

"/var/lib/dynatrace/enrichment/dt_host_metadata.properties"}) {

try {

foreach (string line in System.IO.File.ReadAllLines(name.StartsWith("/var") ? name : System.IO.File.ReadAllText(name))) {

var keyvalue = line.Split("=");

dt_metadata.Add( new KeyValuePair<string, object>(keyvalue[0], keyvalue[1]));

}

}

catch { }

}

Action<ResourceBuilder> configureResource = r => r

.AddService(serviceName: "dotnet-quickstart") //TODO Replace with the name of your application

.AddAttributes(dt_metadata);

services.AddOpenTelemetry()

.ConfigureResource(configureResource)

.WithTracing(builder => {

builder

.SetSampler(new AlwaysOnSampler())

.AddSource(MyActivitySource.Name)

.AddOtlpExporter(options =>

{

options.Endpoint = new Uri(Environment.GetEnvironmentVariable("DT_API_URL")+ "/v1/traces");

options.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf;

options.Headers = $"Authorization=Api-Token {Environment.GetEnvironmentVariable("DT_API_TOKEN")}";

});

})

.WithMetrics(builder => {

builder

.AddMeter("my-meter")

.AddOtlpExporter((OtlpExporterOptions exporterOptions, MetricReaderOptions readerOptions) =>

{

exporterOptions.Endpoint = new Uri(Environment.GetEnvironmentVariable("DT_API_URL")+ "/v1/metrics");

exporterOptions.Headers = $"Authorization=Api-Token {Environment.GetEnvironmentVariable("DT_API_TOKEN")}";

exporterOptions.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf;

readerOptions.TemporalityPreference = MetricReaderTemporalityPreference.Delta;

});

});

var resourceBuilder = ResourceBuilder.CreateDefault();

configureResource!(resourceBuilder);

loggerFactoryOT = LoggerFactory.Create(builder => {

builder

.AddOpenTelemetry(options => {

options.SetResourceBuilder(resourceBuilder).AddOtlpExporter(options => {

options.Endpoint = new Uri(Environment.GetEnvironmentVariable("DT_API_URL")+ "/v1/logs");

options.Headers = $"Authorization=Api-Token {Environment.GetEnvironmentVariable("DT_API_TOKEN")}";

options.ExportProcessorType = OpenTelemetry.ExportProcessorType.Batch;

options.Protocol = OtlpExportProtocol.HttpProtobuf;

});

})

.AddConsole();

});

Sdk.CreateTracerProviderBuilder()

.SetSampler(new AlwaysOnSampler())

.AddSource(MyActivitySource.Name)

.ConfigureResource(configureResource);

// add-logging

}
|}
Расширение данных Ключ-АСТРОМ

Операции чтения файлов, анализирующие файлы <code>dt_metadata</code> в примере кода, пытаются прочитать файлы данных ЕдиногоАгента, чтобы расширить запрос '''OTLP''' и гарантировать, что вся соответствующая информация о топологии доступна в Ключ-АСТРОМ.

==== ASP.NET ====
1. Установите следующие пакеты.
{| class="wikitable"
|dotnet add package Microsoft.Extensions.Logging

dotnet add package OpenTelemetry.Extensions.Hosting

dotnet add package OpenTelemetry

dotnet add package OpenTelemetry.Api

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

dotnet add package OpenTelemetry.Instrumentation.AspNetCore

dotnet add package OpenTelemetry.Instrumentation.Http

dotnet add package OpenTelemetry.Instrumentation.Runtime
|}
2. Добавьте следующие операторы <code>using</code> в класс запуска, который инициирует загрузку вашего приложения.
{| class="wikitable"
|using OpenTelemetry;

using OpenTelemetry.Trace;

using OpenTelemetry.Exporter;

using OpenTelemetry.Metrics;

using OpenTelemetry.Logs;

using OpenTelemetry.Resources;

using OpenTelemetry.Context.Propagation;

using System.Diagnostics;

using System.Diagnostics.Metrics;

using Microsoft.Extensions.Logging;

using OpenTelemetry.Instrumentation.AspNetCore;
|}
3. Добавьте эти поля в класс запуска, причем первые два должны содержать данные о доступе, если вы используете экспорт '''OTLP'''.
{| class="wikitable"
|private static string DT_API_URL = ""; // TODO: Provide your SaaS/Managed URL here

private static string DT_API_TOKEN = ""; // TODO: Provide the OpenTelemetry-scoped access token here

private const string activitySource = "Dynatrace.DotNetApp.Sample"; // TODO: Provide a descriptive name for your application here

public static readonly ActivitySource MyActivitySource = new ActivitySource(activitySource);

private static ILoggerFactory loggerFactoryOT;
|}
4. Добавьте метод <code>initOpenTelemetry</code> в класс запуска и вызовите его как можно раньше при запуске приложения. Это инициализирует '''OpenTelemetry''' для бэкенда Ключ-АСТРОМ и создаст поставщиков трассировки и метрик по умолчанию.
{| class="wikitable"
|private static void initOpenTelemetry(){

var port = System.Environment.GetEnvironmentVariable("PORT") ?? "8080";

var appBuilder = WebApplication.CreateBuilder();

appBuilder.WebHost.ConfigureKestrel(options =>{

options.ListenAnyIP(Convert.ToInt32(port)); // hardcoding the port

});

List<KeyValuePair<string, object>> dt_metadata = new List<KeyValuePair<string, object>>();

foreach (string name in new string[] {"dt_metadata_e617c525669e072eebe3d0f08212e8f2.properties",

"/var/lib/dynatrace/enrichment/dt_metadata.properties",

"/var/lib/dynatrace/enrichment/dt_host_metadata.properties"}) {

try {

foreach (string line in System.IO.File.ReadAllLines(name.StartsWith("/var") ? name : System.IO.File.ReadAllText(name))) {

var keyvalue = line.Split("=");

dt_metadata.Add( new KeyValuePair<string, object>(keyvalue[0], keyvalue[1]));

}

}

catch { }

}

Action<ResourceBuilder> configureResource = r => r

.AddService(serviceName: "dotnetManual") //TODO Replace with the name of your application

.AddAttributes(dt_metadata);

appBuilder.Services.AddOpenTelemetry()

.ConfigureResource(configureResource)

.WithTracing(builder =>{

appBuilder.Services.Configure<AspNetCoreTraceInstrumentationOptions>(appBuilder.Configuration.GetSection("AspNetCoreInstrumentation"));

builder

.AddSource(MyActivitySource.Name)

.SetSampler(new AlwaysOnSampler())

.AddHttpClientInstrumentation()

.AddAspNetCoreInstrumentation()

.AddOtlpExporter(otlpOptions =>{

otlpOptions.Endpoint = new Uri(Environment.GetEnvironmentVariable("DT_API_URL")+ "/v1/traces");

otlpOptions.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf;

otlpOptions.Headers = $"Authorization=Api-Token {Environment.GetEnvironmentVariable("DT_API_TOKEN")}";

});

})

.WithMetrics(builder =>{

builder

.AddMeter("my-meter")

// .AddMeter(Instrumentation.MeterName)

.AddRuntimeInstrumentation()

.AddHttpClientInstrumentation()

.AddAspNetCoreInstrumentation()

.AddOtlpExporter((OtlpExporterOptions exporterOptions, MetricReaderOptions readerOptions) => {

exporterOptions.Endpoint = new Uri(Environment.GetEnvironmentVariable("DT_API_URL")+ "/v1/metrics");

exporterOptions.Headers = $"Authorization=Api-Token {Environment.GetEnvironmentVariable("DT_API_TOKEN")}";

exporterOptions.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf;

readerOptions.TemporalityPreference = MetricReaderTemporalityPreference.Delta;

});

appBuilder.Logging.ClearProviders();

appBuilder.Logging.AddOpenTelemetry(options =>

{

var resourceBuilder = ResourceBuilder.CreateDefault();

configureResource(resourceBuilder);

options.SetResourceBuilder(resourceBuilder);

options.AddOtlpExporter(otlpOptions => {

otlpOptions.Endpoint = new Uri(Environment.GetEnvironmentVariable("DT_API_URL")+ "/v1/logs");

otlpOptions.Headers = $"Authorization=Api-Token {Environment.GetEnvironmentVariable("DT_API_TOKEN")}";

otlpOptions.ExportProcessorType = OpenTelemetry.ExportProcessorType.Batch;

otlpOptions.Protocol = OtlpExportProtocol.HttpProtobuf;

});

});

appBuilder.Services.AddControllers();

appBuilder.Services.AddEndpointsApiExplorer();

var app = appBuilder.Build();

app.MapControllers();

app.Run();

});

}
|}
Расширение данных Ключ-АСТРОМ

Операции чтения файлов, анализирующие файлы <code>dt_metadata</code> в примере кода, пытаются прочитать файлы данных ЕдиногоАгента, чтобы расширить запрос '''OTLP''' и гарантировать, что вся соответствующая информация о топологии доступна в Ключ-АСТРОМ.

=== Добавление трассировки ===
Используя шаг настройки <code>MyActivitySource</code>, теперь мы можем начать новые действия (трассировки):
{| class="wikitable"
|using var activity = Startup.MyActivitySource.StartActivity("Call to /myendpoint", ActivityKind.Consumer, parentContext.ActivityContext);

activity?.SetTag("http.method", "GET");

activity?.SetTag("net.protocol.version", "1.1");
|}
В приведенном выше коде мы:

* Создали новое действие (span) и назвали его «'''Call to /myendpoint'''».
* Добавили два тега (атрибута), следуя [https://opentelemetry.io/docs/specs/semconv/general/trace/ семантическому соглашению об именовании], специфичному для действия этого диапазона: информация о методе '''HTTP''' и версии

Активность будет автоматически установлена как текущая и активная область до тех пор, пока поток выполнения не выйдет за пределы области действия текущего метода. Последующие активности автоматически станут дочерними областями.

=== Сбор метрик ===
1. Для создания новых метрических инструментов нам сначала нужен объект метрики.
{| class="wikitable"
|private static readonly Meter meter = new Meter("my-meter", "1.0.0"); //TODO Replace with the name of your meter
|}
2. С помощью <code>meter</code> мы теперь можем создавать отдельные инструменты, например, метрики.
{| class="wikitable"
|private static readonly Counter<long> counter = meter.CreateCounter<long>("request_counter");
|}
3. Теперь мы можем вызвать метод <code>Add()</code> для записи новых значений <code>counter</code> с помощью нашей метрики и сохранения дополнительных атрибутов (например, <code>action.type</code>).
{| class="wikitable"
|counter.Add(1, new("ip", "an ip address here"), new("some other key", "some other value"));
|}

=== Подключение логов ===
Используя переменную <code>loggerFactoryOT</code>, которую мы инициализировали в разделе «'''Настройка'''», мы теперь можем создавать отдельные экземпляры регистратора, которые будут передавать регистрируемую информацию напрямую в настроенную конечную точку '''OpenTelemetry''' в Ключ-АСТРОМ.
{| class="wikitable"
|var logger = loggerFactoryOT.CreateLogger<Startup>();

services.AddSingleton<ILoggerFactory>(loggerFactoryOT);

services.AddSingleton(logger);

logger.LogInformation(eventId: 123, "Log line");
|}

=== Обеспечение распространения контекста (необязательно) ===
Распространение контекста особенно важно, когда задействованы сетевые вызовы (например, '''REST''').

Если вы используете автоматическое инструментирование и ваши сетевые библиотеки также им охватываются, то это будет автоматически реализовано библиотеками инструментирования. В противном случае ваш код должен это учитывать.

==== Извлечение контекста при получении запроса ====
В следующем примере мы предполагаем, что получили сетевой вызов через <code>System.Web.HttpRequest</code>, и определяем экземпляр <code>CompositeTextMapPropagator</code> для извлечения контекстной информации из '''HTTP-заголовков'''. Затем мы передаем этот экземпляр в <code>Extract()</code>, возвращая объект контекста, что позволяет нам продолжить предыдущую трассировку с нашими интервалами.
{| class="wikitable"
|private CompositeTextMapPropagator propagator = new CompositeTextMapPropagator(new TextMapPropagator[] {

new TraceContextPropagator(),

new BaggagePropagator(),

});

private static readonly Func<HttpRequest, string, IEnumerable<string>> valueGetter = (request, name) => request.Headers[name];

var parentContext = propagator.Extract(default, HttpContext.Request, valueGetter);

using var activity = MyActivitySource.StartActivity("my-span", ActivityKind.Consumer, parentContext.ActivityContext);
|}

==== Внедрение контекста при отправке запросов ====
В следующем примере мы отправляем '''REST-запрос''' к другой службе и предоставляем наш существующий контекст как часть '''HTTP-заголовков''' нашего запроса.

Для этого мы определяем экземпляр <code>TextMapPropagator</code>, который добавляет соответствующую информацию. После создания экземпляра '''REST-объекта''' мы передаём его вместе с контекстом и экземпляром сеттера в <code>Inject()</code>, который добавит необходимые заголовки к запросу.
{| class="wikitable"
|private CompositeTextMapPropagator propagator = new CompositeTextMapPropagator(new TextMapPropagator[] {

new TraceContextPropagator(),

new BaggagePropagator()

});

private static Action<HttpRequestMessage, string, string> _headerValueSetter => (request, name, value) => {

request.Headers.Remove(name);

request.Headers.Add(name, value);

};

propagator.Inject(new PropagationContext(activity!.Context, Baggage.Current), request, _headerValueSetter);
|}

== Настройка сбора данных в соответствии с требованиями конфиденциальности (необязательно) ==
Хотя Ключ-АСТРОМ автоматически собирает все атрибуты '''OpenTelemetry''', в веб-интерфейсе Ключ-АСТРОМ сохраняются и отображаются только значения атрибутов, указанные в списке разрешенных. Это предотвращает случайное сохранение персональных данных, позволяя вам соблюдать требования к конфиденциальности и контролировать объем хранимых данных мониторинга.

Чтобы просматривать пользовательские атрибуты, необходимо сначала разрешить их использование в веб-интерфейсе Ключ-АСТРОМ.

== Проверка загрузки данных в Ключ-АСТРОМ ==
После завершения инструментирования вашего приложения выполните несколько тестовых действий для создания и отправки демонстрационных трассировок, метрик и логов, а также проверьте, что они были правильно загружены в Ключ-АСТРОМ.

Чтобы сделать это для трассировок, перейдите в раздел '''Трассировки''' и выберите вкладку '''Распределенные трассировки'''. Если вы используете ЕдиныйАгент, выберите '''PurePaths''' .

Для просмотра метрик и логов перейдите в раздел '''Метрики''' или '''Логов''' или '''Логи и события'''.

.NET OpenTelemetry - История изменений

IKuznetsov в 09:35, 15 октября 2025

IKuznetsov: Новая страница: «В этом пошаговом руководстве показано, как добавить возможность наблюдения в ваше '''.NET-п...»