如何配置VSCode调试Python Uvicorn+OpenTelemetry环境下的FastAPI

问题背景 #

此前已有方案可在VSCode中调试FastAPI应用，但现在需要结合Python OpenTelemetry自动埋点来调试。通过OpenTelemetry运行Python代码的CLI命令示例（Flask场景）如下：

opentelemetry-instrument --traces_exporter console --metrics_exporter console --logs_exporter console --service_name dice-server flask run -p 8080

当前使用的VSCode launch.json 配置为：

{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
    {
        "name": "Python: Uvicorn",
        "type": "python",
        "request": "launch",
        "module": "uvicorn",
        "console": "integratedTerminal",
        "justMyCode": true,
        "args": [
            "server.main:app",
            //"--reload",
            "--port",
            "8000"
        ],
        "envFile": "${workspaceFolder}/.env"
    }
]
}

需要调整配置，实现类似CLI的OpenTelemetry埋点启动方式，并支持VSCode调试。

解决方案 #

1. 修改launch.json配置 #

将原有配置替换为以下内容：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: OpenTelemetry + Uvicorn",
            "type": "python",
            "request": "launch",
            "module": "opentelemetry.instrumentation.bootstrap",
            "console": "integratedTerminal",
            "justMyCode": true,
            "args": [
                "--traces_exporter", "console",
                "--metrics_exporter", "console",
                "--logs_exporter", "console",
                "--service_name", "your-fastapi-service",
                "uvicorn",
                "server.main:app",
                "--port", "8000"
            ],
            "envFile": "${workspaceFolder}/.env"
        }
    ]
}

2. 配置说明 #

• module字段：改为opentelemetry.instrumentation.bootstrap，对应opentelemetry-instrument命令的底层启动模块，用于触发自动埋点逻辑。
• args参数：
  先添加OpenTelemetry的配置项（追踪、指标、日志输出方式及服务名称），再拼接原有的Uvicorn启动参数（命令、应用路径、端口），完全对齐CLI的运行逻辑。
• console字段：保留integratedTerminal，方便在VSCode终端查看OpenTelemetry的埋点输出数据。

3. 开发环境可选配置 #

如果需要开启Uvicorn热重载，可在args中添加--reload：

"args": [
    "--traces_exporter", "console",
    "--metrics_exporter", "console",
    "--logs_exporter", "console",
    "--service_name", "your-fastapi-service",
    "uvicorn",
    "server.main:app",
    "--port", "8000",
    "--reload"
]

4. 调试验证 #

选择新配置Python: OpenTelemetry + Uvicorn启动调试，即可同时实现：

• VSCode断点调试FastAPI代码
• OpenTelemetry自动埋点并在终端输出追踪、指标、日志数据

内容的提问来源于stack exchange，提问作者JobaDiniz