Логування комплексних обʼєктів

Дізнайтеся, як вести логи комплексних обʼєктів за допомогою OpenTelemetry .NET

У посібнику Початок роботи з OpenTelemetry .NET Logs — Консоль ми дізналися, як реєструвати примітивні типи даних. У цьому посібнику ви дізнаєтеся, як реєструвати комплексі обʼєкти.

Логування комплексних обʼєктів у .NET

Логування комплексних обʼєктів було запроваджене в .NET 8.0 через атрибут LogPropertiesAttribute. Цей атрибут та відповідна логіка генерації коду надаються пакунком розширенням Microsoft.Extensions.Telemetry.Abstractions.

Попередні вимоги

Кроки реалізації

1. Встановіть необхідний пакунок

Встановіть пакунок Microsoft.Extensions.Telemetry.Abstractions:

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

2. Визначте комплексний тип даних

Створіть структуру для представлення вашого комплексного обʼєкта:

public struct FoodRecallNotice
{
    public string? BrandName { get; set; }
    public string? ProductDescription { get; set; }
    public string? ProductType { get; set; }
    public string? RecallReasonDescription { get; set; }
    public string? CompanyName { get; set; }
}

3. Створіть метод розширення для логера з атрибутом LogProperties

Визначте метод розширення для вашого логера, який використовує атрибут LogProperties.

using Microsoft.Extensions.Logging;

internal static partial class LoggerExtensions
{
    [LoggerMessage(LogLevel.Critical)]
    public static partial void FoodRecallNotice(
        this ILogger logger,
        [LogProperties(OmitReferenceName = true)] in FoodRecallNotice foodRecallNotice);
}

Атрибут [LogProperties(OmitReferenceName = true)] вказує генератору джерела:

  • Включити всі властивості FoodRecallNotice як окремі атрибути журналу
  • Опустити імʼя посилання (імʼя параметра) з ключів атрибутів

4. Логування комплексного обʼєкта

Створіть екземпляр вашого комплексного обʼєкта та зареєструйте його:

// Створіть комплексний обʼєкт
var foodRecallNotice = new FoodRecallNotice
{
    BrandName = "Contoso",
    ProductDescription = "Salads",
    ProductType = "Food & Beverages",
    RecallReasonDescription = "due to a possible health risk from Listeria monocytogenes",
    CompanyName = "Contoso Fresh Vegetables, Inc.",
};

// Логування комплексного обʼєкта
logger.FoodRecallNotice(foodRecallNotice);

5. Запустіть програму

Запустіть програму, наприклад, за допомогою dotnet run, і ви повинні побачити вивід журналу в консолі:

LogRecord.Timestamp:               2024-01-12T19:01:16.0604084Z
LogRecord.CategoryName:            Program
LogRecord.Severity:                Fatal
LogRecord.SeverityText:            Critical
LogRecord.FormattedMessage:
LogRecord.Body:
LogRecord.Attributes (Key:Value):
    CompanyName: Contoso Fresh Vegetables, Inc.
    RecallReasonDescription: due to a possible health risk from Listeria monocytogenes
    ProductType: Food & Beverages
    ProductDescription: Salads
    BrandName: Contoso
LogRecord.EventId:                 252550133
LogRecord.EventName:               FoodRecallNotice

Зверніть увагу, що кожна властивість обʼєкта FoodRecallNotice відображається як окремий атрибут у записі журналу.

Параметри LogPropertiesAttribute

Атрибут LogPropertiesAttribute надає кілька параметрів для контролю того, як властивості включаються до журналів:

  • OmitReferenceName: Коли встановлено в true, імʼя параметра опускається з ключів атрибутів. У наведеному вище прикладі ключі атрибутів — це просто імена властивостей (наприклад, “BrandName”), а не “foodRecallNotice.BrandName”.

  • IncludeProperties: Використовується для вказівки, які властивості слід включити. Якщо не вказано, всі властивості включаються.

  • ExcludeProperties: Використовується для вказівки, які властивості слід виключити з журналювання.

  • IncludeSensitive: Коли встановлено в true, властивості, позначені атрибутом [Sensitive], включаються до журналів. Стандартне значення — false.

Повний приклад

Ось повний приклад, який обʼєднує все:

using System;
using Microsoft.Extensions.Logging;
using OpenTelemetry;
using OpenTelemetry.Logs;

// Визначення комплексного обʼєкта
public struct FoodRecallNotice
{
    public string? BrandName { get; set; }
    public string? ProductDescription { get; set; }
    public string? ProductType { get; set; }
    public string? RecallReasonDescription { get; set; }
    public string? CompanyName { get; set; }
}

// Метод розширення Logger
internal static partial class LoggerExtensions
{
    [LoggerMessage(LogLevel.Critical)]
    public static partial void FoodRecallNotice(
        this ILogger logger,
        [LogProperties(OmitReferenceName = true)] in FoodRecallNotice foodRecallNotice);
}

// Головна програма
class Program
{
    static void Main(string[] args)
    {
        // Створіть фабрику логів з OpenTelemetry
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder.AddOpenTelemetry(options =>
            {
                options.AddConsoleExporter();
            });
        });

        // Отримайте екземпляр логера
        var logger = loggerFactory.CreateLogger<Program>();

        // Створіть комплексний обʼєкт
        var foodRecallNotice = new FoodRecallNotice
        {
            BrandName = "Contoso",
            ProductDescription = "Salads",
            ProductType = "Food & Beverages",
            RecallReasonDescription = "due to a possible health risk from Listeria monocytogenes",
            CompanyName = "Contoso Fresh Vegetables, Inc.",
        };

        // Записати комплексний обʼєкт
        logger.FoodRecallNotice(foodRecallNotice);

        Console.WriteLine("Press any key to exit");
        Console.ReadKey();
    }
}

Дізнайтеся більше


Востаннє змінено July 12, 2026: [uk] Ukrainian documentation for OpenTelemetry (0301c8f3)