systemtap笔记

#!/usr/bin/env perl
# 使用环境中的perl解释器执行此脚本

# 启用严格模式和警告，提高代码质量和安全性
use strict;
use warnings;

# 导入必要的Perl模块
use Getopt::Long qw( GetOptions :config no_ignore_case); # 命令行参数解析，保持大小写敏感
use File::Spec (); # 跨平台文件路径处理
use File::Temp qw( tempdir ); # 临时目录创建与管理
use FindBin (); # 获取脚本所在目录路径

# 前向声明shell参数引用函数
sub quote_sh_args ($);

# 解析命令行参数
GetOptions("D=s@",          \(my $D_opts),      # 预处理器宏定义，如 -DMAXACTION=100000
           "c=s",           \(my $shcmd),       # 执行命令并在命令结束后退出
           "d=s@",          \(my $d_opts),      # 加载指定对象的调试信息
           "arg=s%",        \(my $args),        # 用户自定义参数，用于 $^arg_NAME 变量
           "args",          \(my $print_args),  # 打印所有可用的 --arg 参数
           "dump-src",      \(my $dump_src),    # 输出生成的脚本源码
           "sample-pid=i",  \(my $sample_pid),  # 采样进程以检查DSO对象
           "exec=s",        \(my $exec_path),   # 指定要跟踪的可执行文件路径
           "help",          \(my $help),        # 显示帮助信息
           "master=i",      \(my $master_pid),  # 指定主进程ID，跟踪其所有子进程
           "x=i",           \(my $pid),         # 设置目标进程ID
           "e=s",           \(my $src),         # 直接运行给定脚本
           "v",             \(my $verbose),     # 详细输出模式
           "skip-badvars",  \(my $skip_badvars), # 跳过无效变量
           "I=s@",          \(my $Inc))         # 指定stap++库搜索目录
   or die usage();  # 参数解析失败时显示用法并退出

# 添加默认的tapset库搜索路径：当前目录和脚本所在目录下的tapset子目录
push @$Inc, '.', "$FindBin::Bin/tapset";

# 操作系统兼容性检查
if ($^O ne 'linux') {
    die "Only linux is supported but I am on $^O.\n";  # 仅支持Linux系统
}

# 参数冲突检查：--args和--arg不能同时使用
if ($print_args && $args && %$args) {
    die "No --arg is allowed when --args is specified.\n";
}

# 检查SystemTap是否已安装并获取版本信息
my $ver = `stap -V 2>&1`;
if (!defined $ver) {
    die "Systemtap not installed or its \"stap\" utility is not visible to the PATH environment: $!\n";
}

# 解析SystemTap版本并检查最低版本要求
if ($ver =~ /version\s+(\d+\.\d+)/i) {
    my $v = $1;
    my $min_ver = 2.3;  # 最低要求版本2.3
    if ($v < $min_ver) {
        die "ERROR: at least systemtap $min_ver is required but found $v\n";
    }
} else {
    die "ERROR: unknown version of systemtap:\n$ver\n";
}

# 如果指定了--help参数，显示帮助信息并退出
if ($help) {
    print usage();
    exit;
}

# 处理预处理器宏定义
my %set_D_opts;
for my $opt (@$D_opts) {
    # 记录已设置的宏名称
    if ($opt =~ /^([_A-Z]+)=/) {
        $set_D_opts{$1} = 1;
    }
}

# 设置默认的性能安全参数（如果用户未指定）
if (!$set_D_opts{MAXACTION}) {
    push @$D_opts, "MAXACTION=100000";  # 限制单个探针最大执行次数
}

if (!$set_D_opts{MAXMAPENTRIES}) {
    push @$D_opts, "MAXMAPENTRIES=5000";  # 限制哈希表最大条目数
}

if (!$set_D_opts{MAXBACKTRACE}) {
    push @$D_opts, "MAXBACKTRACE=200";  # 限制调用栈最大深度
}

# 处理输入源：文件或直接脚本
my $infile;
if (!defined $src) {
    # 从命令行获取输入文件
    $infile = shift
        or die "No input file specified.\n";
    
    # 读取源文件内容
    $src = read_src_file($infile);
} else {
    # 使用-e参数直接提供的脚本内容
    $infile = "-e";
}

