.conf20 Session Q&A: Your Custom Search Command Questions Answered

At .conf20, my colleague Amy Sutedja and I had the opportunity to lead a breakout session on how you can customize the Splunk platform with custom search commands and setup pages. These two unique features allow you to extend the Splunk platform in a way that meets your specific needs and helps your customers to get the most value possible from your Splunk apps.

During our breakout session, we received a lot of great questions from the audience that we didn’t get the chance to answer live. We’ve compiled a list of these questions with answers from our team.

Top Ten Questions about Custom Search Commands

1. How can I integrate custom search commands into Splunk Cloud?
As long as your custom search command app is compatible with Splunk Cloud and Python 3, you’re good to go!

Here are some tools that you can use to evaluate your app for Splunk Cloud compatibility:

• Splunk AppInspect, the static analysis tool that backs the Splunk Cloud vetting process.
• The Splunk Platform Upgrade Readiness app, which verifies whether your app is compatible with Splunk Enterprise 8.x and Python 3.
   

You can also test your custom search command on a Splunk Enterprise deployment set up with a search head cluster configuration. This setup mimics the configuration that our larger mutual customers use in Splunk Cloud.

2. Can I use a custom search command to integrate a dashboard from Jira or Confluence into my Splunk app?
Partially. While you can certainly use a custom search command to get data from Jira or Confluence’s public REST API into Splunk Cloud or Splunk Enterprise, integrating a dashboard would most likely involve additional front-end development.

To integrate a dashboard into your Splunk app, you might consider either creating an HTML page for your app that allows you to embed complex objects or building an external page that integrates with Splunk software, as well as Jira or Confluence.

3. If you invoke the storage/passwords endpoint in the Python script for the search command, does the passed authentication for the user running the search require the list_storage_passwords capability?
Yes. If your custom search command script invokes the storage/passwords endpoint, the user running your search command needs to have the list_storage_passwords capability. 

For more information about the list_storage_password capability, see Define roles on the Splunk platform with capabilities in the Splunk Enterprise Securing the Splunk Platform manual.

4. In v1 custom search command protocol, there was a setting to ignore time order. Is there a similar way to ignore time order in v2 chunked protocol?
The v2 protocol for custom search commands doesn’t currently support this function. If this feature is important to you, you can request this setting as an enhancement on Splunk Ideas.

5. Is there a way to specify required fields in the custom search command @Configuration declaration passed from the SPL command invocation?
Yes. When you run a custom search command, the Splunk platform invokes an external process, as shown in the following diagram.

This process involves a getinfo exchange, in which splunkd sends a JSON payload that contains an optional required_fields setting to the custom search command script. The required_fields setting refers to the list of fields that the search command requires as input and is used for field extraction during the search.

For more information about the getinfo exchange, see How custom search commands work in the Splunk Developer Guide.

6. Can you leverage the Splunk Add-on Builder to create custom search commands?
No, you can’t create custom search commands with the Splunk Add-on Builder. To learn more about what you can use this tool to accomplish, see Use the Splunk Add-on Builder in the Splunk Add-on Builder User Guide.

7. What is the difference between a generating search command and the Intersplunk custom search command protocol?
A generating search command is a type of search command in SPL. You can use generating commands to fetch information from the indexes without performing any transformations. For more information about the types of search commands that you can create, see Types of search commands in the Splunk Developer Guide.

The Intersplunk custom search command protocol was an earlier, now deprecated, protocol for developing custom search commands. As a best practice, use the v2 protocol to create custom search commands. For the majority of use cases, the v2 protocol has better performance and compatibility with distributed Splunk Cloud and Splunk Enterprise configurations than the Intersplunk protocol.

8. What is the difference between extending the GeneratingCommand class and outputting a file that becomes a lookup table?
You extend the GeneratingCommand class to create a custom generating command. You typically use a generating command to fetch a result dataset that you don't necessarily want to store as indexed events or as a local lookup table in your Splunk Cloud or Splunk Enterprise deployment. For example, you might want to implement a generating command when Splunk Cloud or Splunk Enterprise is not the source of truth for a dataset that updates frequently and does not need to be stored in an index.

The custom search command in our weather_app_example demonstrates this use case. You don’t want to index all weather data from an external service, just in case you need to use some of it in your search. The “weather” generating command lets you pull a specific subset of this data into your search pipeline without requiring you to index the entire data source.

The following image shows how the “weather” generating command calls the external weather API to get events into Splunk Cloud or Splunk Enterprise.

9. Does the custom search command Python script run on the search head? Are there performance concerns if the Python is not well-written?
You can either run a custom search command on the search head or distribute the command to the indexers. The decision of where to run a custom search command depends on the search command type. To learn more about where the different command types run from, see Command types in the Splunk Enterprise Search Reference.

Python code that isn’t well-written could lead to performance issues, including slower processing times. As a best practice, optimize the Python code in your custom search command script.

10. What I am really missing is documentation about how to set up a local development environment using the Visual Studio Code Extension for Splunk and how to do local debugging.
We’re working on it! In the meantime, be sure to check out the Debugging Splunk Apps, Add-ons, and configurations using Visual Studio Code .conf talk. 

If you didn’t get the chance to attend our breakout session at .conf, be sure to check out the recording of Extend the Splunk Platform with Custom Search Commands and Setup Pages at .conf Online!

More Resources

Check out the following resources to learn more about custom search commands:

• For comprehensive documentation on custom search commands, see Create custom search commands for apps in Splunk Cloud or Splunk Enterprise in the Splunk Developer Guide.
• For the end-to-end custom search command example featured in our breakout session, see the weather_app_example in the splunk-app-examples repository on GitHub.
• For additional examples of the other types of custom search commands, see the searchcommands_app in the Splunk Enterprise SDK for Python on GitHub.
   

Stay tuned for our next blog post, in which we’ll answer your top questions about setup pages!

As always, if you have any questions or feedback, reach out at devfeedback@splunk.com.

Special thanks to Amy Sutedja, James Ervin, Tedd Hellmann, and David Poncelow for helping to answer these questions.