教程：将 .NET Aspire 仪表板用于 Python 应用

项目
12/13/2024

.NET .NET Aspire 仪表板为查看遥测提供了出色的用户体验，并可作为独立容器映像使用，适用于任何启用 OpenTelemetry的应用。本文中，你将学习如何：

在独立模式下启动 .NET.NET Aspire 仪表板。
将 .NET Aspire 仪表板与 Python 应用程序一起使用。

先决条件

若要完成本教程，需要满足以下条件：

Docker 或 Podman。
- 可以使用备用容器运行时，但本文中的命令适用于 Docker。
在本地安装 Python 3.9 或更高版本。
示例应用程序。

示例应用程序

本教程可以使用 Flask、Django 或 FastAPI 完成。提供了每个框架中的一个示例应用程序，可帮助你遵循本教程。将示例应用程序下载或克隆到本地工作站。

烧瓶
FastAPI

git clone https://github.com/Azure-Samples/msdocs-python-flask-webapp-quickstart

git clone https://github.com/Azure-Samples/msdocs-python-fastapi-webapp-quickstart.git

在本地运行应用程序：

烧瓶
FastAPI

转到应用程序文件夹：

cd msdocs-python-flask-webapp-quickstart

为应用创建虚拟环境：

Windows
macOS/Linux

py -m venv .venv
.\.venv\Scripts\Activate.ps1

python3 -m venv .venv
source .venv/bin/activate

安装依赖项：
```
pip install -r requirements.txt
```
运行应用：
```
flask run
```
在 Web 浏览器中打开位于 http://localhost:5000 的示例应用程序。

本地运行的 Flask 应用的屏幕截图

转到应用程序文件夹：

cd msdocs-python-fastapi-webapp-quickstart

为应用创建虚拟环境：

Windows
macOS/Linux

py -m venv .venv
.\.venv\Scripts\Activate.ps1

python3 -m venv .venv
source .venv/bin/activate

安装依赖项：
```
pip install -r requirements.txt
```
运行应用：
```
uvicorn main:app --reload
```
在 Web 浏览器中打开位于 http://localhost:8000 的示例应用程序。

添加 OpenTelemetry

若要将 .NET Aspire 仪表板用于 Python 应用，需要安装 OpenTelemetry SDK 和导出程序。 OpenTelemetry SDK 提供用于检测应用程序的 API，导出程序将遥测数据发送到 .NET Aspire 仪表板。

安装 OpenTelemetry SDK 和导出程序：

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc

将新文件添加到名为 otlp_tracing.py 的应用程序，并添加以下代码：

import logging
from opentelemetry import metrics, trace

from opentelemetry._logs import set_logger_provider
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
    OTLPLogExporter,
)
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

def configure_oltp_grpc_tracing(
    endpoint: str = None
) -> trace.Tracer:
    # Configure Tracing
    traceProvider = TracerProvider()
    processor = BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint))
    traceProvider.add_span_processor(processor)
    trace.set_tracer_provider(traceProvider)

    # Configure Metrics
    reader = PeriodicExportingMetricReader(OTLPMetricExporter(endpoint=endpoint))
    meterProvider = MeterProvider(metric_readers=[reader])
    metrics.set_meter_provider(meterProvider)

    # Configure Logging
    logger_provider = LoggerProvider()
    set_logger_provider(logger_provider)

    exporter = OTLPLogExporter(endpoint=endpoint)
    logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
    handler = LoggingHandler(level=logging.NOTSET, logger_provider=logger_provider)
    handler.setFormatter(logging.Formatter("Python: %(message)s"))

    # Attach OTLP handler to root logger
    logging.getLogger().addHandler(handler)

    tracer = trace.get_tracer(__name__)
    return tracer

更新你的应用程序（app.py for Flask，main.py for FastAPI），以包括导入并调用 configure_oltp_grpc_tracing 函数：

import logging
from otlp_tracing import configure_otel_otlp

logging.basicConfig(level=logging.INFO)
tracer = configure_otel_otlp()
logger = logging.getLogger(__name__)

将 print 调用替换为应用程序中的 logger.info 调用。
重启应用程序。

框架专用工具

此工具仅专注于向我们的代码添加 OpenTelemetry。对于更详细的仪表，您可以使用 OpenTelemetry 工具包，以适用于您正在使用的特定框架。

烧瓶
FastAPI

安装 Flask 监测软件包：

pip install opentelemetry-instrumentation-flask

将以下代码添加到应用程序：

from opentelemetry.instrumentation.flask import FlaskInstrumentor

# add this line after configure_otel_otlp() call
FlaskInstrumentor().instrument()

安装 FastAPI 检测包：

pip install opentelemetry-instrumentation-fastapi

将以下代码添加到应用程序：

from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

# add this line after configure_otel_otlp() call
FastAPIInstrumentor.instrument_app(app)

启动 Aspire 仪表盘

若要在独立模式下启动 Aspire 仪表板，请运行以下命令 Docker 命令：

docker run --rm -it -p 18888:18888 -p 4317:18889 --name aspire-dashboard \
    mcr.microsoft.com/dotnet/aspire-dashboard:9.0

在 Docker 日志中，仪表板的端点和密钥将显示。复制密钥并导航到 Web 浏览器中的 http://localhost:18888。输入登录仪表板的密钥。

查看结构化日志

在 Python 应用程序中导航，你将在 Aspire 仪表板中看到结构化日志。结构化日志页显示应用程序中的日志，你可以筛选和搜索日志。

Aspire 仪表板的屏幕截图，显示 Python 应用程序日志

后续步骤

已成功将 .NET Aspire 仪表板用于 Python 应用程序。若要了解有关 .NET.NET Aspire 仪表板的详细信息，请参阅 Aspire 仪表板概述以及如何使用 .NET Aspire协调应用程序。

通过