Use Macros To Avoid Index Dependency

In Report on data in this tutorial, the search you used in your dashboard referenced a specific index. However, as a recommended practice, you shouldn't include index definitions with your app. You could remove the specific index from your search, but then you'll have to include "index=*" in your searches instead. If your users want to restrict your app to searching in a specific index, they'll need to modify every search.

To work around this issue, you can use a macro that includes a default index to search, helping administrators to configure your app. For development, you can also set up a local version of the macro to reference your development index.

For more about macros, see Use search macros in searches in the Knowledge Manager Manual.

For a general description of using macros to avoid dependency on indexes, see App Design Patterns - Creating Indexes on Splunk Blogs.

Let's start out by creating a macro. In this macro, you'll specify an index that your app should look in for sendmail_syslog events.

  1. In Splunk Web, click Settings, then click Advanced search.
  2. Next to Search macros click Add new.
  3. Under Destination app make sure your app is selected.
  4. Under Name provide a name for your macro.
  5. Under Definition enter:
  6. index=hello_index

    Your macro definition should look something like this:

  7. Click Save to create your macro.
  8. As with searches, macros are saved to your local user's app's /local folder. Let's move it back into the app by changing its sharing permissions:

  9. Click Permissions next to your macro.
  10. Under Object should appear in select This app only.
  11. Click Save to update permissions.
  12. Return to your app by clicking the Apps menu in the upper left corner of the window and selecting your app.
  13. We need to edit the inline search in your app that is powering your dashboard to use your new macro. We'll also make the search a little more specific.

  14. On your dashboard, click Edit to open the edit view of your dashboard.
  15. Tip: You can also open edit view by appending "/edit" to your dashboard's URL.

  16. Next to Edit Dashboard, click Source to display the Simple XML view of your dashboard.
  17. In the <query> tag, replace "index=<your_index_name>" with:
  18. `default_index` sourcetype=sendmail_syslog

    Note  This line contains backticks (`), not single quotes (').

    This statement specifies the sourcetype to select only the data that your app is designed to handle. Right now, your app uses the index you created and has so far indexed only sendmail_syslog events. In the future, you can't be certain which index your app will be set up to target or what other events will be included in that index, so you should specify the sourcetype you expect.

  19. Click Save to save these changes.

When you return to your dashboard, it should look the same as before.

Now, your app's searches will use the default_index macro to specify the index in which to find events. If your app grew to include a large number of searches, you could easily change the target index for all of them just by changing the default_index macro.

Next, let's take a look at how your app's structure was affected:

  1. In a text editor, open $SPLUNK_HOME/etc/apps/your_app_name/metadata/local.meta.
  2. Splunk Web has added a stanza to define permissions for the default_index macro:

    Because this macro is only shared within this app, export is set to none.

    Note  If you previously deleted local.meta by following the steps in Your first AppInspect, the file will have been recreated.

  3. In a text editor, open $SPLUNK_HOME/etc/apps/your_app_name/local/macros.conf.
  4. Splunk Web has added a stanza defining your default_index macro:

    This addition is a good start for the local version of macros.conf because your index is the one you are using for development purposes. However, if you want to help the administrators who will be installing and configuring your app, add a macros.conf file to the /default directory for them to edit.

  5. Copy the macros.conf file from $SPLUNK_HOME/etc/apps/your_app_name/local folder to the $SPLUNK_HOME/etc/apps/your_app_name/default folder.
  6. In a text editor, open $SPLUNK_HOME/etc/apps/your_app_name/default/macros.conf.
  7. Replace "index=hello_index" with "".
  8. If you do not specify an index for searches, the default index is used, which is typically "main". Because the "main" index probably doesn't have any events matching sourcetype=sendmail_syslog, you won't see any results after you remove your local version of macros.conf. For end users of your apps, using this setup results in your app searching their default index, which is a reasonable approach.

  9. Add a comment letting future admins know to add their index specification to this file:
  10. Because you won't package local files when you distribute your app, if you were to upload your app to Splunkbase and someone were to install it, your app would search the user's default index by default until an administrator edits the macros.conf file.