Skip to content

Commit

Permalink
bashreadline
Browse files Browse the repository at this point in the history
  • Loading branch information
brendangregg committed Jan 29, 2016
1 parent 0030d34 commit aa87997
Show file tree
Hide file tree
Showing 4 changed files with 113 additions and 0 deletions.
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ Examples:

Tools:

- tools/[bashreadline](tools/bashreadline.py): Print entered bash commands system wide. [Examples](tools/bashreadline_example.txt).
- tools/[biolatency](tools/biolatency.py): Summarize block device I/O latency as a histogram. [Examples](tools/biolatency_example.txt).
- tools/[biosnoop](tools/biosnoop.py): Trace block device I/O with PID and latency. [Examples](tools/biosnoop_example.txt).
- tools/[funccount](tools/funccount.py): Count kernel function calls. [Examples](tools/funccount_example.txt).
Expand Down
48 changes: 48 additions & 0 deletions man/man8/bashreadline.8
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
.TH bashreadline 8 "2016-01-28" "USER COMMANDS"
.SH NAME
bashreadline \- Print entered bash commands system wide. Uses Linux eBPF/bcc.
.SH SYNOPSIS
.B bashreadline
.SH DESCRIPTION
bashreadline traces the return of the readline() function using uprobes, to
show the bash commands that were entered interactively, system wide. The
entered command may fail: this is just showing what was entered.

This program is also a basic example of eBPF/bcc and uprobes.

Since this uses BPF, only the root user can use this tool.
.SH REQUIREMENTS
CONFIG_BPF and bcc.
.SH EXAMPLES
.TP
Trace bash commands system wide:
#
.B bashreadline
.SH FIELDS
.TP
TIME
Time of the command (HH:MM:SS).
.TP
PID
Process ID of the bash shell.
.TP
COMMAND
Entered command.
.SH OVERHEAD
As the rate of interactive bash commands is expected to be very low (<<100/s),
the overhead of this program is expected to be negligible.
.SH SOURCE
This is from bcc.
.IP
https://github.com/iovisor/bcc
.PP
Also look in the bcc distribution for a companion _examples.txt file containing
example usage, output, and commentary for this tool.
.SH OS
Linux
.SH STABILITY
Unstable - in development.
.SH AUTHOR
Brendan Gregg
.SH SEE ALSO
opensnoop(8)
43 changes: 43 additions & 0 deletions tools/bashreadline.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
#!/usr/bin/python
#
# bashreadline Print entered bash commands from all running shells.
# For Linux, uses BCC, eBPF. Embedded C.
#
# This works by tracing the readline() function using a uretprobe (uprobes).
#
# Copyright 2016 Netflix, Inc.
# Licensed under the Apache License, Version 2.0 (the "License")
#
# 28-Jan-2016 Brendan Gregg Created this.

from __future__ import print_function
from bcc import BPF
from time import strftime

# load BPF program
bpf_text = """
#include <uapi/linux/ptrace.h>
int printret(struct pt_regs *ctx) {
if (!ctx->ax)
return 0;
char str[80] = {};
bpf_probe_read(&str, sizeof(str), (void *)ctx->ax);
bpf_trace_printk("%s\\n", &str);
return 0;
};
"""
b = BPF(text=bpf_text)
b.attach_uretprobe(name="/bin/bash", sym="readline", fn_name="printret")

# header
print("%-9s %-6s %s" % ("TIME", "PID", "COMMAND"))

# format output
while 1:
try:
(task, pid, cpu, flags, ts, msg) = b.trace_fields()
except ValueError:
continue
print("%-9s %-6d %s" % (strftime("%H:%M:%S"), pid, msg))
21 changes: 21 additions & 0 deletions tools/bashreadline_example.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
Demonstrations of bashreadline, the Linux eBPF/bcc version.


This prints bash commands from all running bash shells on the system. For
example:

# ./bashreadline
TIME PID COMMAND
05:28:25 21176 ls -l
05:28:28 21176 date
05:28:35 21176 echo hello world
05:28:43 21176 foo this command failed
05:28:45 21176 df -h
05:29:04 3059 echo another shell
05:29:13 21176 echo first shell again

The entered command may fail. This is just showing what command lines were
entered interactively for bash to process.

It works by tracing the return of the readline() function using uprobes
(specifically a uretprobe).

0 comments on commit aa87997

Please sign in to comment.