*Redis DEBUG 命令

DEBUG 命令是 Redis 的内部调试工具，主要用于开发、测试和故障排查。大多数子命令具有破坏性或不稳定性，仅应在测试环境或明确知道后果的情况下使用。

*语法

DEBUG HELP
DEBUG OBJECT key
DEBUG SEGFAULT
DEBUG OOM
DEBUG RELOAD [NO-STATS]
DEBUG LOG message

*参数说明

参数 类型 必填 说明
HELP Subcommand 否 返回子命令帮助信息
OBJECT Subcommand 是 返回指定 key 的详细内部调试信息
SEGFAULT Subcommand 是 故意触发段错误，导致 Redis 进程崩溃
OOM Subcommand 是 故意触发内存不足，导致 Redis 进程退出
RELOAD Subcommand 是 保存并重新加载 RDB 文件，用于测试持久化
NO-STATS Flag 否（RELOAD 时） 重新加载后不重置统计信息
LOG Subcommand 是 将自定义消息写入 Redis 日志
key String 是（OBJECT 时） 要调试的键名
message String 是（LOG 时） 要写入日志的消息内容

*返回值

  • DEBUG HELP：返回 Array，包含所有子命令的说明文本
  • DEBUG OBJECT key：返回 String，包含 key 的详细内部调试信息（编码、引用计数、序列化长度、lru、lfu 等）
  • DEBUG SEGFAULT：不返回，直接触发段错误导致进程崩溃
  • DEBUG OOM：不返回，直接触发 OOM 导致进程退出
  • DEBUG RELOAD：返回 OK，表示重新加载完成；如果失败返回错误信息
  • DEBUG LOG message：返回 OK

*时间复杂度

  • DEBUG HELP：O(1) - DEBUG OBJECT key：O(1) - DEBUG SEGFAULT：O(1)（但会导致进程崩溃）
  • DEBUG OOM：O(1)（但会导致进程退出）
  • DEBUG RELOAD：O(N)，N 为数据库中 key 的数量（执行 RDB 保存和加载）
  • DEBUG LOG：O(1) ---

*示例

*查看对象调试信息

> SET mykey "hello world"
OK
> DEBUG OBJECT mykey
"Value at:0x7f8b4c0b8000 refcount:1 encoding:raw serializedlength:11 lru:15378242 lru_seconds_idle:0"

> HSET myhash field1 "value1"
1
> DEBUG OBJECT myhash
"Value at:0x7f8b4c0b9000 refcount:1 encoding:ziplist serializedlength:27 lru:15378242 lru_seconds_idle:0"

*写入调试日志

> DEBUG LOG "Starting custom operation"
OK

*查看帮助

> DEBUG HELP
1) "DEBUG <subcommand> [<arg> [value] [opt ...]]. Subcommands:"
2) "HELP -- Print this help."
3) "OBJECT <key> -- Show low-level info about key."
4) "SEGFAULT -- Simulate a crash."
5) "OOM -- Simulate an out-of-memory error."
6) "RELOAD [NO-STATS] -- Save and reload RDB."
7) "LOG <message> -- Write message to the server log."

*危险操作（仅在测试环境使用）

> DEBUG SEGFAULT
# 服务器进程崩溃，连接断开

> DEBUG OOM
# 服务器进程退出，连接断开

> DEBUG RELOAD
OK
> DEBUG RELOAD NO-STATS
OK

*常见错误

错误 原因 解决
ERR syntax error 使用了不存在的子命令 检查子命令拼写，使用 DEBUG HELP 查看可用命令
ERR key not found key 不存在（OBJECT 时） 确认 key 存在后再查询，或使用 EXISTS 检查
ERR Not valid DEBUG subcommand 子命令不存在 使用 DEBUG HELP 查看可用子命令
连接断开 执行了 DEBUG SEGFAULT 或 DEBUG OOM 这是预期行为，重新启动 Redis 服务器
ERR Cannot save to RDB RDB 文件权限不足或磁盘满（RELOAD 时） 检查磁盘空间和文件权限

*最佳实践

  • ⚠️ 警告：DEBUG SEGFAULT 和 DEBUG OOM 是破坏性操作，会直接导致 Redis 进程崩溃或退出，绝对禁止在生产环境使用
  • DEBUG OBJECT 是分析对象内部状态的有效工具，比 OBJECT 命令提供更详细的调试信息（如序列化长度、内存地址），但仅在需要深入排查时使用
  • DEBUG RELOAD 用于测试持久化流程：保存当前数据到 RDB 并重新加载，可用于验证 RDB 文件的正确性和加载速度。NO-STATS 选项保留统计信息，适合对比持久化前后的性能指标
  • DEBUG LOG 适合在 Lua 脚本或测试流程中插入标记日志，便于追踪执行流程
  • 生产环境：除 DEBUG OBJECT 和 DEBUG LOG 外，其他子命令应避免使用。DEBUG OBJECT 是安全的只读操作，但返回的信息主要用于内部调试，普通用户可能不需要理解所有字段

*FAQ

Q1: DEBUG OBJECT 和 OBJECT 命令有什么区别？ A: DEBUG OBJECT 提供更详细的内部调试信息，包括内存地址、序列化长度、lru/lfu 时间戳等；OBJECT 命令提供更简洁的元信息，适合日常查询。DEBUG OBJECT 的输出格式不稳定，可能随版本变化。

Q2: DEBUG SEGFAULT 有什么用？ A: 用于测试 Redis 的崩溃恢复机制（如 systemd 自动重启、哨兵监控）。它会故意触发段错误，导致进程崩溃。仅在测试环境使用。

Q3: DEBUG RELOAD 会丢失数据吗？ A: 不会。它会先执行 BGSAVE 保存当前数据到 RDB，然后清空内存并重新加载 RDB。如果持久化配置正常，数据不会丢失。但如果 RDB 文件损坏或加载失败，数据可能丢失。

Q4: DEBUG OBJECT 返回的 serializedlength 是什么？ A: 是该 key 被序列化为 RDB 格式时的字节长度。这通常比实际内存占用小，因为 RDB 格式是压缩的。它可以帮助评估该 key 持久化时的大小。

Q5: 为什么 DEBUG OBJECT 在集群模式下不可用？ A: 在集群模式下，出于安全考虑，DEBUG OBJECT 通常被禁用。因为集群模式下一个节点的问题可能影响整个集群。需要在 redis.conf 中启用 enable-debug-command 配置才能使用。

Q6: DEBUG OBJECT 返回的 lru 和 lru_seconds_idle 是什么意思？ A: lru 是 Redis 内部使用的 LRU 时钟计数器（一个 24 位整数），lru_seconds_idle 是从上次访问以来的秒数。这两个字段仅在 maxmemory-policy 使用 LRU 策略时有意义。

*相关命令