# 初始化全局数据结构
my (%StdVars,     # 标准变量存储
    %UsedLibs,    # 已使用的库文件
    %DSOs,        # 动态共享对象路径
    %LibPaths,    # 库文件路径缓存
    %UsedStdVars  # 已使用的标准变量跟踪
);

# 构建stap命令行参数数组
my @stap_opts;

# 添加详细输出选项
if ($verbose) {
    push @stap_opts, "-v";
}

# 添加调试对象选项
if ($d_opts) {
    for my $opt (@$d_opts) {
        push @stap_opts, '-d', $opt;
    }
}

# 添加跳过无效变量选项
if (defined $skip_badvars) {
    push @stap_opts, "--skip-badvars";
}

# 添加预处理器宏定义
for my $opt (@$D_opts) {
    push @stap_opts, "-D$opt";
}

# 处理通过 --exec 参数指定的可执行文件
if (defined $exec_path) {
    # 检查可执行文件是否存在
    if (!-f $exec_path) {
        die "$exec_path not found.\n";
    }

    # 设置标准变量 exec_path 并添加调试信息
    $StdVars{exec_path} = $exec_path;
    push @stap_opts, '-d', $exec_path;

    # 使用 ldd 命令获取可执行文件的动态库依赖
    open my $in, "ldd $exec_path|"
        or die "cannot run the command \"ldd $exec_path\": $!\n";
    while (<$in>) {
        # 匹配动态库路径（如 /lib64/libc.so.6）
        if (m{\s+(\/\S+\.so(?:\.\d+)*)}) {
            my $path = $1;
            #warn "Found DSO $path.\n";
            $DSOs{$path} = 1;  # 记录到动态库哈希表中
        }
    }

    # 为所有发现的动态库添加调试信息选项
    for my $path (sort keys %DSOs) {
        push @stap_opts, '-d', $path;
    }

    close $in;
}

# 处理通过 -x 参数指定的目标进程
if (defined $pid) {
    # 检查是否与 --master 参数冲突
    if (defined $master_pid) {
        die "-x <pid> and --master <pid> are exclusive.\n";
    }

    # 添加 stap 的 -x 选项
    push @stap_opts, "-x", $pid;
        
        # 获取进程的可执行文件路径
        my $exec_file = "/proc/$pid/exe";
        if (!-f $exec_file) {
            die "Nginx process $pid is not running or ",
                "you do not have enough permissions.\n";
        }

        # 设置进程过滤条件和目标标识
        $StdVars{pid_ok} = gen_pid_test_condition();  # 生成 pid 过滤表达式
        $StdVars{target} = $pid;

        # 如果未指定可执行文件路径，则从进程信息中获取
        if (!defined $exec_path) {
            $exec_path = readlink $exec_file;  # 解析符号链接获取真实路径
            $StdVars{exec_path} = $exec_path;
            push @stap_opts, "-d", $exec_path;
        }

        # 处理进程加载的动态库
        process_dso($pid);
}

# 处理通过 --master 参数指定的主进程（用于跟踪其所有子进程）
if (defined $master_pid) {
#push @stap_opts, "-x", $master_pid;  # 注释掉的代码，不直接跟踪主进程
    
    # 获取主进程的可执行文件路径
    my $exec_file = "/proc/$master_pid/exe";
    if (!-f $exec_file) {
        die "Nginx process $master_pid is not running or ",
            "you do not have enough permissions.\n";
    }

    # 如果未指定可执行文件路径，则从主进程信息中获取
    if (!defined $exec_path) {
        $exec_path = readlink $exec_file;
        $StdVars{exec_path} = $exec_path;
        push @stap_opts, "-d", $exec_path;
    }

    # 获取主进程的所有子进程
    my @pids = get_child_processes($master_pid);
    if (@pids == 0) {
        die "No child processes found for $master_pid.\n";
    }

    # 生成包含所有子进程的过滤条件
    $StdVars{pid_ok} = gen_pid_test_condition(\@pids);
    $StdVars{target} = "@pids";  # 将所有子进程ID作为空格分隔的字符串

    # 使用第一个子进程来处理动态库依赖
    my $pid = $pids[0];
    process_dso($pid);
}

