btfmt

Formatter and language tooling for bpftrace.

Install · Quick start · Language features · Configuration · 中文

btfmt gives bpftrace scripts deterministic formatting and editor intelligence from one native binary. Use it as a CLI in local workflows and CI, run it as a standard LSP server, or install the platform-specific VS Code extension.

What You Get

Formatter	Language Server	VS Code
Stable indentation, spacing, braces, and line breaks	Diagnostics, hover, completion, navigation, and rename	Bundled native server, syntax highlighting, format-on-save, and language status
Comments, shebangs, and preprocessor regions preserved	Workspace-aware maps, macros, imports, and symbols	Local, Remote SSH, WSL, and Dev Container support
Multiple files, stdin, in-place writes, and CI checks	Rootless probe and args completion with graceful fallback	Restricted Mode with reduced workspace access

Install

Download the latest CLI archive or platform-specific VSIX from GitHub Releases.

Platform	CLI archive	VS Code package
Linux x64	btfmt-linux-amd64.tar.gz	btfmt-linux-x64-<version>.vsix
macOS x64	btfmt-darwin-amd64.tar.gz	btfmt-darwin-x64-<version>.vsix
macOS ARM64	btfmt-darwin-arm64.tar.gz	btfmt-darwin-arm64-<version>.vsix
Windows x64	btfmt-windows-amd64.zip	btfmt-win32-x64-<version>.vsix

Install the Linux CLI:

tar -xzf btfmt-linux-amd64.tar.gz
mkdir -p ~/.local/bin
install -m 755 btfmt ~/.local/bin/btfmt

Install the VS Code package with Extensions: Install from VSIX....

Build the CLI from source:

cargo install --locked --git https://github.com/fanyang89/bpftrace-formatter.git

Quick Start

btfmt script.bt                 # formatted output on stdout
btfmt --write script.bt         # write back atomically
btfmt --check scripts/*.bt      # non-zero when formatting differs
cat script.bt | btfmt -         # explicit stdin

Enable format-on-save in VS Code:

"[bpftrace]": {
  "editor.defaultFormatter": "fanyang89.btfmt",
  "editor.formatOnSave": true
}

Formatting example

Before:

tracepoint:syscalls:sys_enter_openat{printf("openat: %s\n",str(args.filename));}

After:

tracepoint:syscalls:sys_enter_openat
{
    printf("openat: %s\n", str(args.filename));
}

Language Features

Capability	Scope
Completion	Builtins, providers, keywords, variables, maps, macro parameters, imported macros, probe targets, and args fields
Navigation	Definitions, references, highlights, and document symbols
Rename	Lexical variables plus workspace-wide maps and macro families
Hover	Versioned bpftrace builtin documentation
Diagnostics	Syntax errors with UTF-16-correct editor ranges
Formatting	Shared CLI/LSP engine and per-workspace .btfmt.json

Probe completion never invokes sudo or runs bpftrace. It combines symbols observed in the workspace, portable event catalogs, and kernel metadata readable by the current user. Missing kernel access is a normal limited-data environment, not an error.

Configuration

Generate a complete configuration file:

btfmt --generate-config

{
  "indent": { "size": 4, "use_spaces": true },
  "blocks": { "brace_style": "next_line", "indent_statements": true }
}

See Configuration for every option, validation rule, and the distinct CLI/LSP search order.

LSP And Architecture

Start the stdio language server for any compatible editor:

btfmt lsp

flowchart LR
    CLI[btfmt CLI] --> Core[Parser + formatter]
    VSCode[VS Code client] --> LSP[btfmt lsp]
    Editor[Other LSP client] --> LSP
    LSP --> Core
    LSP --> Index[Workspace symbol index]

Loading

The parser comes from the pinned tree-sitter-bpftrace crate; generated parser sources are not vendored here.

Development

task build
task test
task ci

See AGENTS.md for repository conventions and vscode-extension/PUBLISHING.md for release operations.

Support And License

• Releases
• Issue tracker
• VS Code troubleshooting
• Unlicense