Metabase 故障排查指南诊断信息、日志定位与数据库性能问题的系统化解决路径【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabaseMetabase 的故障排查体系围绕“先收集信息、再分层定位、最后定向修复”展开从一键导出的诊断信息Diagnostic Info、浏览器 HAR 文件、服务器日志到 JVM 性能剖析再到数据库连接、超时与性能问题的专项排查。本文以 docs/troubleshooting-guide/index.md 为主线骨架逐层展开每类问题的检测方法与修复步骤并结合仓库源码默认日志配置、连接池设置等补充底层依据帮助你建立一套可复用的排障 SOP。故障排查的整体框架按问题域组织先取证后修复Metabase 的排障文档按“问题域”分类组织每一类都遵循“症状 → 原因 → 检测 → 修复”的闭环。整体分类如下分类覆盖问题对应指南诊断信息下载诊断 JSON、创建 HAR 文件、性能剖析diagnostic-info.md、create-har-file.md、profiling-metabase.md安装JAR 运行、Docker、H2 应用数据库running.md、docker.md、loading-from-h2.md认证无法登录、LDAP、SAMLcant-log-in.md、ldap.md、saml.md权限权限不生效、行列级安全失效permissions.md、row-and-column-security.md数据库连接失败、表缺失、数据不一致、数据库慢、超时db-connection.md、cant-see-tables.md、sync-fingerprint-scan.md、db-performance.md、timeout.md问题与仪表盘无法保存/查看/编辑、可视化错误、仪表盘慢、SQL 问题、时区错误、过滤器失效proxies.md、cant-view-or-edit.md、visualization.md、my-dashboard-is-slow.md、sql.md、timezones.md、filters.md、linked-filters.md模型模型不工作models.md邮件与告警邮件发送失败、通知异常cant-send-email.md、notifications.md错误信息界面出现报错error-message.mdBug 与功能请求已知缺陷、上报 Bug、请求新功能known-issues.md、bugs.md、requesting-new-features.md排障的第一原则是先定位问题发生层是浏览器端前端 JS、网络请求、Metabase 应用层JVM、服务器日志还是数据源层数据库服务器以下各节按这条链路依次展开。第一步收集诊断信息Diagnostic Info当你需要向他人求助或自行深挖问题时最有效的做法是导出 Metabase 的诊断信息——一个结构化的 JSON 文件。打开诊断信息弹窗在页面任意位置按下Cmd F1Mac或Ctrl F1PC或者按Cmd/Ctrl K唤起命令面板Command Palette搜索 Diagnostic选择Open diagnostic error modal。可包含的信息类型在弹窗中勾选希望写入诊断 JSON 的内容包括Item definition当前条目定义例如某个仪表盘的元数据定义Browser error messages浏览器端错误信息All server error messages全部服务器错误信息All server logs全部服务器日志Server logs from the current user only仅当前用户的服务器日志Metabase instance version information实例版本信息。需要注意Metabase 实际采集哪些数据取决于你发起诊断时所在的页面例如在某个仪表盘页发起才会包含该仪表盘的定义。⚠️ 分享诊断文件前务必先检查内容因为诊断信息可能包含敏感数据会话、凭据、用户信息等。服务器日志与控制台日志的获取Metabase 会在服务器与浏览器控制台两侧分别记录错误取决于错误发生在哪一层服务器日志管理员可在界面右上角点击网格图标 Admin Tools Logs新版界面位于Monitor Application logs查看自托管部署时也可直接在运行 Metabase 的终端中查看。读取方法见 server-logs.md。浏览器控制台Metabase 会将调试信息与错误输出到浏览器开发者工具控制台任何用户都可以按浏览器对应方式打开开发者工具查看Chrome/Edge 的 DevTools、Firefox 的 Web Console、Safari 的 Web Inspector。HAR 文件浏览器记录的完整网络请求日志详见下文。第二步读懂 Metabase 服务器日志日志是排障的核心证据。下面是一条真实风格的查询请求日志出自 server-logs.md2021-07-07 15:53:18,560 DEBUG middleware.log :: POST /api/dataset 202 [ASYNC: completed] 46.9 ms (17 DB calls) App DB connections: 1/10 Jetty threads: 3/50 (4 idle, 0 queued) (72 total active threads) Queries in flight: 0 (0 queued); h2 DB 4 connections: 0/1 (0 threads blocked)逐字段拆解如下字段示例值含义日志时间2021-07-07 15:53:18,560日志产生的时间戳日志级别DEBUG不同级别对应不同信息量详见 application-logs.md命名空间middleware.log日志来源模块可通过调整日志级别获取该模块更多/更少信息HTTP 方法POSTPOST、PUT、GET、DELETE 等请求动词路径/api/dataset处理的 URL。注意不包含 URL 参数这可能增加定位问题的难度状态码202HTTP 响应状态码ASYNC 状态[ASYNC: completed]Metabase 是否成功把结果投递给浏览器若用户在查询完成前关闭浏览器则显示cancelled响应时间46.9 msMetabase 从收到请求到返回结果给浏览器的耗时数据库调用数(17 DB calls)执行的查询语句数量包含对数据源的调用和对 Metabase 应用数据库的调用应用数据库连接App DB connections: 1/10当前活跃连接数与连接池总容量Jetty 线程Jetty threads: 3/50 (4 idle, 0 queued)活跃线程数/线程池总量括号内为空闲热线程数与排队线程数。若线程池被打满说明并发压力过大需要扩容部署Java 线程(72 total active threads)Metabase 使用的线程总数进行中查询Queries in flight: 0 (0 queued)跨所有数据源的活跃与排队查询数数据库信息h2 DB 4 connections: 0/1 (0 threads blocked)与本次请求相关的数据库类型、数据库 ID、活跃/池容量连接数与阻塞线程数区别于全局 Queries in flight从源码看默认日志配置Metabase 使用 Log4j 2 作为日志框架仓库根目录的 resources/log4j2.xml 是默认配置其中关键的 Logger 设置如下与文档中的自定义示例一致Loggers Logger namecom.mchange levelERROR/ Logger nameliquibase levelINFO/ Logger namemetabase levelINFO/ Logger namemetabase-enterprise levelINFO/ Logger namemetabase.metabot levelDEBUG/ Logger namemetabase.plugins levelDEBUG/ Logger namemetabase.query-processor.async levelDEBUG/ Logger namemetabase.server.middleware levelDEBUG/ Logger nameorg.quartz levelINFO/ Root levelWARN AppenderRef refSTDOUT/ /Root /Loggers从源码可见metabase与metabase-enterprise默认 INFOmetabase.plugins、metabase.query-processor.async、metabase.server.middleware默认 DEBUGcom.mchangec3p0 连接池默认 ERROR。测试环境另有 test_config/log4j2-test.xml 可供参考。临时调整日志级别无需重启在Monitor Application logs页面点击Customize log levels可选用常用排障预设或直接以 JSON 提交自定义配置。例如排查联动过滤器linked filters问题时可以临时提高以下命名空间的日志级别{ metabase.parameters.chain-filter: debug, metabase.parameters.chain-filter.dedupe-joins: debug }该覆盖是临时的可以指定生效时长如 60 分钟超时后自动回退到默认配置或你自定义的 log4j2 文件。使用自定义 log4j 配置文件复制一份默认的 resources/log4j2.xml按需调整各 Logger 的级别。例如打开同步/指纹/扫描相关的 TRACE 日志Logger namemetabase.sync levelTRACE/重启 Metabase 并指向自定义文件Docker 方式通过JAVA_OPTS注入docker run -p 3000:3000 -v $PWD/my_log4j2.xml:/tmp/my_log4j2.xml -e JAVA_OPTS-Dlog4j.configurationFilefile:/tmp/my_log4j2.xml metabase/metabaseJAR 方式通过-Dlog4j.configurationFile参数java -Dlog4j.configurationFilefile:/path/to/custom/log4j2.xml -jar metabase.jar开启 Jetty 调试日志与日志显示控制若需查看 Web 服务器Jetty的详细日志在Loggers节点中增加Logger nameorg.eclipse.jetty levelDEBUG/。注意 Jetty 的 DEBUG 日志非常冗长可能反而干扰定位。默认日志会包含 emoji 与颜色输出可通过环境变量关闭export MB_EMOJI_IN_LOGSfalse export MB_COLORIZE_LOGSfalse java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar相关环境变量的完整说明见 environment-variables.md。第三步创建 HAR 文件定位性能与网络问题HARHTTP Archive文件记录了浏览器产生的全部网络请求适合排查 Metabase 的性能问题与请求链路异常。⚠️ 录制 HAR 会包含敏感信息会话 Cookie、认证信息等。仅在明确要求且确需诊断会话/认证类问题时录制分享前务必用文本编辑器检查文件内容。Chrome 与 Edge 中的录制步骤打开开发者工具页面任意位置右键 →Inspect切换到Network标签网络日志自动开始录制点击开发者工具顶栏的齿轮图标进入设置在Network区域勾选Allow to generate HAR files with sensitive data保持 Network 标签页打开并处于录制状态复现问题复现完成后点击标签栏下方工具栏最右侧的下载图标选择Export HAR (with sensitive data)…保存文件。Firefox 中的录制步骤打开开发者工具右键 →Inspect切换到Network标签在录制状态下复现问题在网络请求列表任意位置右键选择Save All As HAR。Safari 中的录制步骤若未开启开发者菜单Safari 设置 高级勾选Show features for web developers通过开发 显示 Web 检查器或右键 →检查元素打开开发者工具切换到Network标签自动开始录制复现问题点击 Network 标签右上角的Export。HAR 文件与服务器日志、诊断 JSON 组合使用可以覆盖“浏览器发起请求 → Metabase 处理 → 数据库响应”的完整链路。第四步内存与 JVM 问题排查Metabase 以 JAR 形式运行在 JVM 上因此 JVM 与文件系统的异常都会阻止其正常运行详见 running.md。Java 版本要求当前仓库要求的运行版本为Java 25更旧版本不受支持且应选择所选主版本号下的最新次版本。官方建议单台服务器只运行一个 Java 版本若多个应用需要不同 Java 版本优先使用容器隔离。区分 Metabase 内存与 JVM 内存JVM 会恒定占用约机器内存的1/4可通过参数调整Metabase 只使用 JVM 分配到的这部分内存并会释放不再使用的部分但 JVM 不会把空闲内存归还给操作系统因此从机器视角看 JVM 始终占用那份固定内存。例如一台 8 GB 内存的机器JVM 默认占用约 2 GBMetabase 只在这 2 GB 内活动但机器侧看到的内存占用始终是 2 GB。两个典型内存红旗java.lang.OutOfMemoryError: Java heap space常见于共享主机等无法正确探测可用内存的环境解决办法是增大 JVM 堆内存见下。内存使用随时间呈锯齿状sawtoothMetabase 快速消耗内存 → 触发垃圾回收GC→ 释放 → 再快速消耗循环往复。频繁 GC 会占用大量 CPU 拖慢应用。可通过 Prometheus 指标jvm_memory_bytes_used{areaheap}观察监控接入方式见 observability-with-prometheus.md。增大 JVM 堆内存使用-X系列参数以 2 GB 为例java -Xmx2g -jar metabase.jar经验法则为机器上其他进程至少预留 12 GB 内存例如 2 GB 内存机器设-Xmx1g4 GB 机器设-Xmx2g。Docker 场景下通过JAVA_OPTS注入docker run -d -p 3000:3000 -e JAVA_OPTS-Xmx2g metabase/metabase在 OOM 时自动导出堆转储Heap Dump如果实例运行一段时间后才 OOM可能是某个具体事件如大查询触发。可在启动参数中启用 OOM 时的堆转储java -Xmx2g -XX:HeapDumpOnOutOfMemoryError -XX:HeapDumpPath/path/to/a/directory -jar metabase-jar-XX:HeapDumpPath指定 hprof 文件输出目录默认当前目录hprof 文件可能和-Xmx一样大请确保磁盘空间充足可用 JDK 自带的jhat或 Eclipse Memory Analyzer ToolMAT分析。两个可忽略的告警WARNING: sun.reflect.Reflection.getCallerClass is not supported. This will impact performance.此警告可以安全忽略Metabase 运行正常若遇到文件读写权限类 IOError如无法读取 SQLite 数据库或自定义 GeoJSON 地图文件参考 docker.md 中“Metabase cant read to/from a file or directory”一节。第五步使用 JMX 与 VisualVM 剖析运行中的 Metabase对于“内存吃紧”“实例卡死”“响应缓慢”这类性能问题JVM 自带的 JMX 监控 VisualVM 是最直接的剖析手段详见 profiling-metabase.md。前置条件本地安装 VisualVM它随 OpenJDK 与 Oracle JDK 附带位于 JDK 安装目录的bin下部分 Linux 发行版将其独立为visualvm包。连接本地 Metabase如果 VisualVM 与 Metabase 在同一台机器上这是最省事的方式——无需任何远程通信配置正常启动 Metabase再单独启动 VisualVM 即可看到本地进程连接远程 Metabase含 Docker 容器远程监控包括本地 Docker 容器内的实例需要给 JVM 指定 JMX 系统属性。以 JAR 方式运行为例将原命令java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar改为java --add-to-startjmx,jmx-remote \ -Dcom.sun.management.jmxremote \ -Dcom.sun.management.jmxremote.port1099 \ -Dcom.sun.management.jmxremote.rmi.port1099 \ -Dcom.sun.management.jmxremote.authenticatefalse \ -Dcom.sun.management.jmxremote.sslfalse \ -Dcom.sun.management.jmxremote.local.onlyfalse \ -Djava.rmi.server.hostnameMetabase Hostname \ -jar metabase.jar端口1099是常见的 RMI/JMX 端口可换成任意可访问端口。注意上述命令将实例开放给任何可访问者监控仅应在受信网络环境中短时使用如需加固连接参见 Oracle 官方 JMX 管理文档。Docker 容器场景将 JMX 属性写入环境变量文件metabase-vars.envJAVA_OPTS-Dcom.sun.management.jmxremote.port1099 -Dcom.sun.management.jmxremote.rmi.port1099 -Dcom.sun.management.jmxremote.authenticatefalse -Dcom.sun.management.jmxremote.sslfalse -Dcom.sun.management.jmxremote.local.onlyfalse -Djava.rmi.server.hostnameMetabase Hostname文件要求每行一个环境变量、无多余换行然后通过--env-file注入并暴露 JMX 端口docker run --env-filemetabase-vars.env -d -p 3000:3000 -p 1099:1099 -h Metabase Hostname --name metabase metabase/metabase之后在 VisualVM 中右键Add Remote Host添加远程主机 → 填入上述 hostname → 右键该主机Add JMX connection填入端口1099→ 双击打开远程 JMX 进程Docker 场景下端口需与系统属性及映射端口一致。Heap Dump 与 Thread Dump连接成功后VisualVM 会暴露大量运行时信息其中两个最有价值Heap Dump堆转储在 Monitor 标签页生成快照当前时刻堆中所有对象可用 Eclipse MAT 等工具事后分析“内存被什么占用了”Thread Dump线程转储在 Threads 标签页采集展示每个线程在特定时刻正在执行什么、被什么阻塞。当 Metabase 看起来卡死或缓慢时线程转储能直接指出阻塞点第六步数据库连接问题的排查与修复连接数据库失败时核心任务是判断问题出在Metabase 侧还是数据库服务器侧详见 db-connection.md。先检查 Metabase 侧进入Admin Databases选中目标数据库确认连接配置没有被改动或删除若未开始同步点击Sync database schema若同步耗时过长参考 sync-fingerprint-scan.md。进入Admin Tools Logs检查是否因报错导致同步失败日志读取见上文若你没有 Admin 权限需要联系 Metabase 的搭建者。再检查数据库服务器侧确认数据仓库服务正在运行托管服务看控制台状态有 CLI 则登录执行查询验证用运行 Metabase 的机器通过其他客户端测试连通性若通过堡垒机可访问但 Metabase 不行检查 Metabase 的 IP 是否有权访问数据库Metabase Cloud 用户需确认已将 Metabase 的 IP 加入白名单确认 Metabase 使用的数据库角色具备所需权限参考 users-roles-privileges.md 授权。常见数据库连接错误“Your question took too long”界面出现该提示时按 timeout.md 排查超时问题。“Connections cannot be acquired from the underlying database”在日志中发现该错误时进入Admin Databases选中目标数据库在Advanced options Additional JDBC connection string options中添加trustServerCertificatetrue点击Save。 另外注意Metabase 版本必须支持对应数据库版本例如早于 46 的版本不支持 Microsoft SQL Server 2022。逐层验证连通性检查端口连通以默认 PostgreSQL 5432 端口为例nc -v your-db-host 5432验证凭据数据库名或用户/密码错误会报错psql -h HOSTNAME -p PORT -d DATABASENAME -U DATABASEUSER在 Metabase 内测试连接打开 SQL 编辑器执行SELECT 1Snowflake 走 JAR 运行时的特殊处理若连接 Snowflake 报JDBC driver internal error: exception creating result且以 JAR 方式运行需要在java命令中加入java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar完整的 JAR 运行说明见 running-the-metabase-jar-file.md。第七步数据库性能、超时与连接池调优数据库本身的性能问题同样有系统化的排查路径详见 db-performance.md。识别瓶颈可选用 Usage Analytics 查看使用统计Pro/Enterprise 计划可用查看数据库服务器日志确认是否存在表规模增长、Metabase 使用人数/频率上升、其他脚本或应用频繁访问数据库对高频查询的表优化表结构关键对照实验在 Metabase 中跑一个问题再对数据库直接执行同一查询两者耗时接近 → 数据量或使用模式超过了数据库能力需要给数据库扩容Metabase 中明显更慢 → 问题在 Metabase 应用层部署需要考虑横向扩展。若脚本或第三方应用高频打库停止脚本并清理排队查询给脚本加超时、安排在非高峰时段运行或对数据库做副本并将工具指向副本。重置数据库连接“重启大法”进入Admin Databases 目标数据库不做任何修改直接点击Save changes即可重置 Metabase 与该数据库的连接备选直接从数据库侧杀掉连接。一般 Metabase 会在挂起连接超时 10 分钟后、再 20 分钟后尝试关闭若数据库不响应可能需要从数据库侧主动关闭到 Metabase 的连接。清除排队查询当有人/某程序一次性发起大量查询如一个卡片过多的仪表盘查询“雪崩”会占满 Metabase 与数据库之间的所有连接导致新查询无法执行且排队速度超过数据库消化速度。处理方式停止引发查询的进程到数据库服务器上停止所有进行中的来自 Metabase 的查询可选调大MB_JDBC_DATA_WAREHOUSE_MAX_CONNECTION_POOL_SIZE连接池上限。从源码看该设置定义在 src/metabase/driver/settings.clj底层对应 c3p0 连接池默认值为 15文档提示当连接全部被占用时Metabase 处理查询会变慢需要等待可用连接。同文件还定义了jdbc-data-warehouse-connection-pool-checkout-timeout-ms默认0即无限等待与jdbc-data-warehouse-connection-pool-max-pending-checkouts默认0即无界排队两者可配合使用设置正数后池满时的额外查询会以 HTTP 503 快速失败而不是无限排队——这对防止查询雪崩拖垮实例非常有价值。其他性能优化项重新安排或禁用同步/扫描Metabase 默认定期对数据库执行 sync/scan 以刷新表、筛选下拉值与建议。大数据库场景可改为手动触发见 sync-scan.md。修正列的数据类型数字、日期、时间戳被存成字符串时Metabase 生成的查询会要求数据库实时转换性能差。在数据库层修正 schema 类型并同步进 Metabase 即可提速。连接与查询超时Timeout排查超时问题的来源可能是数据库连接、负载均衡器、反向代理如 Nginx、Jetty、云服务。定位思路是按链路逐层检查详见 timeout.mdJetty 连接器配置Jetty 官方协议/连接器文档云平台的相关超时治理如 AWS EC2 连接排障、ELB 空闲超时控制、Google App Engine 的 DeadlineExceededError 处理。第八步认证、权限、模型、邮件等其他问题域的快速入口登录问题无法登录时优先重置密码managing.md 中的“重置某人的密码”与“重置管理员密码”小节确认站点 URL 设置settings.md与账号是否被停用注意 Metabase Cloud 的商店账号密码与实例登录密码是两回事。SAML/LDAP 场景分别见 saml.md 与 ldap.md。权限问题权限不生效参考 permissions.md行列级安全失效参考 row-and-column-security.md。表缺失连接成功但数据浏览器看不到表参考 cant-see-tables.md数据与数据库不一致则看 sync-fingerprint-scan.md。问题/仪表盘问题保存失败看 proxies.md无法查看/编辑看 cant-view-or-edit.md可视化错误看 visualization.md仪表盘缓慢看 my-dashboard-is-slow.mdSQL 问题看 sql.md日期时间错乱看 timezones.md过滤器失效看 filters.md 与 linked-filters.md。模型问题参考 models.md。邮件与告警邮件发不出看 cant-send-email.md通知类问题看 notifications.md。界面报错参考 error-message.md。第九步已知 Bug、产品限制与升级如果上述指南都解决不了很可能遇到了团队已知的 Bug 或产品限制详见 known-issues.md查找已知 Bug进入 Metabase 的 GitHub issues 页面在Label下拉中选择Type: Bug升级后出现的问题可叠加.Regression标签并结合功能关键词搜索按 排序可看到最常被遇到的 Bug若命中已有 issue点 帮助团队排定优先级。查找产品限制在 Label 中选择Type: New Feature搜索——如果功能“从来就不存在”那多半是产品限制而非回归缺陷。上报新 Bug / 请求新功能确认既非已知 Bug 也非产品限制后按 bugs.md 提交 Bug 报告或按 requesting-new-features.md 提交功能请求。最后也是最值得一试的“万能药”是升级Metabase 每个版本都会新增功能并修复 Bug。升级指南见 upgrading-metabase.mdMetabase Cloud 用户则由官方自动完成升级。自托管用户可以先查看当前版本的发布说明确认是否已有针对所遇问题的修复再决定是否升级。小结一套可复用的排障流程结合以上内容完整的 Metabase 排障流程可以归纳为五步取证按Cmd/Ctrl F1导出诊断 JSON按需录制 HAR 文件同时收集服务器日志与浏览器控制台错误读懂日志对照“时间/级别/命名空间/路径/状态码/ASYNC/响应时间/DB calls/连接池/线程/Queries in flight”逐字段分析必要时用 Monitor Application logs 临时调整日志级别分层定位判断问题在浏览器端、Metabase 应用层JVM 内存、Jetty 线程、连接池还是数据源层数据库服务器、网络、权限定向修复连接问题用nc/psql/SELECT 1逐层验证性能问题用 VisualVM 做 Heap/Thread Dump、按 db-performance.md 排查瓶颈并调优连接池内存问题调整-Xmx与堆转储参数求助闭环仍无法解决时检索已知 Bug/产品限制必要时提交 Bug 报告或直接升级到最新版本。每个分类的详细步骤均可从 index.md 一键直达配合仓库内的 默认日志配置 与 连接池源码定义 深入理解底层行为即可建立起对 Metabase 排障的完整心智模型。【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考