Agent Skills › rustfs/rustfs › tier-debug

tier-debug

GitHub

用于调试对象存储分层生命周期（ILM）问题，包括版本不一致、恢复失败及元数据检查。提供排查过渡元数据和远程分层的操作指南。

.agents/skills/tier-debug/SKILL.md rustfs/rustfs

Trigger Scenarios

排查 ILM 分层转换异常分析 NoSuchVersion 错误检查 xl.meta 元数据追踪远程分层 versionId

Install

npx skills add rustfs/rustfs --skill tier-debug -g -y

More Options

Non-standard path

npx skills add https://github.com/rustfs/rustfs/tree/main/.agents/skills/tier-debug -g -y

Use without installing

npx skills use rustfs/rustfs@tier-debug

指定 Agent (Claude Code)

npx skills add rustfs/rustfs --skill tier-debug -a claude-code -g -y

安装 repo 全部 skill

npx skills add rustfs/rustfs --all -g -y

预览 repo 内 skill

npx skills add rustfs/rustfs --list

SKILL.md

Frontmatter

{
    "name": "tier-debug",
    "description": "Debug ILM tiering \/ lifecycle transition issues — NoSuchVersion on tier GET, restore failures, xl.meta inspection, remote-tier versionId tracing. Use when investigating tiered\/transitioned objects, warm backends, or transition metadata."
}

Tier / ILM Debugging

Full playbook: docs/operations/tier-ilm-debugging.md — read it before changing tier code.

Quick moves:

# Inspect transition metadata on disk (one xl.meta per erasure shard disk)
cargo run -p rustfs-filemeta --example dump_fileinfo -- "/path/to/{bucket}/{object}/xl.meta"

# Trace what versionId is sent to the remote tier
RUST_LOG=rustfs_ecstore::bucket::lifecycle=debug ./target/debug/rustfs …

Interpretation:

transition_ver_id: <none> → correct for an unversioned tier bucket; no versionId must be sent on tier GET/DELETE.
transition_ver_id: 00000000-… (nil) → corrupt legacy write-back; readers must filter it out, never send it.
Empty-string transitioned-versionID metadata under both x-rustfs-internal-* and x-minio-internal-* keys → object went to an unversioned tier bucket.

Code entry points: crates/ecstore/src/bucket/lifecycle/bucket_lifecycle_ops.rs (ILM actions), crates/ecstore/src/services/tier/ (warm backends), crates/filemeta/src/filemeta/version.rs (metadata read/write + regression tests).