{"componentChunkName":"component---src-components-mark-down-block-js","path":"/docs/cli-using/","result":{"data":{"markdownRemark":{"html":"

Using The Command Line Interface (CLI)

\n

As soon as you download AppScope, you can start using the CLI to explore and gain insight into application behavior. No installation or configuration is required.

\n

The CLI provides a rich set of capabilities for capturing and managing data from single applications. Data is captured in the local filesystem by default, and you can specify a different destination.

\n

By default, the AppScope CLI redacts binary data from console output. Although in most situations, the default behaviors of the AppScope CLI and library are the same, they differ for binary data: it's omitted in the CLI, and allowed when using the library. To change this, use the allowbinary=true flag. The equivalent environment variable is SCOPE_ALLOW_BINARY_CONSOLE. In the config file, allowbinary is an attribute of the console watch type for events.

\n

To learn more, see the CLI Reference, and/or run scope --help or scope -h. And check out the Further Examples, which include both CLI and library use cases.

\n

CLI Basics

\n

The basic AppScope CLI command is scope. The following examples progress from simple to more involved. Scoping a running process gets its own section. The final section explains how to scope an app that generates a large data set, and then explore that data.

\n

Scope a New Process

\n

Try scoping some well-known Linux commands, and view the results:

\n
scope top\n
\n
scope ls -al\n
\n
scope curl https://www.google.com\n
\n

When scoping browsers, we use the --no-sandbox option because virtually all modern browsers incorporate the sandbox security mechanism, and some sandbox implementations can interact with AppScope in ways that cause the browser to hang, or not to start.

\n
scope firefox --no-sandbox\n
\n

Scope a Series of Shell Commands

\n

In the shell that you open in this example, every command you run will be scoped:

\n
scope bash\n
\n

To release a process like scope bash above, exit the process in the shell. If you do this with the bash shell itself, you won't be able to scope bash again in the same terminal session.

\n

Scope Cribl Stream

\n

See what AppScope shows Cribl Stream doing:

\n

scope $CRIBL_HOME/bin/cribl server

\n

You can take the idea of using AppScope to reveal application behavior much further.

\n

Use a Custom HTTP Header to Mark Your Data

\n

When scoping apps that make HTTP requests, you can add the X-Appscope header, setting its content to the string of your choice.

\n

Here's a trivial example of how this feature might be useful:

\n

Suppose you want to scope HTTP requests to a weather forecast service, looking at many different cities, but labeling the data by country.

\n

You could use the X-Appscope header to do your labeling:

\n
scope curl --header \"X-Appscope: Canada\" wttr.in/calgary\nscope curl --header \"X-Appscope: Canada\" wttr.in/ottawa\n...\n\nscope curl --header \"X-Appscope: Brazil\" wttr.in/recife\nscope curl --header \"X-Appscope: Brazil\" wttr.in/riodejaneiro\n...\n
\n

In the resulting AppScope events, the body > data element would include an \"x-appscope\" field whose value would be the country named in the request's X-Appscope header.

\n

\n

Invoke a Config File While Scoping a New Process

\n

Why create a custom configuration file? One popular reason is to change the destination to which AppScope sends captured data to someplace other than the local filesystem (the default). To learn about the possibilities, read the comments in the default Configuration File.

\n

This example scopes the echo command while invoking a configuration file named cloud.yml:

\n
scope run -u cloud.yml -- echo foo\n
\n

\n

Scoping a Running Process

\n

You attach AppScope to a process using either a process ID or a process name.

\n

Attaching by Process ID

\n

In this example, we'll start by grepping for process IDs of cribl (Cribl Stream) processes:

\n
$ ps -ef | grep cribl\nubuntu    1820     1  1 21:03 pts/4    00:00:02 /home/ubuntu/someusername/cribl/4.0.3/m/cribl/bin/cribl server\nubuntu    1838  1820  4 21:03 pts/4    00:00:07 /home/ubuntu/someusername/cribl/4.0.3/m/cribl/bin/cribl /home/ubuntu/someusername/cribl/4.0.3/m/cribl/bin/cribl.js server -r CONFIG_HELPER\nubuntu    1925 30025  0 21:06 pts/3    00:00:00 grep --color=auto cribl\n
\n

Then, we'll attach to a process of interest:

\n
ubuntu@ip-127-0-0-1:~/someusername/appscope3$ sudo scope attach 1820\n
\n

Attaching by Process Name

\n

In this example, we try to attach to a Cribl Stream process by its name, which will be cribl. Since there's more than one process, AppScope lists them and prompts us to choose one:

\n
$ sudo scope attach cribl\nFound multiple processes matching that name...\nID  PID   USER    SCOPED  COMMAND\n1   1820  ubuntu  false   /home/ubuntu/someusername/cribl/4.0.3/m/cribl/bin/cribl server\n2   1838  ubuntu  false   /home/ubuntu/someusername/cribl/4.0.3/m/cribl/bin/cribl /home/ubuntu/someusername/cribl/4.0.3/m/cribl/bin/cribl.js server -r CONFIG_HELPER\nSelect an ID from the list:\n2\nWARNING: Session history will be stored in /home/ubuntu/.scope/history and owned by root\nAttaching to process 1838\n
\n

Detaching from Processes

\n

You can also detach AppScope from a process.

\n

Furthermore, if you want to undo the effects of the scope attach, scope start, and/or scope service commands, run the scope stop command. This runs scope detach --all, removes the rules file from the system, and removes scope from service configurations.

\n

When you detach from a process, AppScope:

\n\n

What AppScope does not do is unload its library.

\n

More About Scoping Running Processes

\n

To attach AppScope to a running process:

\n
    \n
  1. You must run scope as root, or with sudo.
    2. \n
  2. If you attach to a shell, AppScope does not automatically scope its child processes.
    3. \n
  3. You can attach to a process that is executing within a container context by running scope attach inside that container or from the host.
    4. \n
\n

When you attach AppScope to a process, its child processes are not automatically scoped.

\n

You cannot attach to a static executable's process.

\n

No HTTP/1.1 events and headers are emitted when AppScope attaches to a Go process that uses the azure-sdk-for-go package.

\n

No events are emitted from files or sockets that exist before AppScope attaches to a process.

\n\n

\n

Working with HTTP Payloads

\n

When you scope an app that produces HTTP traffic, you can capture the payloads using the -p or --payloads option. This is AppScope's payloads feature (see the payload section in the AppScope config file), which is disabled by default, because it can create large amounts of data, and because it captures payloads unencrypted.

\n

When the payloads feature is enabled, setting SCOPE_PAYLOAD_TO_DISK to true guarantees that AppScope will write payloads to the local directory specified in SCOPE_PAYLOAD_DIR.

\n

\n

Exploring Captured Data

\n

You can scope apps that generate large data sets, and then use AppScope CLI subcommands and options to monitor and visualize the data. The following extended example introduces this technique.

\n

Start by scoping the ps command:

\n
scope run -- ps -ef\n
\n

Show last session's captured metrics with scope metrics:

\n
NAME             VALUE      TYPE     UNIT           PID     TAGS\nproc.start       1          Count    process        5470    args: ps -ef,gid: 0,groupname: root,host: ip-10-8-107-15…\nproc.cpu         60898      Count    microsecond    5470    host: my_hostname,proc: ps\nproc.cpu_perc    0.60898    Gauge    percent        5470    host: my_hostname,proc: ps\nproc.mem         67512      Gauge    kibibyte       5470    host: my_hostname,proc: ps\nproc.thread      2          Gauge    thread         5470    host: my_hostname,proc: ps\nproc.fd          6          Gauge    file           5470    host: my_hostname,proc: ps\nproc.child       1          Gauge    process        5470    host: my_hostname,proc: ps\nfs.read          379832     Count    byte           5470    host: my_hostname,proc: ps,summary: true\nnet.rx           401        Count    byte           5470    class: unix_tcp,host: my_hostname,proc: ps,summary: …\nnet.tx           361        Count    byte           5470    class: unix_tcp,host: my_hostname,proc: ps,summary: …\nfs.seek          150        Count    operation      5470    host: my_hostname,proc: ps,summary: true\nfs.stat          136        Count    operation      5470    host: my_hostname,proc: ps,summary: true\n...\n
\n

Plot a chart of last session's proc.cpu metric with scope metrics -m proc.cpu -g:

\n
 80000 ┼                   ╭╮\n 76000 ┤                   ││\n 72000 ┤                   ││\n 68000 ┤                   ││\n 64000 ┤                   ││\n 60000 ┤                   ││\n 56000 ┤                   ││\n 52000 ┤                   ││                                     ╭╮                               ╭╮   ╭─\n 48000 ┤                   ││                                     ││                               ││   │\n 44000 ┤                   ││                                     ││                               ││   │\n 40000 ┤ ╭╮                ││                                     ││          ╭╮                ╭─╮││ ╭╮│\n 36000 ┤ ││                ││                                     ││          ││                │ │││ │││\n 32000 ┤ ││╭╮              ││          ╭╮    ╭╮ ╭╮                ││ ╭╮       ││ ╭╮ ╭╮ ╭╮ ╭╮ ╭╮╭╯ ╰╯╰╮│╰╯\n 28000 ┤ ││││              ││          ││    ││ ││                ││ ││       ││ ││ ││ ││ ││ │││     ││\n 24000 ┤ ││││              ││          ││    ││ ││                ││ ││       ││ ││ ││ ││ ││ │││     ││\n 20000 ┤╭╯││╰╮ ╭╮╭╮ ╭──╮╭╮ ││ ╭╮ ╭╮ ╭╮ ││ ╭──╯│ ││╭─╮ ╭╮    ╭───╮ ││╭╯│ ╭╮ ╭╮ │╰╮││ ││ ││ ││ │╰╯     ╰╯\n 16000 ┤│ ││ │ ││││ │  │││ ││ ││ ││ ││ ││ │   │ │││ │ ││    │   │ │││ │ ││ ││ │ │││ ││ ││ ││ │\n 12000 ┤│ ╰╯ ╰─╯╰╯╰─╯  ╰╯│╭╯╰─╯╰─╯│╭╯╰─╯╰─╯   ╰─╯╰╯ ╰─╯╰────╯   │╭╯╰╯ │╭╯╰─╯╰─╯ ╰╯╰─╯│╭╯╰─╯╰─╯\n  8000 ┤│                ││       ││                            ││    ││             ││\n  4000 ┤│                ││       ││                            ││    ││             ││\n     0 ┼╯                ╰╯       ╰╯                            ╰╯    ╰╯             ╰╯\n
\n

Display the last session's captured events with scope events:

\n
[EkA1] Jul 12 02:11:15 ps fs fs.open file:/proc/17721/stat\n[OrA1] Jul 12 02:11:15 ps fs fs.close file:/proc/17721/stat file_read_bytes:158 file_read_ops:1 file_write_bytes:0 file_write_ops:0\n[xAA1] Jul 12 02:11:15 ps fs fs.open file:/proc/17721/status\n[LHA1] Jul 12 02:11:15 ps fs fs.close file:/proc/17721/status file_read_bytes:952 file_read_ops:1 file_write_bytes:0 file_write_ops:0\n[vQA1] Jul 12 02:11:15 ps fs fs.open file:/proc/17721/cmdline\n[IXA1] Jul 12 02:11:15 ps fs fs.close file:/proc/17721/cmdline file_read_bytes:0 file_read_ops:1 file_write_bytes:0 file_write_ops:0\n[s6B1] Jul 12 02:11:15 ps fs fs.open file:/proc/17758/stat\n...\n
\n

Now scope a command which produces HTTP and other kinds of events:

\n
scope run -- curl https://www.google.com\n
\n

Filter out everything but http from the last session's events, with scope events -t http:

\n
[vL1] Jul 12 02:14:07 curl http http.req http_host:www.google.com http_method:GET http_scheme:https http_target:/\n[PU1] Jul 12 02:14:08 curl http http.resp http_host:www.google.com http_method:GET http_target:/\n
\n

View the history of the current AppScope session with scope history:

\n
Displaying last 20 sessions\nID  COMMAND CMDLINE                     PID     AGE     DURATION    TOTAL EVENTS\n4   ps      ps -ef                      5464    3m6s    12ms        788\n5   curl    curl https://www.google.…   5492    14s     141ms       20\n
\n

Scope another command which will produce a variety of events ...

\n
# scope run -- apt update\nHit:1 http://us-west-2.ec2.archive.ubuntu.com/ubuntu bionic InRelease\nGet:2 http://us-west-2.ec2.archive.ubuntu.com/ubuntu bionic-updates InRelease [88.7 kB]                                      \nGet:3 http://us-west-2.ec2.archive.ubuntu.com/ubuntu bionic-backports InRelease [74.6 kB]                                    \nHit:4 https://download.docker.com/linux/ubuntu bionic InRelease                                                                                \nGet:5 http://security.ubuntu.com/ubuntu bionic-security InRelease [88.7 kB]                                                                    \nHit:6 https://baltocdn.com/helm/stable/debian all InRelease\n...\n
\n

... Then, show only the last 10 events of sourcetype console, sorted in ascending order by timestamp:

\n
# scope events --sort _time --sourcetype console --last 10 --reverse\n[g2Wg] Jul 12 02:14:49 apt console stdout message:\"                                  0% [Working] 0% [16 Packages store 0 B]                …\"\n[zvUe] Jul 12 02:14:49 apt console stdout message:\"                                  0% [Working] 0% [16 Packages store 0 B]                …\"\n[ucRe] Jul 12 02:14:50 find console stdout message:/var/lib/apt/lists/security.ubuntu.com_ubuntu_dists_bionic-security_universe_binary-amd6…\n[zkRe] Jul 12 02:14:50 dirname console stdout message:/var/lib/update-notifier\n[I0Se] Jul 12 02:14:50 mktemp console stdout message:/var/lib/update-notifier/tmp.ut1sgTEuvb\n[gmUg] Jul 12 02:14:54 python3 console stdout message:\"39 updates can be applied immediately. To see these additional updates run: apt list …\"\n[gZ7h] Jul 12 02:14:54 apt console stdout message:\"Reading package lists... 0%\"\n[1a2i] Jul 12 02:14:54 apt console stdout message:\"Reading package lists... 0%  Reading package lists... 0%  Reading package lists... 3%  Re…\"\n[cp1i] Jul 12 02:14:54 apt console stdout message:\"Reading package lists... 0%  Reading package lists... 0%  Reading package lists... 3%  Re…\"\n[QU2i] Jul 12 02:14:56 apt console stderr message:\"W: An error occurred during the signature verification. The repository is not updated and…\"\n
\n

Scope a command which reads and writes over the network:

\n
# scope curl wttr.in    \nWeather report: Portland, Oregon, United States\n\n      \\   /     Sunny\n       .-.      93 °F          \n    ― (   ) ―   ↓ 6 mph        \n       `-’      9 mi           \n      /   \\     0.0 in         \n                                                       ┌─────────────┐                                                       \n┌──────────────────────────────┬───────────────────────┤  Mon 11 Jul ├───────────────────────┬──────────────────────────────┐\n│            Morning           │             Noon      └──────┬──────┘     Evening           │             Night            │\n├──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤\n│     \\   /     Sunny          │     \\   /     Sunny          │     \\   /     Sunny          │     \\   /     Clear          │\n│      .-.      68 °F          │      .-.      89 °F          │      .-.      +95(93) °F     │      .-.      78 °F          │\n│   ― (   ) ―   ↓ 5-6 mph      │   ― (   ) ―   ↘ 6-7 mph      │   ― (   ) ―   ↘ 10-11 mph    │   ― (   ) ―   ↘ 8-15 mph     │\n│      `-’      6 mi           │      `-’      6 mi           │      `-’      6 mi           │      `-’      6 mi           │\n│     /   \\     0.0 in | 0%    │     /   \\     0.0 in | 0%    │     /   \\     0.0 in | 0%    │     /   \\     0.0 in | 0%    │\n└──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┘       \n...\n
\n

Then, show only events containing the string net_bytes, and display the fields net_bytes_sent and net_bytes_recv, with their values:

\n
# scope events --fields net_bytes_sent,net_bytes_recv --match net_bytes\n[e91] Jul 12 02:15:41 curl net net.close net_bytes_sent:71 net_bytes_recv:8773\n
","frontmatter":{"title":"Using the CLI"}}},"pageContext":{"slug":"/cli-using/","id":"a69e5f8a-ca57-5420-b865-2ee7985e1caa"}},"staticQueryHashes":["2787008656","306729481","625673991","640077088"]}