# 处理通过 --sample-pid 参数指定的采样进程
if ($sample_pid) {
    process_dso($sample_pid);  # 仅用于获取动态库信息，不跟踪该进程
}

# 如果未设置进程过滤条件但指定了可执行文件，则设置默认值
if (!defined $StdVars{pid_ok} && defined $exec_path) {
    $StdVars{pid_ok} = '1';  # 允许所有进程
}

# 如果未设置目标标识但指定了可执行文件，则设置默认值
if (!defined $StdVars{target} && defined $exec_path) {
    $StdVars{target} = 'ANY';  # 表示任意进程
}

# 处理用户自定义参数（--arg 选项）
if (!$print_args) {
    while (my ($k, $v) = each %$args) {
        #warn "getting $k => $v";
        $StdVars{"arg_$k"} = $v;  # 将参数存储为 arg_NAME 格式的标准变量
    }
}

# 初始化用于收集脚本中使用的参数信息
my %used_args;

# 处理源代码并生成最终的 SystemTap 脚本
my $stap_src = process_src($infile, $src);
if ($dump_src) {
    print $stap_src;  # 如果指定了 --dump-src 选项，则输出处理后的脚本内容
    exit;  # 输出后退出程序
}

# 处理 --args 选项：显示脚本中使用的所有参数
if ($print_args) {
    for my $name (sort keys %used_args) {
        my $default = $used_args{$name};  # 获取参数的默认值
        print "\t--arg $name=VALUE";  # 打印参数名称
        if (defined $default) {
            print " (default: $default)\n";  # 如果有默认值，显示默认值
        } else {
            print "\n";  # 没有默认值则只换行
        }
    }
    exit;  # 显示参数后退出程序
}

# 检查未使用的参数并发出警告
for my $key (keys %$args) {
    if (!$UsedStdVars{"arg_$key"}) {  # 检查参数是否在脚本中被使用
        my $val = $args->{$key};
        if (!defined $val) {
            $val = '';
        }
        warn "WARNING: \$^arg_$key is defined by \"--arg $key=$val\", "
             ."but never used.\n";  # 警告用户定义了未使用的参数
    }
}

# 创建临时目录用于存放处理后的库文件
my $tmpdir = tempdir("stapxx-XXXXXXXX", CLEANUP => 1);  # 创建自动清理的临时目录
while (my ($lib, $src) = each %UsedLibs) {
    my $outfile = "$tmpdir/$lib.stp";  # 为每个库创建临时文件
    open my $out, ">$outfile"
        or die "Cannot open $outfile for writing: $!\n";
    print $out $src;  # 将处理后的库内容写入临时文件
    close $out;
}

# 将临时目录添加到 stap 的包含路径
push @stap_opts, "-I", $tmpdir;

# 处理 -c 选项（执行命令并在命令结束后退出）
if (defined $shcmd) {
    push @stap_opts, "-c", $shcmd;
}

# 构建完整的 stap 命令
my $cmd = "stap " . quote_sh_args(\@stap_opts) . " -";  # 使用管道输入脚本内容
warn $cmd;  # 调试用，输出完整命令

open my $in, "|$cmd"  # 打开管道将脚本内容传递给 stap
    or die "Cannot run stap: $!\n";
print $in $stap_src;  # 将处理后的脚本内容写入 stap 的标准输入
close $in;  # 关闭管道，等待 stap 执行完成



#=====================
# 定义一些辅助函数
# 处理用户自定义变量（$*var 格式）
sub eval_usr_var {
    my ($file, $usr_vars, $var) = @_;  # 参数：文件名、变量表、变量名
    if (defined $usr_vars->{$var}) {
        return $usr_vars->{$var};  # 返回变量值
    }

    die "$file: line $.: Undefined user varaible \$*$var.\n";  # 变量未定义则报错
}

