查看日志
日志是排查数据墙DBW 问题的首要入口。引擎将运行时信息、请求处理细节、数据库交互和错误信息输出到标准输出（stdout），也可以配置输出到文件。
日志输出位置
| 输出方式 | 配置 | 适用场景 |
|---|---|---|
| 标准输出（stdout） | 默认 | 本地开发、容器环境（docker logs / kubectl logs） |
| 文件 | runtime.telemetry.file.enabled: true | 持久化存储、离线分析 |
配置文件输出
json
{
"runtime": {
"telemetry": {
"file": {
"enabled": true,
"path": "/var/log/dab/dab-log.txt",
"rolling-interval": "Day",
"retained-file-count-limit": 7,
"file-size-limit-bytes": 10485760
}
}
}
}| 字段 | 说明 | 默认值 |
|---|---|---|
enabled | 启用文件日志 | false |
path | 日志文件路径 | /logs/dab-log.txt |
rolling-interval | 滚动间隔：Day、Hour、Minute | Day |
retained-file-count-limit | 保留文件数 | 1 |
file-size-limit-bytes | 触发滚动的大小（字节） | 1048576 |
日志级别
| 级别 | 用途 | 典型场景 |
|---|---|---|
Trace | 最详细，含方法入口/出口 | 深度问题排查 |
Debug | 调试诊断信息 | SQL 生成、查询执行 |
Information | 服务运行关键事件 | 启动完成、请求数量 |
Warning | 需关注的异常情况 | 配置弃用警告、降级行为 |
Error | 操作失败 | 数据库连接失败、权限拒绝 |
Critical | 系统级严重故障 | 进程崩溃 |
None | 完全禁用日志 | 不推荐 |
设置日志级别
启动参数（覆盖配置文件）：
bash
dab start --LogLevel Debug配置文件：
json
{
"runtime": {
"telemetry": {
"log-level": {
"default": "Warning",
"Azure.DataApiBuilder.Core": "Information"
}
}
}
}CLI：
bash
dab configure --runtime.telemetry.log-level.default "Warning"模式默认值
| 模式 | 默认日志级别 |
|---|---|
development | Debug |
production | Error |
按命名空间过滤
排查特定组件时可以只关注其日志，不影响其他组件的输出：
| 命名空间 | 排查目标 |
|---|---|
Azure.DataApiBuilder.Core.Configurations.RuntimeConfigValidator | 配置验证问题 |
Azure.DataApiBuilder.Core.Resolvers.SqlQueryEngine | SQL 查询生成 |
Azure.DataApiBuilder.Core.Resolvers.IQueryExecutor | 数据库执行和耗时 |
Azure.DataApiBuilder.Service.Controllers.RestController | REST 请求路由错误 |
Azure.DataApiBuilder.Auth.IAuthorizationResolver | 授权决策 |
Microsoft.AspNetCore.Authorization.IAuthorizationHandler | 认证管道 |
只调试 SQL 生成
json
{
"runtime": {
"telemetry": {
"log-level": {
"default": "Warning",
"Azure.DataApiBuilder.Core.Resolvers.SqlQueryEngine": "Debug"
}
}
}
}常见问题的日志特征
数据库连接失败
日志中包含：
Error: A network-related or instance-specific error occurred while establishing a connection to SQL Server诊断行动：
- 确认数据库地址、端口、用户名、密码正确。
- 用数据库原生客户端从同一网络位置测试连接。
- 检查防火墙和网络安全组规则。
权限拒绝（403）
日志中包含：
Authorization failure: The current role does not have permission to perform this action.诊断行动：
- 确认请求的最终角色名是否正确（查看
X-MS-API-ROLE头或 JWTroles声明）。 - 运行
dab configure --show-effective-permissions确认实体权限。 - 检查角色名大小写是否与配置一致。
JWT 验证失败（401）
日志中包含：
Authentication failed: The issuer is invalid. Expected 'https://idp.example.com/', received 'https://wrong-issuer/'诊断行动：
- 解码 JWT 令牌（jwt.io），对比
iss和aud与配置是否完全一致。 - 确认令牌未过期（检查
exp）。 - 确认身份提供程序的 OpenID 配置（
/.well-known/openid-configuration）可访问。
配置解析错误
日志中包含配置字段相关的错误信息。
诊断行动：
- 运行
dab validate获取详细的配置错误报告。 - 按阶段修复错误，每个阶段修复后重新运行直到退出码为 0。
生产环境日志策略
| 策略 | 建议 |
|---|---|
| 默认级别 | Warning——正常请求不输出日志，只记录异常 |
| 文件滚动 | 按日滚动，保留 7-14 天 |
| 关键命名空间 | 保持 Warning，需要时临时调整为 Information |
| 审计日志 | 结合 OpenTelemetry 将认证失败和权限拒绝发送到安全监控系统 |
| 日志存储 | 配合日志聚合系统（ELK、Loki）集中管理 |
临时开启详细日志（热重载）
修改配置文件中的日志级别后，引擎会在运行时检测并动态应用——无需重启服务。这让你可以在生产环境中临时调高某个命名空间的日志级别来排查问题，排查完毕后调回正常级别。