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 这类集成了模型服务、Agent 编排、RAG 检索与多 Worker 集群的 AI 数据平台中一次请求往往要穿越 webserver、controller、LLM worker、embedding worker 等多个进程没有可靠的日志与分布式追踪手段几乎无法定位性能瓶颈与故障根因。本文以 DB-GPT 仓库中的官方可观测性文档docs/docs/application/advanced_tutorial/observability.md为主体从日志配置、内置 Trace 存储到 OpenTelemetry/Jaeger 分布式追踪的完整接入流程展开讲解并结合仓库源码tracer_impl.py、opentelemetry.py与官方 Docker Compose 集群示例docker-compose.yml给出可复现的实战方案。读完本文你将能够配置 DB-GPT 的日志级别与存储位置理解内置 Trace 的落盘格式与dbgpt trace命令行分析工具以及将 DB-GPT 的跨服务调用链完整接入 Jaeger在浏览器中可视化查看对话、RAG 与集群级追踪。一、DB-GPT 中的可观测性机制在软件系统语境下可观测性指的是通过检查系统输出来理解其内部状态的能力这对于调试debugging、监控monitoring与系统维护maintaining至关重要。DB-GPT 通过以下两种机制向用户暴露系统内部状态日志LoggingDB-GPT 会记录系统运行过程中的各类事件与指标帮助开发者了解系统内部状态追踪TracingDB-GPT 内置了链路追踪能力可以还原一个请求在系统中流转的完整调用路径。从源码结构来看这两条路径都汇聚在 packages/dbgpt-core/src/dbgpt/util/tracer 目录下日志由统一的 Logging 参数体系驱动而追踪则由DefaultTracer、SpanStorageContainer与FileSpanStorage/OpenTelemetrySpanStorage等多种 Span 存储后端协作完成。下一节先介绍最基础的日志配置。二、Logging日志级别与存储位置配置2.1 两个关键环境变量DB-GPT 允许通过环境变量配置日志的级别与存放位置。默认情况下日志存放在 DB-GPT 根目录下的logs目录中。你可以通过如下两个环境变量进行调整环境变量作用默认值DBGPT_LOG_LEVEL控制日志级别INFODBGPT_LOG_DIR控制日志存放目录DB-GPT 根目录下的logs目录典型的配置方式是在.env文件或 shell 环境中设置## 日志级别FATAL / ERROR / WARNING / INFO / DEBUG / NOTSET DBGPT_LOG_LEVELDEBUG ## 日志目录 DBGPT_LOG_DIR/var/log/dbgpt2.2 源码级解读日志参数是如何被解析的日志级别并非硬编码的字符串而是通过环境变量动态读取。在 packages/dbgpt-core/src/dbgpt/util/utils.py#L28-L29 中可以看到其取值逻辑def _get_logging_level() - str: return os.getenv(DBGPT_LOG_LEVEL, INFO)同时DB-GPT 还以参数化方式封装了LoggingParameters同样位于utils.py中其level字段的默认值为${env:DBGPT_LOG_LEVEL:-INFO}并声明了合法取值集合level: Optional[str] field( default${env:DBGPT_LOG_LEVEL:-INFO}, metadata{ help: _(Logging level, just support FATAL, ERROR, WARNING, INFO, DEBUG, NOTSET), valid_values: [FATAL, ERROR, WARNING, INFO, DEBUG, NOTSET], }, )此外packages/dbgpt-core/src/dbgpt/_private/config.py#L318 也以os.getenv(DBGPT_LOG_LEVEL, INFO)的形式兜底读取该变量。这意味着无论通过.env文件、命令行还是dbgpt参数注入日志级别都能被统一识别。支持的级别为FATAL、ERROR、WARNING、INFO、DEBUG、NOTSET其中DEBUG级别在生产排查问题、INFO级别在日常运行时最为常用。三、Tracing内置链路追踪与本地 Trace 存储3.1 内置追踪能力与本地存储路径DB-GPT 内置的追踪能力可以在不改动任何业务代码的情况下自动记录请求在系统中的流转过程。默认情况下Trace 数据会以 JSON Lines.jsonl格式写入日志目录下的traces目录即默认路径为logs/dbgpt*.jsonl这些本地文件是后续使用dbgpt trace命令行工具进行离线分析的原料。关于本地 Trace 的存储细节与分析方法可参见仓库中的 Debugging调试与 Trace 日志分析指南。3.2 本地 Trace 的离线分析dbgpt trace 命令虽然本地.jsonl文件可以直接用文本编辑器查看但更推荐使用 DB-GPT 自带的命令行工具dbgpt trace来结构化地分析这些数据。常用子命令如下# 查看最新一次会话的详情 dbgpt trace chat # 查看服务运行时信息隐藏会话内容 dbgpt trace chat --hide_conv # 查看最近会话信息隐藏运行参数 dbgpt trace chat --hide_run_params # 查看会话详情与完整调用链树形展示 dbgpt trace chat --hide_run_params --tree # 基于 trace_id 查看指定会话 dbgpt trace chat --hide_run_params --trace_id your-trace-id # 列出所有 Trace dbgpt trace list # 按 span 类型过滤 dbgpt trace list --span_type chat # 全文搜索按 trace_id / span_id / operation_name / metadata 内容 dbgpt trace list --search Hello # 查看全部帮助 dbgpt trace chat --help dbgpt trace list --help例如dbgpt trace list会以表格形式输出每条 Trace 的Trace ID、Span ID、Operation Name与Conversation UID而dbgpt trace chat --tree则会输出形如下方的树形调用链直观展示一次对话从 Web 入口到模型生成的每一层耗时Operation: DB-GPT-Web-Entry (Start: 2023-10-12 03:06:43.180, End: None) Operation: get_chat_instance (Start: 2023-10-12 03:06:43.258, End: 2023-10-12 03:06:43.424) Operation: stream_generator (Start: 2023-10-12 03:06:43.425, End: None) Operation: BaseChat.stream_call (Start: 2023-10-12 03:06:43.426, End: None) Operation: WorkerManager.generate_stream (Start: 2023-10-12 03:06:43.426, End: None) Operation: DefaultModelWorker.generate_stream (Start: 2023-10-12 03:06:43.428, End: None) Operation: DefaultModelWorker_call.generate_stream_func (Start: 2023-10-12 03:06:43.430, End: 2023-10-12 03:06:48.518)3.3 本地存储的源码实现从源码层面看本地 Trace 存储由 tracer_impl.py 中的initialize_tracer()负责初始化。它会将FileSpanStorage加入SpanStorageContainerstorage_container SpanStorageContainer(system_app) tracer_filename resolve_root_path(tracer_filename) storage_container.append_storage(FileSpanStorage(tracer_filename))其中TracerParameters提供了多个可调参数包括fileTrace 落盘文件名如dbgpt_webserver_tracer.jsonl、root_operation_name根操作名、exporter导出器值为telemetry时启用 OpenTelemetry 导出、otlp_endpoint、otlp_insecure、otlp_timeout等。值得注意的关键逻辑在__post_init__中use_telemetry os.getenv(TRACER_TO_OPEN_TELEMETRY, false).lower() true if self.exporter is None and use_telemetry: self.exporter telemetry这解释了为什么只需要设置环境变量TRACER_TO_OPEN_TELEMETRYTrueDB-GPT 就会自动把exporter切换为telemetry从而在保留本地文件存储的同时额外启用 OpenTelemetry 导出通道。四、OpenTelemetry 支持将 Trace 导出到 OTLP 后端4.1 安装 OpenTelemetry 依赖DB-GPT 支持通过 OpenTelemetry 标准协议OTLP将 Trace 导出到 Jaeger、Zipkin 等兼容后端从而实现分布式追踪。首先需要安装以下 Python 包pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp如果缺少上述依赖opentelemetry.py模块会直接抛出带安装提示的ImportError提醒你安装这三个包。4.2 修改 .env 启用 OpenTelemetry然后在.env文件中启用 OpenTelemetry 追踪并指定 OTLP 端点## 是否将 DB-GPT 的 Trace 发送到 OpenTelemetry TRACER_TO_OPEN_TELEMETRYTrue ## OTLP 导出端点默认使用 gRPC 协议 OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://localhost:4317说明OTEL_EXPORTER_OTLP_TRACES_ENDPOINT指向你的 OTLP Collector 或后端地址可以按需替换官方默认使用gRPC 端点端口4317若后端仅提供 HTTP 协议则对应端口为4318详见下文 Docker Compose 配置中的端口映射源码中该端点不仅支持环境变量直接注入还支持以${env:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT}占位符的形式引用环境变量并额外支持OTEL_EXPORTER_OTLP_TRACES_INSECURE是否使用非安全连接与OTEL_EXPORTER_OTLP_TRACES_TIMEOUT连接超时秒数两个扩展变量。4.3 源码实现OpenTelemetrySpanStorage 如何工作OpenTelemetry 导出逻辑位于 packages/dbgpt-core/src/dbgpt/util/tracer/opentelemetry.py。OpenTelemetrySpanStorage类基于 OpenTelemetry SDK 实现创建TracerProvider并设置service.name资源属性服务名取自root_operation_name例如DB-GPT-Webserver通过OTLPSpanExporteropentelemetry.exporter.otlp.proto.grpc.trace_exporter连接otlp_endpoint并配合BatchSpanProcessor批量上报 Span当 Span 结束时将 DB-GPT 内部Span的元数据metadata逐项写入 OpenTelemetry Span 的属性attribute并设置开始/结束时间时间戳转换为纳秒从而在 Jaeger UI 中呈现完整的 DB-GPT 调用细节。这也意味着只要配置正确DB-GPT 无需任何业务代码改动即可接入任何兼容 OTLP 的可观测后端。五、Jaeger 实战单机接入 OpenTelemetry下面以 Jaeger 为例展示如何把 DB-GPT 的追踪数据导入 Jaeger 进行可视化分析。5.1 启动 Jaeger All-in-One使用 Docker 一键启动 Jaeger 全功能镜像注意开放 OTLP 所需的4317/4318端口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其中16686Jaeger Web UI 前端端口4317OTLP over gRPC 接收端口DB-GPT 默认使用4318OTLP over HTTP 接收端口6831/6832Thrift-compact / Thrift-binary UDP 端口供多数语言 SDK 使用9411Zipkin 兼容端口。5.2 配置 .env 并启动 DB-GPT按前文方式在.env中启用 OpenTelemetryTRACER_TO_OPEN_TELEMETRYTrue OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://localhost:4317然后启动 DB-GPT webserverdbgpt start webserver启动后即可通过浏览器访问 Jaeger UIhttp://localhost:16686查看 DB-GPT 上报的 Trace。5.3 Jaeger UI 界面解读接入完成后Jaeger UI 中可以看到以下几种典型视图对应仓库中docs/static/img/application/advanced_tutorial/目录下的官方截图搜索 Trace 页面Search Traces Page选择服务与时间范围按关键字/标签搜索全部 Trace普通对话 Trace展示一次常规对话从请求进入到模型返回的完整时间线与各 Span 耗时对话详情标签Conversation Detail Tags展开某个 Span 后可以看到 DB-GPT 写入的详细标签即 Span 元数据如chat_mode、model_name、user_input等运行参数Agent 对话 TraceAgent 模式下多次工具调用、模型调用的嵌套调用链RAG 对话 Trace / 集群视图RAG 场景下 controller、LLM worker 与 webserver 之间的跨服务通信链路。下图为 Jaeger 的 Trace 搜索页面下图为一次跨服务controller、LLM worker、webserver的 RAG 对话 Trace 示例可清晰看到各服务间的调用关系与耗时分布六、集群方案Docker Compose 一键启动可观测集群6.1 官方 Compose 文件解析对于生产级的多服务场景DB-GPT 官方提供了完整的 Docker Compose 示例docker/compose_examples/observability/docker-compose.yml。该文件定义了一个由Jaeger controller llm-worker embedding-worker webserver组成的、带可观测性能力的完整集群。其核心结构如下# 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 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: dbgptnet要点说明链路打通方式每个 DB-GPT 服务都设置了TRACER_TO_OPEN_TELEMETRYTrue并将OTEL_EXPORTER_OTLP_TRACES_ENDPOINT指向 Compose 网络内的 Jaeger 服务名http://jaeger:4317gRPC 协议日志级别各服务统一设置为DBGPT_LOG_LEVELDEBUG便于在集群场景下获得最详细的运行日志Jaeger 持久化通过SPAN_STORAGE_TYPEbadger与jaeger-badger数据卷持久化 Span 数据官方注释提示设置容器内 UID/GID 与宿主一致可参考:uid10001,gid10001写法依赖顺序webserver通过depends_on依赖controller、llm-worker、embedding-worker确保模型与检索服务先就绪。6.2 启动集群在仓库根目录执行cd docker/compose_examples/observability 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。若使用自定义镜像可按docker-compose.yml顶部注释说明先在仓库根目录执行bash ./docker/base/build_proxy_image.sh构建eosphorosai/dbgpt-openai:latest镜像如需指定 pip 源可追加--pip-index-url参数。集群启动完成后同样通过http://localhost:16686访问 Jaeger UI 查看 Trace。此时由于 controller、LLM worker、embedding worker、webserver 均将 Span 上报到同一个 Jaeger你可以在一次 RAG 对话的 Trace 中看到 webserver入口→ controller模型调度→ LLM worker推理→ embedding worker向量检索之间的完整跨服务调用链这正是单机模式无法观察到的集群级可观测性。七、总结与排查指引至此我们已经完整走通了 DB-GPT 可观测性的三条路径日志Logging通过DBGPT_LOG_LEVEL默认INFO支持FATAL/ERROR/WARNING/INFO/DEBUG/NOTSET与DBGPT_LOG_DIR控制日志级别与落盘位置本地 Trace默认写入logs/dbgpt*.jsonl可结合 Debugging 指南 中的dbgpt trace chat/dbgpt trace list命令离线分析调用链与运行参数分布式追踪设置TRACER_TO_OPEN_TELEMETRYTrue与OTEL_EXPORTER_OTLP_TRACES_ENDPOINT将 Span 通过 OTLP默认 gRPC 端口4317导出到 Jaeger 等后端集群部署可直接复用 observability 的 docker-compose.yml。在实际使用中如果发现 Jaeger UI 中没有数据建议按以下顺序排查确认已安装opentelemetry-api、opentelemetry-sdk、opentelemetry-exporter-otlp三个 Python 包确认.env或容器环境中的TRACER_TO_OPEN_TELEMETRYTrue是否生效注意字符串比较大小写不敏感确认OTEL_EXPORTER_OTLP_TRACES_ENDPOINT指向的协议与端口gRPC4317/ HTTP4318与后端一致容器间通信时应使用 Compose 服务名而非localhost将DBGPT_LOG_LEVEL临时调高到DEBUG观察日志中是否有 Trace 导出相关的报错。通过以上配置开发者可以在开发调试、性能分析与线上故障定位中以标准化的方式观测 DB-GPT 的每一次对话与每一层模型调用让复杂的 AI 应用系统状态变得清晰可见。【免费下载链接】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），仅供参考