# 处理标准内置变量（$^var 格式）
sub eval_std_var {
    my ($file, $var, $trait_name, $trait_val) = @_;  # 参数：文件名、变量名、特性名、特性值

    $UsedStdVars{$var} = 1;  # 标记变量已被使用

    # 如果变量已定义，直接返回其值
    if (defined $StdVars{$var}) {
        return $StdVars{$var};
    }

    # 处理变量特性（如 $^arg_foo:default(123)）
    if (defined $trait_name) {
        #warn "trait: $trait_name";
        if ($trait_name eq 'default') {  # 处理默认值特性
            if ($print_args && $var =~ /^arg_(\w+)$/) {
                $used_args{$1} = $trait_val;  # 记录参数默认值
            }
            $StdVars{$var} = $trait_val;  # 设置变量值为默认值
            return $trait_val;  # 返回默认值
        } else {
            die "$file: line $.: unknown trait name: $trait_name\n";  # 未知特性报错
        }
    }

    # 处理 --args 模式下的变量
    if ($print_args) {
        if ($var =~ /^arg_(\w+)$/) {
            $used_args{$1} = undef;  # 记录参数但不设置默认值
        }
        return '';  # 返回空字符串
    }

    # 处理特殊变量
    if ($var eq 'exec_path') {  # 可执行文件路径
        die "$file: line $.: \$^exec_path is used but neither -x <pid> ",
            "nor --exec <path> is specified.\n";  # 未指定路径则报错

    } elsif ($var =~ /^arg_(\w+)$/) {  # 用户参数
        die "$file: line $.: \$^$var is used but no --arg $1=VAL option is specified.\n";  # 未指定参数则报错

    } elsif ($var =~ /^(lib\w+)_path$/) {  # 库文件路径
        my $prefix = $1;
        my $libpath = find_dso_path($prefix);  # 查找动态库路径
        if (!$libpath) {
            warn "$file: line $.: $prefix is not found, assuming it is statically linked.\n";
            if (!defined $StdVars{exec_path}) {
                die "No -x <pid> option is specified.\n";
            }

            $LibPaths{$prefix} = $StdVars{exec_path};  # 假设静态链接，使用可执行文件路径
            return $StdVars{exec_path};
        }

        return $libpath;  # 返回找到的库路径
    } else {
        die "$file: line $.: Undefined built-in variable \$^$var.\n";  # 未知内置变量报错
    }
}

# 查找动态共享对象(DSO)的路径
sub find_dso_path {
    my $pat = shift;  # 获取库名模式，通常是 libxxx 格式

    # 检查缓存中是否已有该库的路径
    my $path = $LibPaths{$pat};
    if ($path) {
        return $path;  # 如果已缓存，直接返回
    }

    # 解析库名模式，提取实际库名（去掉lib前缀）
    my $name;
    if ($pat !~ /^lib(\S+)/) {
        die "bad pattern: $pat";  # 库名必须以lib开头
    }

    $name = $1;  # 提取lib后面的实际库名

    # 在已发现的DSO列表中查找匹配的库
    my $found_path;
    for my $path (sort keys %DSOs) {
        #warn "checking $path against $pat";
        
        # 尝试精确匹配（如 libssl-1.0.0.so.10）
        if ($path =~ m{\blib\Q$name\E[-.\d]*\.so(?:\.\d+)*$}) {
            $LibPaths{$pat} = $path;  # 缓存结果
            $found_path = $path;
            warn "Found exact match for $pat: $path\n";  # 输出找到的精确匹配
            last;  # 找到精确匹配后立即返回
	}

        # 尝试模糊匹配（处理库名可能有变体的情况）
        if ($path =~ m{\b(?:lib)?\Q$name\E[^/\s]*?\.so(?:\.\d+)*$}) {
            if ($found_path) {
                warn "Ignored ambiguous library $path for \"$pat\"\n";  # 忽略模糊匹配
                next;
            }

            $LibPaths{$pat} = $path;  # 缓存结果
            $found_path = $path;  # 记录找到的路径
        }
    }

    return $found_path;  # 返回找到的路径，如果未找到则为undef
}

