Track program execution

Chalk’s exec command is a powerful feature that allows you to gather runtime information about your applications as they execute. This capability creates a bridge between the build-time metadata collected during insertion operations and the actual runtime behavior of your software. With chalk exec, you can launch a program while simultaneously collecting information about its execution environment, process details, and system state.

Basic Usage: Executing a Simple Program

Let’s start with a simple example by running a basic Bash program with chalk exec.

Running a Simple Command

Create a simple shell script that we’ll execute with Chalk:

# Create a file named hello.sh
$ cat << EOF > hello.sh
#!/bin/bash
echo "Hello, \$1!"
sleep 5  # Give Chalk time to collect data
echo "Goodbye, \$1!"
EOF

# Make it executable
$ chmod +x hello.sh

Now, let’s run it by using chalk exec:

$ chalk exec -- ./hello.sh Chalk
Hello, Chalk!
Goodbye, Chalk!

Behind the scenes, Chalk observes the process and writes events to ~/.local/chalk/chalk.log (by default).

It will contain information about the process that was started, including its process ID, command name, executable path, and arguments. And it will include details about the host environment.

With a little help from jq we can get a pretty view of historic runs program.

$ cat ~/.local/chalk/chalk.log | jq -jc '.[]|select(._OPERATION == "exec")|(._OPERATION, " of ", ._CHALKS[0]._OP_ARTIFACT_PATH, " [", ._CHALKS[0]._PROCESS_PID, "], user ran ", ._ARGV, " at ", ._DATETIME, "\n")'
exec of /usr/bin/bash [1096], user ran ["hello.sh","Chalk"] at 2026-03-10T20:24:42.958+00:00

Now let’s exec the program a few more times with different arguments.

$ chalk exec -- ./hello.sh Megan
Hello, Megan!
Goodbye, Megan!
$ chalk exec -- ./hello.sh Varun
Hello, Varun!
Goodbye, Varun!

And see what the Chalk logs tell us.

$ cat ~/.local/chalk/chalk.log | jq -jc '.[]|select(._OPERATION == "exec")|(._OPERATION, " of ", ._CHALKS[0]._OP_ARTIFACT_PATH, " [", ._CHALKS[0]._PROCESS_PID, "], user ran ", ._ARGV, " at ", ._DATETIME, "\n")'
exec of /usr/bin/bash [1096], user ran ["hello.sh","Chalk"] at 2026-03-10T20:24:42.958+00:00
exec of /usr/bin/bash [1267], user ran ["hello.sh","Megan"] at 2026-03-10T20:44:12.755+00:00
exec of /usr/bin/bash [1270], user ran ["hello.sh","Varun"] at 2026-03-10T20:44:20.686+00:00

Understanding What’s Happening

When you run chalk exec, Chalk:

1. Starts the program you specified
2. Collects information about the process and environment
3. Generates a report with this information and,
4. By default, continues running your program as normal

The program itself runs exactly as it would without Chalk, but you get the additional benefit of Chalk’s reporting capabilities.

Unlike the insert and extract commands that focus on metadata within artifacts, exec focuses on capturing details about the execution context. This is particularly valuable for applications running in production environments, container orchestration systems, or any scenario where you need visibility into runtime behavior.

Examining the Exec Report

Let’s look at some of the key information provided in a chalk exec report:

Process Information

• _PROCESS_PID: The process ID of the running program
• _PROCESS_COMMAND_NAME: The name of the command being executed
• _PROCESS_EXE_PATH: The path to the executable
• _PROCESS_ARGV: The arguments passed to the program
• _PROCESS_CWD: The current working directory
• _PROCESS_STATE: The state of the process (running, sleeping, etc.)

Environment Information

• _ENV: Environment variables available to the process. By default only a few common environment variables are reported for security.
• _OP_HOSTNAME: The hostname of the machine
• _OP_PLATFORM: The operating system and architecture

Timing Information

• _TIMESTAMP: When the report was generated
• _DATETIME: ISO-8601 human-readable datetime of the report

For chalked applications, the report will also include the original chalk mark information, establishing a connection between build-time and runtime.

Practical Applications

Now that we understand the basics, let’s briefly consider some practical applications for chalk exec reports:

1. Runtime Monitoring: Track the behavior of your application over time through heartbeat reports.
2. Incident Investigation: When issues occur, exec reports provide valuable context about what was running and how.
3. Performance Analysis: Monitor resource usage and system state alongside your application.
4. Security Monitoring: Detect unexpected network connections or process behavior.
5. Container Observability: Gain visibility into containerized applications that might otherwise be difficult to monitor.

Learn about monitoring long-running procesess with Chalk heartbeats, observing network I/O, and monitoring containers.