Использование трассировок действий и OpenTelemetry

Построитель API данных (DAB) поддерживает OpenTelemetry для распределенной трассировки и метрик, что позволяет отслеживать и диагностировать поведение таких компонентов, как REST, GraphQL, операции базы данных и внутренние промежуточные системы.

Схема, на которой показан поток OpenTelemetry.

Предпосылки

Инструмент запуска

Используйте dab add-telemetry для добавления параметров OpenTelemetry в конфигурацию.

  1. Убедитесь, что у вас есть файл конфигурации. Если необходимо создать его, выполните следующую команду:

    dab init \
    --database-type mssql \
    --connection-string "<sql-connection-string>"

  2. Добавьте параметры OpenTelemetry в файл конфигурации.

    dab add-telemetry \
    -c dab-config.json \
    --otel-enabled true \
    --otel-endpoint "http://localhost:4317" \
    --otel-protocol "grpc" \
    --otel-service-name "dab"

  3. Запустите DAB.

    dab start

Тестирование в телеметрическом бэкенде

  1. Откройте серверную часть или пользовательский интерфейс сборщика OpenTelemetry.

  2. Убедитесь, что трассировки и метрики поступают для вызовов REST, GraphQL или вызовов базы данных.

Замечание

Панель мониторинга .NET Aspire является идеальной частью цикла разработчика. Он включает встроенные представления для трассировок и метрик OpenTelemetry.

Трассировки построителя API данных

DAB создает "действия" OpenTelemetry для:

  • Входящие HTTP-запросы (конечные точки REST)
  • операции GraphQL
  • Запросы базы данных (для каждой сущности)
  • Внутренние действия ПО промежуточного слоя (например, обработка запросов, отслеживание ошибок)
  • Выполнение инструмента MCP (вызов каждого языка обработки данных (DML) и вызов пользовательского инструмента)

Замечание

Функции построителя данных 2.0, описанные в этом разделе, находятся в предварительной версии и могут измениться до общедоступной доступности. Дополнительные сведения см. в статье "Новые возможности" версии 2.0.

Каждое действие включает подробные теги (метаданные), такие как:

  • http.method http.url http.querystring status.code
  • action.type (CRUD, операция GraphQL)
  • user.role, user-agent
  • data-source.type, data-source.name
  • api.type (REST или GraphQL)

Ошибки и исключения также отслеживаются с подробными сведениями.

Метрики построителя данных API

DAB выдает метрики OpenTelemetry, такие как:

  • Всего запросов: счетчик, помеченный методом HTTP, состоянием, конечной точкой и типом API.
  • Ошибки: счетчик, помеченный типом ошибки, методом HTTP, состоянием, конечной точкой и типом API.
  • Длительность запроса: гистограмма (в миллисекундах), помеченная методом HTTP, состоянием, конечной точкой и типом API.
  • Активные запросы: счетчик вверх и вниз для одновременных запросов.

Метрики используют API .NET Meter и пакет SDK OpenTelemetry.

Configuration

Добавьте раздел open-telemetry под runtime.telemetry в ваш файл конфигурации.

{
    "runtime": {
        "telemetry": {
            "open-telemetry": {
                "enabled": true,
                "endpoint": "http://otel-collector:4317",
                "service-name": "dab",
                "exporter-protocol": "grpc"
            }
        }
    }
}

Command-line

Настройка OpenTelemetry с помощью dab add-telemetry.

  • --otel-enabled
  • --otel-endpoint
  • --otel-protocol
  • --otel-service-name
  • --otel-headers

Example

dab add-telemetry \
    -c dab-config.json \
    --otel-enabled true \
    --otel-endpoint "http://localhost:4317" \
    --otel-protocol "grpc" \
    --otel-service-name "dab"

Результирующая конфигурация

Замечание

Опции OpenTelemetry недоступны на dab configure.

{
    "runtime": {
        "telemetry": {
            "open-telemetry": {
                "enabled": true,
                "endpoint": "http://localhost:4317",
                "service-name": "dab",
                "exporter-protocol": "grpc"
            }
        }
    }
}

Экспорт и визуализация

Данные телеметрии экспортируются через .NET OpenTelemetry SDK в вашу настроенную серверную часть, например, Azure Monitor или Jaeger. Убедитесь, что серверная часть запущена и доступна по указанному адресу endpoint. Для визуализации можно использовать любую платформу, совместимую с OpenTelemetry.

SDK для OpenTelemetry контролирует время экспорта. Он экспортирует трассировки после завершения активностей. Он экспортирует метрики в периодический интервал, настроенный пакетом SDK. Если интервал не задан, пакет SDK использует его по умолчанию.

Замечание

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

Заметки о реализации

  • Трассировки и метрики охватывают все операции REST, GraphQL, MCP и работы с базами данных.
  • Обработчики посреднического слоя и ошибок также передают телеметрические данные.
  • Контекст распространяется с помощью запросов

Связанный контент

  • Last updated on