# 读取源文件内容
sub read_src_file {
    my $infile = shift;  # 获取输入文件路径
    open my $in, $infile
        or die "Cannot open $infile for reading: $!\n";  # 打开文件失败则报错
    my $src = do { local $/; <$in> };  # 一次性读取整个文件内容
    close $in;  # 关闭文件句柄
    return $src;  # 返回文件内容
}

# 处理@use指令，导入tapset库文件
sub use_libs {
    my ($file, $libs) = @_;  # 参数：当前文件名、库列表字符串
    #warn "libs: $libs";
    
    my @libs = split /\s*,\s*/, $libs;  # 按逗号分隔库名列表
    for my $lib (@libs) {
        #warn "processing $lib...";
        
        # 将点分隔的库名转换为路径（如 ngx.time 变为 ngx/time.sxx）
        my $path = join("/", split /\./, $lib) . ".sxx";
        #warn $path;
        
        # 在所有包含路径中查找库文件
        for my $dir (@$Inc) {
            my $abspath = File::Spec->catfile($dir, $path);  # 构建绝对路径
            warn "Testing $abspath\n";
            warn "exist: ", (-f $abspath) ? 1 : 0;
            
            if (-f $abspath) {  # 如果文件存在
                my $src = read_src_file($abspath);  # 读取库文件内容
                $UsedLibs{$lib} = process_src($abspath, $src);  # 处理库文件内容并缓存
                goto next_lib;  # 跳转到下一个库的处理
            }
        }
        die "$file: line $.: cannot find \@use library $lib\n";  # 找不到库文件则报错
next_lib:  # 处理下一个库的标签
    }
    return "";  # @use指令本身不产生输出
}

# 处理stap源代码，替换变量和指令
sub process_src {
    my ($file, $src) = @_;  # 参数：文件名、源代码内容

    my %usr_vars;  # 存储用户自定义变量
    my @bits;      # 存储处理后的代码片段

    # 定义库名模式（支持点分隔的库名，如 ngx.time）
    my $libname_pat = qr/(?:\w+(?:\.\w+)*)/;
    
    # 处理输入文件
    open my $in, '<', \$src or die $!;  # 从字符串打开文件句柄

    while (<$in>) {
        # 替换脚本首行的 shebang
        if ($. == 1 && /^\#!/) {
            $_ = "#!/usr/bin/env stap\n";  # 确保使用 stap 解释器
            next;
        }

        # 替换参数变量（$^arg_xxx 格式）
        s{\$\^(arg_\w+)(?:\s*:(\w+)\s*\((.*?)\))?}{eval_std_var($file, $1, $2, $3)}eg;
        
        # 替换 @pfunc 函数调用（简化函数引用）
        s{\@pfunc\s*\(\s*(\w+)\s*\)}{process("\$^exec_path").function("$1")}g;
        
        # 替换标准变量（$^xxx 格式）
        s{\$\^(\w+|lib[-.\w]+_path)(?:\s*:(\w+)\s*\((.*?)\))?}{eval_std_var($file, $1, $2, $3)}eg;
        
        # 处理用户变量赋值（$*xxx := @cast(...) 格式）
        s{\$\*(\w+)\s*:=\s*(\&?\@(?:cast|var)\(.*?\)(?:\[\d+\])?)}{$usr_vars{$1} = $2; ""}eg;
        
        # 替换用户变量引用（$*xxx 格式）
        s{\$\*(\w+)}{eval_usr_var($file, \%usr_vars, $1)}eg;
        
        # 处理库导入指令（@use xxx 格式）
        s{\@use\s+($libname_pat(?:\s*,\s*$libname_pat)*)}{use_libs($file, $1)}eg;

    } continue {
        push @bits, $_;  # 将处理后的行添加到结果数组
    }

    close $in;  # 关闭文件句柄
    return join '', @bits;  # 合并所有行并返回
}

