Microsoft Visual Studio Code Supporting Add-on for Splunk
Overview
Details
Microsoft Visual Studio Code Supporting Add-on for Splunk
The Microsoft Visual Studio Code Supporting Add-on for Splunk provides support for debugging user Python code contained in apps, add-ons, custom search commands, custom REST handlers, modular visualizations, or any user Python code run within Splunk Enterprise. The supporting add-on can automatically create a debug configuration for your Splunk Enterprise project and provides helper methods for the Visual Studio Code Python Debug Adapter.
Requirements
Microsoft Visual Studio Code - a free cross-platform code editor from Microsoft
Splunk Enterprise
Microsoft Visual Studio Code Supporting Add-on for Splunk (this add-on)
Visual Studio Code Splunk extension
For more information about the Visual Studio Code Splunk extension, refer to the Wiki.
Modifying your code
In order to debug your Python code, some minor changes need to be made. Place the following in your 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)
The above code does 2 main things:
- Appends the path of the supporting add-on to the Python path. This makes is 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 long, in 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.
Setting a break point (optional)
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()
Configure debugging with debug.conf (optional)
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.conf
[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. It is recommended to either remove debug code or disable debugging options for production.
Starting the Visual Studio Code Debugger
Visual Studio Code attaches to your modified code using a debug configuration created by the supported add-on. This configuration is named "Splunk Enterprise: Python Debugger".
Step 1 - open your Splunk Enterprise folder in Visual Studio Code
It is necessary to open the folder in order for Visual Studio Code to read the debug configuration created by the supporting add-on.
After launching Visual Studio Code, choose Open folder...
Step 2 – start the debugger
Once your Python code is running, perform the following steps in Visual Studio Code:
- Select debug from the Visual Studio Code side bar
- Choose the "Splunk Enterprise: Python Debugger" configuration
- Click the start debugging button
Release Notes
Version 0.1.2
Added support for a debug.conf file to control the debugger. See the details page for more information.