Debugging
User-generated Python code running in Splunk Enterprise can be debugged using Visual Studio Code. The Visual Studio Code Extension for Splunk provides breakpoints, step in/over code, access to the call stack, variable watchers, and more!
- Splunk Enterprise - running in a data center or even a public cloud
- Microsoft Visual Studio Code Supporting Add-on for Splunk - enables Python code running in Splunk Enterprise to be debugged by Visual Studio Code
- Visual Studio Code
- Visual Studio Code Extension for Splunk - contains everything you need to get started debugging plus bonus features to interact with Splunk.
Conceptually, there are two components:
- A machine, like a workstation, running Visual Studio Code
- A machine running Splunk Enterprise software
Technically, these things can run on the same machine. However, Visual Studio Code can run on a workstation while Splunk Enterprise runs in a remote data center or even in a public cloud.
Each component requires specific software. The workstation running Visual Studio Code requires the Visual Studio Code Extension for Splunk. The server running Splunk Enterprise requires the Visual Studio Code Supporting Add-on for Splunk.
First, you must add a few lines of Python code to the component you want to debug on the Splunk Enterprise side. This code enables the Visual Studio Code debugger to connect and debug the Python code running in Splunk Enterprise.
Next, start the component you want to debug on the Splunk Enterprise server. For example, to debug a modular input, create an instance of the input and enable it. To debug a custom search command, start a Splunk search and invoke the command. To debug a custom alert action, create a search to trigger the action. Basically, the code needs to be running for Visual Studio Code to connect.
Finally, start the debugger in Visual Studio Code. This connects Visual Studio Code to the running process in Splunk Enterprise and enables a familiar debug experience.
To debug your Python code, place the following in the Python file you would like to debug:
import sys, os
sys.path.append(os.path.join(os.environ['SPLUNK_HOME'],'etc','apps','SA-VSCode','bin'))
import splunk_debug as dbg
dbg.enable_debugging(timeout=25)
This code:
- Appends the path of the supporting add-on to the Python path. This makes it possible for your code to import the necessary modules without copying them to your project.
- Starts the debug server for your code. The timeout parameter specifies how many seconds the debug server will wait for Visual Studio Code to connect to the running process. If a connection is not made during this time period, the Python code will continue to run as normal.
Breakpoints can be set in Visual Studio Code, or you can use the following line to force a breakpoint anywhere in your Python code:
dbg.set_breakpoint()
The debugger can be configured for an app by creating a new file with the name debug.conf in the $SPLUNK_HOME/etc/apps/<app_directory>/local/ directory.
[debug]
enabled = <boolean>
* Set whether an app allows debugging
* Enabling debugging can delay execution and introduce artificial latency. It is recommended to either remove debug code or disable debugging options for production.
* Default: true
Important: enabling debugging can delay execution and introduce artificial latency. For production, either remove debug code or disable debugging options.
Visual Studio Code attaches to your modified code using a debug configuration created by the supporting add-on. This configuration is named "Splunk Enterprise: Python Debugger".
After launching Visual Studio Code, choose Open folder...
Select the root folder of your Splunk Enterprise application. This will typically be located in $SPLUNK_HOME/etc/apps/. For example, to debug a modular input in an application named myapp, open the folder $SPLUNK_HOME/etc/apps/myapp.
Once your Python code is running:
- Select Run and Debug from the Visual Studio Code side bar.
- Choose the "Splunk Enterprise: Python Debugger" configuration.
- Click the Start button.