# 生成帮助信息
sub usage {
    return <<'_EOC_';
Usage:
    stap++ [optoins] [infile]

Options:
    --arg NM=VAL    Specify extra user arguments (for $^arg_NM).
    --args          Print all available arguments for --arg.
    -c CMD     start the probes, run CMD, and exit when it finishes
    -d PATH         Load debug info for the specified objects
    -D NM=VAL       Emit macro definition into generated C code.
    -e SCRIPT       Run given script.
    --exec PATH     Specify the executable file path to be traced.
    --help          Print this help.
    -I PATH         Specify the stap++ tapset library search directory.
    --master PID    Specify the master pid whose child processes are traced.
    --sample-pid PID  Sample process to inspect DSO objects to load via -d
    -v              Be verbose.
    -x PID          Sets target() to PID (also for $^exec_path and $^libxxx_path).

Examples:
    stap++ -x 12345 -e 'probe begin { println("hello") exit() }'
    stap++ -x 12345 infile.ss
_EOC_
}

# 获取指定进程的所有子进程
sub get_child_processes {
    my $pid = shift;  # 获取父进程ID
    
    # 获取所有进程的状态文件
    my @files = glob "/proc/[0-9]*/stat";
    my @children;  # 存储子进程ID
    
    # 遍历所有进程
    for my $file (@files) {
        #print "file: $file\n";
        
        # 跳过进程自身
        if ($file =~ m{^/proc/$pid/}) {
            next;
        }

        # 读取进程状态信息
        open my $in, $file or next;  # 打开失败则跳过
        my $line = <$in>;
        close $in;
        
        # 解析进程ID和父进程ID
        if ($line =~ /^(\d+) \S+ \S+ (\d+)/) {
            my ($child, $parent) = ($1, $2);
            if ($parent eq $pid) {  # 如果父进程ID匹配
                push @children, $child;  # 添加到子进程列表
            }
        }
    }

    # 按数字顺序排序子进程ID
    @children = sort { $a <=> $b } @children;
    return @children;  # 返回子进程ID列表
}

# 生成进程ID过滤条件
sub gen_pid_test_condition {
    my $pids = shift;  # 获取进程ID列表
    
    # 如果未提供进程ID列表，则使用 target() 函数
    if (!$pids) {
        return "pid() == target()";  # 默认条件：当前进程ID等于目标进程ID
    }

    # 为每个进程ID生成条件
    my @c;
    for my $pid (@$pids) {
        push @c, "pid() == $pid";  # 添加进程ID相等条件
    }
    
    # 使用逻辑或连接所有条件，并用括号包围
    return '(' . join(" || ", @c) . ')';
}

# 处理进程的动态共享对象
sub process_dso {
    my $pid = shift;  # 获取进程ID
    
    # 打开进程的内存映射文件
    my $maps_file = "/proc/$pid/maps";
    open my $in, $maps_file
        or die "Cannot open $maps_file for reading: $!\n";

    # 解析内存映射，查找动态库
    while (<$in>) {
        if (m{\S+\.so(?:\.\d+)*$}) {  # 匹配以 .so 结尾的路径
            my $path = $&;  # 获取匹配的路径
            $DSOs{$path} = 1;  # 记录到动态库哈希表
            #warn "seeing $path";
        }
    }

    # 为所有发现的动态库添加调试信息选项
    for my $path (sort keys %DSOs) {
        push @stap_opts, '-d', $path;
    }
}

# 处理Shell命令参数的引用，确保特殊字符被正确转义
sub quote_sh_args ($) {
    my ($args) = @_;  # 获取参数数组引用
    for my $arg (@$args) {
       # 检查参数是否只包含常见的Shell安全字符
       if ($arg =~ m{^[- "&%;,|?*.+=\w:/()]*$}) {
          # 如果包含空格或特殊字符，用单引号包围
          if ($arg =~ /[ "&%;,|?*()]/) {
             $arg = "'$arg'";
          }
          next;  # 处理下一个参数
       }
       
       # 处理包含更复杂字符的参数，使用$'...'格式（ANSI-C引用）
       $arg =~ s/\\/\\\\/g;  # 转义反斜杠
       $arg =~ s/'/\\'/g;    # 转义单引号
       $arg =~ s/\n/\\n/g;   # 转义换行符
       $arg =~ s/\r/\\r/g;   # 转义回车符
       $arg =~ s/\t/\\t/g;   # 转义制表符
       $arg = "\$'$arg'";    # 使用ANSI-C引用格式
    }
    return "@$args";  # 返回空格连接的参数字符串
}