DB-GPT 可观测性实践日志、链路追踪与 OpenTelemetry/Jaeger 集成指南【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT**Observability可观测性**是衡量一个系统能否通过其外部输出推断出内部状态的能力。对于 DB-GPT 这类同时包含 Web 服务、模型 Worker、Embedding 服务与 Agent 编排的复杂 AI 数据应用来说可观测性直接决定了故障排查、性能分析与日常监控的效率。本文基于 DB-GPT 官方文档《Observability》及其底层源码系统讲解 DB-GPT 的两大可观测性机制——日志Logging与链路追踪Tracing并给出从本地 JSONL 存储、dbgpt trace命令行分析到 OpenTelemetry 协议导出、Jaeger 可视化乃至 Docker Compose 多服务集群全链路追踪的完整落地步骤。读完本文你将能独立完成 DB-GPT 的日志与追踪配置并在单机或集群环境下借助 Jaeger 洞察一次对话请求在 controller、LLM worker、embedding-worker 与 webserver 之间的完整调用链路。一、可观测性在 DB-GPT 中的落地机制在软件系统中可观测性是通过检查系统输出来理解其内部状态的能力对于调试debugging、监控monitoring和系统维护maintaining至关重要。DB-GPT 通过以下两大机制提供可观测性日志LoggingDB-GPT 会记录各类事件与指标帮助理解系统的内部状态追踪TracingDB-GPT 内置追踪能力帮助理解请求在系统中的流转过程。从源码结构看日志与追踪分别由dbgpt.util.utils与dbgpt.util.tracer两个模块承载后者是 DB-GPT 可观测性的核心包含base.pySpan 数据模型与 SpanType 定义、tracer_impl.pyTracer 实现与初始化、span_storage.py本地文件/内存存储、opentelemetry.pyOTLP 导出以及tracer_cli.pytrace 分析命令行相关文件均位于 packages/dbgpt-core/src/dbgpt/util/tracer 目录下。二、日志Logging配置级别与存储位置DB-GPT 允许你配置日志级别和存储位置。默认情况下日志存储在 DB-GPT 根目录下的logs目录中。你可以通过设置DBGPT_LOG_LEVEL和DBGPT_LOG_DIR环境变量来更改日志级别与存储位置。2.1 环境变量配置# 日志级别FATAL / ERROR / WARNING / INFO / DEBUG / NOTSET export DBGPT_LOG_LEVELDEBUG # 日志存储目录 export DBGPT_LOG_DIR/path/to/your/logs2.2 源码级参数说明从 packages/dbgpt-core/src/dbgpt/util/utils.py 的实现可以看到日志机制的核心细节_get_logging_level()读取DBGPT_LOG_LEVEL环境变量默认值为INFO见 utils.py#L28-L29LoggingParameters定义了level与file两个配置项其中level支持的合法取值为FATAL、ERROR、WARNING、INFO、DEBUG、NOTSET并通过${env:DBGPT_LOG_LEVEL:-INFO}形式与系统参数配置系统打通见 utils.py#L32-L54_build_logger()在写入文件时使用logging.handlers.TimedRotatingFileHandler按天whenD轮转日志文件日志格式统一为%(asctime)s | %(levelname)s | %(name)s | %(message)s见 utils.py#L132-L158。DBGPT_LOG_DIR用于指定日志根目录实际日志文件名由各服务通过setup_logging(logger_name, ...)传入最终通过resolve_root_path解析为绝对路径。设置DBGPT_LOG_LEVELDEBUG可以获得最详尽的调用信息是排查问题时的首选级别。三、链路追踪Tracing核心机制DB-GPT 内置追踪能力允许你追踪请求在系统中的流转。其核心设计在 tracer_impl.py 中Span 数据模型一次操作如一次函数调用、一次模型请求对应一个 Span每个 Span 携带trace_id、span_id、parent_span_id、operation_name、span_type和metadata等字段通过parent_span_id形成父子层级共同构成一条完整的调用链Span 类型见 base.py#L23-L27BASE基础操作、RUN服务启动运行、CHAT对话、AGENTAgent 行为Tracer 架构DefaultTracer负责 Span 的创建、结束与存储分发TracerManager通过root_tracer全局单例提供start_span/end_span/get_current_span等无侵入接口并确保任何情况下都不抛异常、尽量不阻塞trace装饰器开发人员只需在目标函数上添加trace(operation_namexxx)即可自动生成 Span装饰器会自动提取函数参数作为metadata默认排除self、cls可额外指定exclude_params并同时支持同步函数与异步函数见 tracer_impl.py#L207-L262。initialize_tracer()见 tracer_impl.py#L400-L453负责在服务启动时装配整个追踪体系注册DefaultTracer、SpanStorageContainer可同时挂载多个存储后端、FileSpanStorage并根据TracerParameters判断是否需要额外挂载OpenTelemetrySpanStorage。四、Trace 存储与本地分析4.1 本地存储Local StorageDB-GPT 默认将 traces 存储在 DB-GPT 日志目录下的traces目录中实际文件位于logs/dbgpt*.jsonl每行一条 JSON 格式的 Span 记录。从 span_storage.py 的实现可以看到本地存储的细节FileSpanStorage将每个 Span 序列化为 JSON 写入文件并按日期自动滚动跨天时会把当日文件重命名为文件名_YYYY-MM-DD.jsonl的格式见 span_storage.py#L141-L153SpanStorageContainer采用异步批量写入策略Span 先进入内存队列达到批量阈值默认batch_size10或刷新间隔默认flush_interval10秒后由后台线程统一分发到各存储后端且单条写入失败不会影响整体见 span_storage.py#L28-L113。4.2 使用 dbgpt trace 命令行分析本地 Tracedbgpt trace是 DB-GPT 内置的 trace 分析命令行工具见 tracer_cli.py默认读取logs目录下的dbgpt*.jsonl文件提供三个子命令# 列出最近 20 条 Span支持按 trace_id / span_id / span_type / parent_span_id 过滤 # 支持 --search 全文搜索、--start_time / --end_time 时间过滤、--desc 倒序 # 以及 --output text|html|csv|latex|json 输出格式 dbgpt trace list # 将指定 trace 的 Span 层级结构以树形展示 dbgpt trace tree --trace_id {your_trace_id} # 展示对话详情服务运行参数、系统信息、用户输入、模型输出、错误信息等 # 支持 --tree 树形展示、--hide_conv 隐藏对话内容、--hide_run_params 隐藏运行参数 dbgpt trace chatdbgpt trace list还支持--json_pathJSONPath 提取例如$.metadata.messages[0].content、--value仅显示提取值等高级选项便于从 trace 中精准抽取所需字段。4.3 Debugging 文档如果你希望更深入地了解本地 trace 存储的用法与分析手段可继续阅读 调试指南。五、OpenTelemetry 支持导出分布式追踪DB-GPT 同时支持 OpenTelemetry 分布式追踪。现在你可以通过 OpenTelemetry ProtocolOTLP将 traces 导出到 Jaeger、Zipkin 等兼容 OpenTelemetry 的后端。5.1 安装依赖要启用 OpenTelemetry 支持需要先安装以下包pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp这些依赖与源码中OpenTelemetrySpanStorage的导入要求一致——若缺失opentelemetry.py 会抛出明确的安装提示见 opentelemetry.py#L5-L19。5.2 修改 .env 启用 OpenTelemetry 追踪## 是否启用 DB-GPT 向 OpenTelemetry 发送 trace TRACER_TO_OPEN_TELEMETRYTrue ## 更多细节参见 OTLP exporter 文档 OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://localhost:4317在上述配置中OTEL_EXPORTER_OTLP_TRACES_ENDPOINT可以改为你自己的 OTLP Collector 或后端地址默认使用gRPC端点端口 4317若使用 HTTP 协议则为 4318。5.3 底层导出实现从源码看TRACER_TO_OPEN_TELEMETRYTrue会在TracerParameters.__post_init__中把 exporter 自动设置为telemetry见 tracer_impl.py#L386-L389随后initialize_tracer()会挂载OpenTelemetrySpanStorage见 tracer_impl.py#L424-L434。OpenTelemetrySpanStorage使用OTLPSpanExporter与BatchSpanProcessor将 Span 批量上报并把 DB-GPT 的trace_id、span_id、parent_span_id、span_type以及可序列化的 metadata 写入 OTel Span 属性dbgpt_trace_id、dbgpt_span_id、dbgpt_parent_span_id等同时通过SpanContext重建父级上下文以保留调用层级见 opentelemetry.py#L22-L119。此外TracerParameters还支持以下环境变量以微调 OTLP 连接行为见 tracer_impl.py#L351-L378配置项对应环境变量说明otlp_endpointOTEL_EXPORTER_OTLP_TRACES_ENDPOINTOTLP 上报端点otlp_insecureOTEL_EXPORTER_OTLP_TRACES_INSECURE是否使用非安全连接otlp_timeoutOTEL_EXPORTER_OTLP_TRACES_TIMEOUT连接超时时间秒六、Jaeger 支持Docker 单机示例下面以 Jaeger 为例展示如何使用 OpenTelemetry 对 DB-GPT 进行链路追踪。6.1 启动 Jaeger all-in-one 镜像docker run --rm --name jaeger \ -e COLLECTOR_ZIPKIN_HOST_PORT:9411 \ -p 6831:6831/udp \ -p 6832:6832/udp \ -p 5778:5778 \ -p 16686:16686 \ -p 4317:4317 \ -p 4318:4318 \ -p 14250:14250 \ -p 14268:14268 \ -p 14269:14269 \ -p 9411:9411 \ jaegertracing/all-in-one:1.58各端口用途端口协议用途16686TCPJaeger UI 前端4317gRPC接收 OpenTelemetry ProtocolOTLPgRPC 数据4318HTTP接收 OpenTelemetry ProtocolOTLPHTTP 数据6831UDP接收 jaeger.thrift 紧凑协议多数 SDK 使用6832UDP接收 jaeger.thrift 二进制协议14268HTTP接收 jaeger.thrift 直连上报14250gRPC接收 model.proto 格式数据9411HTTP兼容 Zipkin 上报5778、14269HTTP配置与管理接口6.2 配置 .env 并启动 DB-GPT与前面一致修改.env文件启用 OpenTelemetry 追踪TRACER_TO_OPEN_TELEMETRYTrue OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://localhost:4317启动 DB-GPT 服务dbgpt start webserver现在即可访问 Jaeger UIhttp://localhost:16686查看 traces。6.3 Jaeger UI 界面示例以下为 Jaeger UI 的实际界面截图帮助你快速定位需要关注的功能区域Search Traces 页面——在该页面可以选择服务名、时间范围并搜索 trace普通对话 Trace——一次常规对话请求的完整调用链视图RAG 对话跨服务 Trace——在集群模式下可以看到 DB-GPT controller、LLM worker 与 webserver 之间的跨服务通信七、Jaeger Docker Compose集群可观测性方案如果你希望用 docker-compose 一次性启动 DB-GPT 集群与 Jaeger可以使用下面的docker-compose.yml# An example of using docker-compose to start a cluster with observability enabled. version: 3.10 services: jaeger: image: jaegertracing/all-in-one:1.58 restart: unless-stopped networks: - dbgptnet ports: # serve frontend - 16686:16686 # accept jaeger.thrift over Thrift-compact protocol (used by most SDKs) - 6831:6831 # accept OpenTelemetry Protocol (OTLP) over HTTP - 4318:4318 # accept OpenTelemetry Protocol (OTLP) over gRPC - 4317:4317 - 14268:14268 environment: - LOG_LEVELdebug - SPAN_STORAGE_TYPEbadger - BADGER_EPHEMERALfalse - BADGER_DIRECTORY_VALUE/badger/data - BADGER_DIRECTORY_KEY/badger/key volumes: - jaeger-badger:/badger user: root controller: image: eosphorosai/dbgpt:latest command: dbgpt start controller restart: unless-stopped environment: - TRACER_TO_OPEN_TELEMETRYTrue - OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://jaeger:4317 - DBGPT_LOG_LEVELDEBUG networks: - dbgptnet llm-worker: image: eosphorosai/dbgpt:latest command: dbgpt start worker --model_type proxy --model_name chatgpt_proxyllm --model_path chatgpt_proxyllm --proxy_server_url ${OPENAI_API_BASE}/chat/completions --proxy_api_key ${OPENAI_API_KEY} --controller_addr http://controller:8000 environment: # Your real openai model name, e.g. gpt-3.5-turbo, gpt-4o - PROXYLLM_BACKENDgpt-3.5-turbo - TRACER_TO_OPEN_TELEMETRYTrue - OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://jaeger:4317 - DBGPT_LOG_LEVELDEBUG depends_on: - controller restart: unless-stopped networks: - dbgptnet ipc: host embedding-worker: image: eosphorosai/dbgpt:latest command: dbgpt start worker --worker_type text2vec --model_name proxy_http_openapi --model_path proxy_http_openapi --proxy_server_url ${OPENAI_API_BASE}/embeddings --proxy_api_key ${OPENAI_API_KEY} --controller_addr http://controller:8000 environment: - proxy_http_openapi_proxy_backendtext-embedding-3-small - TRACER_TO_OPEN_TELEMETRYTrue - OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://jaeger:4317 - DBGPT_LOG_LEVELDEBUG depends_on: - controller restart: unless-stopped networks: - dbgptnet ipc: host webserver: image: eosphorosai/dbgpt:latest command: dbgpt start webserver --light --remote_embedding --controller_addr http://controller:8000 environment: - LLM_MODELchatgpt_proxyllm - EMBEDDING_MODELproxy_http_openapi - TRACER_TO_OPEN_TELEMETRYTrue - OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://jaeger:4317 depends_on: - controller - llm-worker - embedding-worker volumes: - dbgpt-data:/app/pilot/data - dbgpt-message:/app/pilot/message ports: - 5670:5670/tcp restart: unless-stopped networks: - dbgptnet volumes: dbgpt-data: dbgpt-message: jaeger-badger: networks: dbgptnet: driver: bridge name: dbgptnet7.1 启动集群OPENAI_API_KEY{your api key} OPENAI_API_BASEhttps://api.openai.com/v1 docker compose up -d请将{your api key}替换为真实的 OpenAI API Key将https://api.openai.com/v1替换为真实的 OpenAI API Base URL。7.2 方案要点解读Jaeger 持久化示例使用 Badger 作为 Jaeger 的存储引擎SPAN_STORAGE_TYPEbadger并通过jaeger-badger卷持久化/badger目录避免容器重启后 trace 丢失逐服务开启追踪controller、llm-worker、embedding-worker、webserver 四个服务都设置了TRACER_TO_OPEN_TELEMETRYTrue且上报端点统一指向http://jaeger:4317容器网络内直接使用服务名jaeger无需经过宿主机端口映射全链路打通所有服务都加入同一个 bridge 网络dbgptnet并依赖 controller 先启动从而保证 webserver 可以同时发现 LLM worker 与 embedding worker使一次对话请求的 trace 能跨越 controller、worker 与 webserver 三个进程完整串联。集群启动后访问http://localhost:16686即可在 Jaeger UI 中查看 traces。在上面的 RAG 对话截图中你可以看到 DB-GPT controller、LLM worker 与 webserver 之间跨服务通信的完整链路。仓库中提供了与此示例等价的可直接运行文件详见 docker/compose_examples/observability/docker-compose.yml该文件默认使用eosphorosai/dbgpt-openai:latest镜像构建方式参见 docker/base/build_proxy_image.sh 中的注释说明同时可结合 HA 集群配置示例 理解生产化部署的扩展方向。八、最佳实践小结先本地、后远程排查问题时应优先使用本地logs/dbgpt*.jsonl文件配合dbgpt trace list / tree / chat命令快速定位确认问题方向后再开启 OpenTelemetry 导出避免无谓的链路开销按需开启追踪TRACER_TO_OPEN_TELEMETRYTrue对所有服务webserver、controller、worker、embedding worker都要一致配置否则跨服务调用链会断裂利用日志级别集群排障时建议将DBGPT_LOG_LEVEL提升到DEBUG与 Jaeger 中的 Span 时间线相互印证善用 metadata 属性Jaeger 中每个 Span 都会携带dbgpt_trace_id、dbgpt_span_id、dbgpt_parent_span_id、span_type等属性以及函数级参数 metadata可按这些字段在 Jaeger UI 中进行标签搜索快速定位慢请求与异常 Span。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/14 19:02:12 · 阅读 1.2k DB-GPT 可观测性实践：日志、链路追踪与 OpenTelemetry/Jaeger 集成指南
DB-GPT 可观测性实践日志、链路追踪与 OpenTelemetry/Jaeger 集成指南【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT**Observability可观测性**是衡量一个系统能否通过其外部输出推断出内部状态的能力。对于 DB-GPT 这类同时包含 Web 服务、模型 Worker、Embedding 服务与 Agent 编排的复杂 AI 数据应用来说可观测性直接决定了故障排查、性能分析与日常监控的效率。本文基于 DB-GPT 官方文档《Observability》及其底层源码系统讲解 DB-GPT 的两大可观测性机制——日志Logging与链路追踪Tracing并给出从本地 JSONL 存储、dbgpt trace命令行分析到 OpenTelemetry 协议导出、Jaeger 可视化乃至 Docker Compose 多服务集群全链路追踪的完整落地步骤。读完本文你将能独立完成 DB-GPT 的日志与追踪配置并在单机或集群环境下借助 Jaeger 洞察一次对话请求在 controller、LLM worker、embedding-worker 与 webserver 之间的完整调用链路。一、可观测性在 DB-GPT 中的落地机制在软件系统中可观测性是通过检查系统输出来理解其内部状态的能力对于调试debugging、监控monitoring和系统维护maintaining至关重要。DB-GPT 通过以下两大机制提供可观测性日志LoggingDB-GPT 会记录各类事件与指标帮助理解系统的内部状态追踪TracingDB-GPT 内置追踪能力帮助理解请求在系统中的流转过程。从源码结构看日志与追踪分别由dbgpt.util.utils与dbgpt.util.tracer两个模块承载后者是 DB-GPT 可观测性的核心包含base.pySpan 数据模型与 SpanType 定义、tracer_impl.pyTracer 实现与初始化、span_storage.py本地文件/内存存储、opentelemetry.pyOTLP 导出以及tracer_cli.pytrace 分析命令行相关文件均位于 packages/dbgpt-core/src/dbgpt/util/tracer 目录下。二、日志Logging配置级别与存储位置DB-GPT 允许你配置日志级别和存储位置。默认情况下日志存储在 DB-GPT 根目录下的logs目录中。你可以通过设置DBGPT_LOG_LEVEL和DBGPT_LOG_DIR环境变量来更改日志级别与存储位置。2.1 环境变量配置# 日志级别FATAL / ERROR / WARNING / INFO / DEBUG / NOTSET export DBGPT_LOG_LEVELDEBUG # 日志存储目录 export DBGPT_LOG_DIR/path/to/your/logs2.2 源码级参数说明从 packages/dbgpt-core/src/dbgpt/util/utils.py 的实现可以看到日志机制的核心细节_get_logging_level()读取DBGPT_LOG_LEVEL环境变量默认值为INFO见 utils.py#L28-L29LoggingParameters定义了level与file两个配置项其中level支持的合法取值为FATAL、ERROR、WARNING、INFO、DEBUG、NOTSET并通过${env:DBGPT_LOG_LEVEL:-INFO}形式与系统参数配置系统打通见 utils.py#L32-L54_build_logger()在写入文件时使用logging.handlers.TimedRotatingFileHandler按天whenD轮转日志文件日志格式统一为%(asctime)s | %(levelname)s | %(name)s | %(message)s见 utils.py#L132-L158。DBGPT_LOG_DIR用于指定日志根目录实际日志文件名由各服务通过setup_logging(logger_name, ...)传入最终通过resolve_root_path解析为绝对路径。设置DBGPT_LOG_LEVELDEBUG可以获得最详尽的调用信息是排查问题时的首选级别。三、链路追踪Tracing核心机制DB-GPT 内置追踪能力允许你追踪请求在系统中的流转。其核心设计在 tracer_impl.py 中Span 数据模型一次操作如一次函数调用、一次模型请求对应一个 Span每个 Span 携带trace_id、span_id、parent_span_id、operation_name、span_type和metadata等字段通过parent_span_id形成父子层级共同构成一条完整的调用链Span 类型见 base.py#L23-L27BASE基础操作、RUN服务启动运行、CHAT对话、AGENTAgent 行为Tracer 架构DefaultTracer负责 Span 的创建、结束与存储分发TracerManager通过root_tracer全局单例提供start_span/end_span/get_current_span等无侵入接口并确保任何情况下都不抛异常、尽量不阻塞trace装饰器开发人员只需在目标函数上添加trace(operation_namexxx)即可自动生成 Span装饰器会自动提取函数参数作为metadata默认排除self、cls可额外指定exclude_params并同时支持同步函数与异步函数见 tracer_impl.py#L207-L262。initialize_tracer()见 tracer_impl.py#L400-L453负责在服务启动时装配整个追踪体系注册DefaultTracer、SpanStorageContainer可同时挂载多个存储后端、FileSpanStorage并根据TracerParameters判断是否需要额外挂载OpenTelemetrySpanStorage。四、Trace 存储与本地分析4.1 本地存储Local StorageDB-GPT 默认将 traces 存储在 DB-GPT 日志目录下的traces目录中实际文件位于logs/dbgpt*.jsonl每行一条 JSON 格式的 Span 记录。从 span_storage.py 的实现可以看到本地存储的细节FileSpanStorage将每个 Span 序列化为 JSON 写入文件并按日期自动滚动跨天时会把当日文件重命名为文件名_YYYY-MM-DD.jsonl的格式见 span_storage.py#L141-L153SpanStorageContainer采用异步批量写入策略Span 先进入内存队列达到批量阈值默认batch_size10或刷新间隔默认flush_interval10秒后由后台线程统一分发到各存储后端且单条写入失败不会影响整体见 span_storage.py#L28-L113。4.2 使用 dbgpt trace 命令行分析本地 Tracedbgpt trace是 DB-GPT 内置的 trace 分析命令行工具见 tracer_cli.py默认读取logs目录下的dbgpt*.jsonl文件提供三个子命令# 列出最近 20 条 Span支持按 trace_id / span_id / span_type / parent_span_id 过滤 # 支持 --search 全文搜索、--start_time / --end_time 时间过滤、--desc 倒序 # 以及 --output text|html|csv|latex|json 输出格式 dbgpt trace list # 将指定 trace 的 Span 层级结构以树形展示 dbgpt trace tree --trace_id {your_trace_id} # 展示对话详情服务运行参数、系统信息、用户输入、模型输出、错误信息等 # 支持 --tree 树形展示、--hide_conv 隐藏对话内容、--hide_run_params 隐藏运行参数 dbgpt trace chatdbgpt trace list还支持--json_pathJSONPath 提取例如$.metadata.messages[0].content、--value仅显示提取值等高级选项便于从 trace 中精准抽取所需字段。4.3 Debugging 文档如果你希望更深入地了解本地 trace 存储的用法与分析手段可继续阅读 调试指南。五、OpenTelemetry 支持导出分布式追踪DB-GPT 同时支持 OpenTelemetry 分布式追踪。现在你可以通过 OpenTelemetry ProtocolOTLP将 traces 导出到 Jaeger、Zipkin 等兼容 OpenTelemetry 的后端。5.1 安装依赖要启用 OpenTelemetry 支持需要先安装以下包pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp这些依赖与源码中OpenTelemetrySpanStorage的导入要求一致——若缺失opentelemetry.py 会抛出明确的安装提示见 opentelemetry.py#L5-L19。5.2 修改 .env 启用 OpenTelemetry 追踪## 是否启用 DB-GPT 向 OpenTelemetry 发送 trace TRACER_TO_OPEN_TELEMETRYTrue ## 更多细节参见 OTLP exporter 文档 OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://localhost:4317在上述配置中OTEL_EXPORTER_OTLP_TRACES_ENDPOINT可以改为你自己的 OTLP Collector 或后端地址默认使用gRPC端点端口 4317若使用 HTTP 协议则为 4318。5.3 底层导出实现从源码看TRACER_TO_OPEN_TELEMETRYTrue会在TracerParameters.__post_init__中把 exporter 自动设置为telemetry见 tracer_impl.py#L386-L389随后initialize_tracer()会挂载OpenTelemetrySpanStorage见 tracer_impl.py#L424-L434。OpenTelemetrySpanStorage使用OTLPSpanExporter与BatchSpanProcessor将 Span 批量上报并把 DB-GPT 的trace_id、span_id、parent_span_id、span_type以及可序列化的 metadata 写入 OTel Span 属性dbgpt_trace_id、dbgpt_span_id、dbgpt_parent_span_id等同时通过SpanContext重建父级上下文以保留调用层级见 opentelemetry.py#L22-L119。此外TracerParameters还支持以下环境变量以微调 OTLP 连接行为见 tracer_impl.py#L351-L378配置项对应环境变量说明otlp_endpointOTEL_EXPORTER_OTLP_TRACES_ENDPOINTOTLP 上报端点otlp_insecureOTEL_EXPORTER_OTLP_TRACES_INSECURE是否使用非安全连接otlp_timeoutOTEL_EXPORTER_OTLP_TRACES_TIMEOUT连接超时时间秒六、Jaeger 支持Docker 单机示例下面以 Jaeger 为例展示如何使用 OpenTelemetry 对 DB-GPT 进行链路追踪。6.1 启动 Jaeger all-in-one 镜像docker run --rm --name jaeger \ -e COLLECTOR_ZIPKIN_HOST_PORT:9411 \ -p 6831:6831/udp \ -p 6832:6832/udp \ -p 5778:5778 \ -p 16686:16686 \ -p 4317:4317 \ -p 4318:4318 \ -p 14250:14250 \ -p 14268:14268 \ -p 14269:14269 \ -p 9411:9411 \ jaegertracing/all-in-one:1.58各端口用途端口协议用途16686TCPJaeger UI 前端4317gRPC接收 OpenTelemetry ProtocolOTLPgRPC 数据4318HTTP接收 OpenTelemetry ProtocolOTLPHTTP 数据6831UDP接收 jaeger.thrift 紧凑协议多数 SDK 使用6832UDP接收 jaeger.thrift 二进制协议14268HTTP接收 jaeger.thrift 直连上报14250gRPC接收 model.proto 格式数据9411HTTP兼容 Zipkin 上报5778、14269HTTP配置与管理接口6.2 配置 .env 并启动 DB-GPT与前面一致修改.env文件启用 OpenTelemetry 追踪TRACER_TO_OPEN_TELEMETRYTrue OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://localhost:4317启动 DB-GPT 服务dbgpt start webserver现在即可访问 Jaeger UIhttp://localhost:16686查看 traces。6.3 Jaeger UI 界面示例以下为 Jaeger UI 的实际界面截图帮助你快速定位需要关注的功能区域Search Traces 页面——在该页面可以选择服务名、时间范围并搜索 trace普通对话 Trace——一次常规对话请求的完整调用链视图RAG 对话跨服务 Trace——在集群模式下可以看到 DB-GPT controller、LLM worker 与 webserver 之间的跨服务通信七、Jaeger Docker Compose集群可观测性方案如果你希望用 docker-compose 一次性启动 DB-GPT 集群与 Jaeger可以使用下面的docker-compose.yml# An example of using docker-compose to start a cluster with observability enabled. version: 3.10 services: jaeger: image: jaegertracing/all-in-one:1.58 restart: unless-stopped networks: - dbgptnet ports: # serve frontend - 16686:16686 # accept jaeger.thrift over Thrift-compact protocol (used by most SDKs) - 6831:6831 # accept OpenTelemetry Protocol (OTLP) over HTTP - 4318:4318 # accept OpenTelemetry Protocol (OTLP) over gRPC - 4317:4317 - 14268:14268 environment: - LOG_LEVELdebug - SPAN_STORAGE_TYPEbadger - BADGER_EPHEMERALfalse - BADGER_DIRECTORY_VALUE/badger/data - BADGER_DIRECTORY_KEY/badger/key volumes: - jaeger-badger:/badger user: root controller: image: eosphorosai/dbgpt:latest command: dbgpt start controller restart: unless-stopped environment: - TRACER_TO_OPEN_TELEMETRYTrue - OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://jaeger:4317 - DBGPT_LOG_LEVELDEBUG networks: - dbgptnet llm-worker: image: eosphorosai/dbgpt:latest command: dbgpt start worker --model_type proxy --model_name chatgpt_proxyllm --model_path chatgpt_proxyllm --proxy_server_url ${OPENAI_API_BASE}/chat/completions --proxy_api_key ${OPENAI_API_KEY} --controller_addr http://controller:8000 environment: # Your real openai model name, e.g. gpt-3.5-turbo, gpt-4o - PROXYLLM_BACKENDgpt-3.5-turbo - TRACER_TO_OPEN_TELEMETRYTrue - OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://jaeger:4317 - DBGPT_LOG_LEVELDEBUG depends_on: - controller restart: unless-stopped networks: - dbgptnet ipc: host embedding-worker: image: eosphorosai/dbgpt:latest command: dbgpt start worker --worker_type text2vec --model_name proxy_http_openapi --model_path proxy_http_openapi --proxy_server_url ${OPENAI_API_BASE}/embeddings --proxy_api_key ${OPENAI_API_KEY} --controller_addr http://controller:8000 environment: - proxy_http_openapi_proxy_backendtext-embedding-3-small - TRACER_TO_OPEN_TELEMETRYTrue - OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://jaeger:4317 - DBGPT_LOG_LEVELDEBUG depends_on: - controller restart: unless-stopped networks: - dbgptnet ipc: host webserver: image: eosphorosai/dbgpt:latest command: dbgpt start webserver --light --remote_embedding --controller_addr http://controller:8000 environment: - LLM_MODELchatgpt_proxyllm - EMBEDDING_MODELproxy_http_openapi - TRACER_TO_OPEN_TELEMETRYTrue - OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://jaeger:4317 depends_on: - controller - llm-worker - embedding-worker volumes: - dbgpt-data:/app/pilot/data - dbgpt-message:/app/pilot/message ports: - 5670:5670/tcp restart: unless-stopped networks: - dbgptnet volumes: dbgpt-data: dbgpt-message: jaeger-badger: networks: dbgptnet: driver: bridge name: dbgptnet7.1 启动集群OPENAI_API_KEY{your api key} OPENAI_API_BASEhttps://api.openai.com/v1 docker compose up -d请将{your api key}替换为真实的 OpenAI API Key将https://api.openai.com/v1替换为真实的 OpenAI API Base URL。7.2 方案要点解读Jaeger 持久化示例使用 Badger 作为 Jaeger 的存储引擎SPAN_STORAGE_TYPEbadger并通过jaeger-badger卷持久化/badger目录避免容器重启后 trace 丢失逐服务开启追踪controller、llm-worker、embedding-worker、webserver 四个服务都设置了TRACER_TO_OPEN_TELEMETRYTrue且上报端点统一指向http://jaeger:4317容器网络内直接使用服务名jaeger无需经过宿主机端口映射全链路打通所有服务都加入同一个 bridge 网络dbgptnet并依赖 controller 先启动从而保证 webserver 可以同时发现 LLM worker 与 embedding worker使一次对话请求的 trace 能跨越 controller、worker 与 webserver 三个进程完整串联。集群启动后访问http://localhost:16686即可在 Jaeger UI 中查看 traces。在上面的 RAG 对话截图中你可以看到 DB-GPT controller、LLM worker 与 webserver 之间跨服务通信的完整链路。仓库中提供了与此示例等价的可直接运行文件详见 docker/compose_examples/observability/docker-compose.yml该文件默认使用eosphorosai/dbgpt-openai:latest镜像构建方式参见 docker/base/build_proxy_image.sh 中的注释说明同时可结合 HA 集群配置示例 理解生产化部署的扩展方向。八、最佳实践小结先本地、后远程排查问题时应优先使用本地logs/dbgpt*.jsonl文件配合dbgpt trace list / tree / chat命令快速定位确认问题方向后再开启 OpenTelemetry 导出避免无谓的链路开销按需开启追踪TRACER_TO_OPEN_TELEMETRYTrue对所有服务webserver、controller、worker、embedding worker都要一致配置否则跨服务调用链会断裂利用日志级别集群排障时建议将DBGPT_LOG_LEVEL提升到DEBUG与 Jaeger 中的 Span 时间线相互印证善用 metadata 属性Jaeger 中每个 Span 都会携带dbgpt_trace_id、dbgpt_span_id、dbgpt_parent_span_id、span_type等属性以及函数级参数 metadata可按这些字段在 Jaeger UI 中进行标签搜索快速定位慢请求与异常 Span。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考