How to work with saved searches using the Splunk SDK for PHP

The Splunk SDK for PHP is deprecated. For more information, see Deprecation notice.

The most fundamental feature in Splunk® is searching your data. But before diving into the details of how to use the SDK to search, let's clarify the terms:

  • A search query is a set of commands and functions you use to retrieve events from an index or a real-time stream, for example: "search * | head 10".
  • A saved search is a search query that has been saved to be used again and can be set up to run on a regular schedule. The results from the search are not saved with the query.
  • A search job is an instance of a completed or still-running search operation, along with the results. A search ID is returned when you create a job, allowing you to access the results of the search when they become available. Search results are returned in XML.

This topic focuses on working with saved searches. For more about working with search jobs, see How to run searches and jobs.

 

The saved search APIs

You work with saved searches using the following APIs:

Access these classes through an instance of the Splunk_Service class. Retrieve a collection, and from there you can access individual items in the collection and create new ones. For example, here is a simplified program for getting a collection of saved searches and creating a new one:

// Connects to Splunk
$service = new Splunk_Service($connectArguments);

// Retrieves a list of all saved searches, for all users and apps
$savedSearches = $service->getSavedSearches()->items(array(
    'namespace' => Splunk_Namespace::createUser(NULL, NULL),     
));

// Creates a saved search with a given name ($name) and search query ($query)
$service->getSavedSearches()->create($name, array(
    'search' => $query,
));

 

Code examples

This section provides examples of how to use the search APIs, assuming you first connect to a Splunk instance. To view these APIs in action, navigate to the index.php page within the examples directory (for instance, if you're developing and testing on your local machine, the URL might be http://localhost:8888/splunk-sdk-php/examples/index.php), and then click "List Saved Searches" under "Examples".

The following parameters are available for saved searches:

 

Listing saved searches

This example shows how to retrieve and list the saved searches in a saved search collection. If you don't explicitly specify a namespace, the service's namespace is used.

<?php

// Get all saved searches
$savedSearches = $service->getSavedSearches()->items(array(
  'namespace' => Splunk_Namespace::createUser(NULL, NULL),     
));

?>

<!-- List the name of each saved search -->
<ul>
<?php
  foreach ($savedSearches as $savedSearch)
  {
    echo '<li>';
    echo htmlspecialchars($savedSearch->getName());
    echo '</li>';
  }
?>

To retrieve a collection for a specific namespace―for example, to list the saved searches available to a specific username or app―provide the namespace as arguments to the Splunk_Namespace::createUser method. The first argument specifies a user, and the second argument specifies an app. In the previous example, both arguments are set to NULL, which specifies all users and all apps.

 

Creating a saved search

When you create a saved search, at a minimum you need to provide a search query and a name for the search. You can also specify additional properties for the saved search at this time by providing a dictionary of key-value pairs for the properties (the possible properties are summarized in Saved search parameters). Or, modify properties after you have created the saved search.

This example shows how to create a simple saved search:

<?php

// Create a saved search by specifying a name and search query
// Note: Do not include the 'search' keyword for a saved search
$myQuery = "* | head 10"; 
$mySearchName = "Test Search";
$savedSearch = $service->getSavedSearches()->create($mySearchName, array(
    'search' => $myQuery,
)); 	

// Print a confirmation
echo '<p>The search "';
echo htmlspecialchars($savedSearch->getName());
echo '" was saved.</p>';

?>
 

Viewing and modifying the properties of a saved search

This example shows how to view the properties of the new saved search. You can use the syntax shown below to view the values of any saved search parameter.

<?php

// Retrieve the search that was just created
$savedSearch = $service->getSavedSearches()->get('Test Search'); 

// Display some properties of the new search
echo '<p>Properties for "';
echo htmlspecialchars($savedSearch->getName());
echo '":</p><ul>';
echo '<li>Description: ';
echo htmlspecialchars($savedSearch['description']);
echo '</li>';
echo '<li>Scheduled: ';
echo htmlspecialchars($savedSearch['is_scheduled']);
echo '</li>';
echo '<li>Next scheduled time: '; 
echo htmlspecialchars($savedSearch['next_scheduled_time']);
echo '</li></ul>';

?>

To set properties (except the 'name' property), use the Splunk_SavedSearch::update method.

<?php

// Retrieve the search that was just created
$savedSearch = $service->getSavedSearches()->get('Test Search'); 

// Update the properties 
$savedSearch->update(array(
    'description' => 'This is a test search',
    'is_scheduled' => true,
    'cron_schedule' => '15 4 * * 6',
));

echo '<p>New properties for "';
echo htmlspecialchars($savedSearch->getName());
echo '":</p><ul>';
echo '<li>Description: ';
echo htmlspecialchars($savedSearch->offsetGet('description'));
echo '</li>';
echo '<li>Scheduled: ';
echo htmlspecialchars($savedSearch->offsetGet('is_scheduled'));
echo '</li>';
echo '<li>Next scheduled time: '; 
echo htmlspecialchars($savedSearch->offsetGet('next_scheduled_time'));
echo '</li></ul>';

?>
 

Running a saved search

Running a saved search creates a search job that is scheduled to run right away. Use the Splunk_SavedSearch::dispatch method to run a saved search. It returns a Splunk_Job object that corresponds to the search job. The Splunk_Job object gives you access to information about the search job, such as the search ID, the status of the search, and the search results once the search job has finished.

<?php

// Retrieve the new saved search
$savedSearch = $service->getSavedSearches()->get('Test Search'); 

// Run a saved search and poll for completion
echo '<p>Run the "';
echo htmlspecialchars($savedSearch->getName());
echo '" search (';
echo htmlspecialchars($savedSearch->offsetGet('search'));
echo ').</p>';

$job = $savedSearch->dispatch();

echo '<p>Waiting for the job to finish...</p>';

try
{
    // Print progress of the job as it is running
    echo '<ul>';
    while (!$job->isDone())
    {
        echo '<li>';
        printf("%03.1f%%", $job->getProgress() * 100);
        echo '</li>';
        flush();

        usleep(0.5 * 1000000);
        $job->refresh();
    }
    echo '<li>Done</li>';
    echo '</ul>';

    // (NOTE: Can throw HTTP 400 if search command arguments not recognized)
    $results = $job->getResults();
    $messages = array();
}
catch (Exception $e)
{
    // Generate fake result that contains the exception message
    $results = array();
    $messages = array();
    $messages[] = new Splunk_ResultsMessage('EXCEPTION', $e->getMessage());
}	
?>

Once the search has finished, retrieve the search results from the Splunk_Job object. For more, see How to run searches and jobs.

 

Deleting a saved search

Delete a saved search using the Splunk_SavedSearch::delete method. (Any jobs created from the saved search are unaffected.)

This example shows how to delete a saved search:

<?php

// Retrieve a saved search
$savedSearch = $service->getSavedSearches()->get('Test Search'); 

// Delete the saved search
$savedSearch->delete();

?>
 

Collection parameters

The parameters below are available when retrieving a collection of saved searches.

By default, all entities are returned when you retrieve a collection. Using the parameters below, you can specify the number of entities to return, how to sort them, and so on.

Parameter

Description

count A number that indicates the maximum number of entries to return. A value of 0 means all entries are returned.
earliest_time A string that contains all the scheduled times starting from this time (not just the next run time).
latest_time A string that contains all the scheduled times until this time.
offset A number that specifies the index of the first item to return.
For oneshot inputs, this value refers to the current position in the source file, indicating how much of the file has been read.
search A string that specifies a search expression to filter the response with, matching field values against the search expression. For example, "search=foo" matches any object that has "foo" as a substring in a field, and "search=field_name%3Dfield_value" restricts the match to a single field.
sort_dir An enum value that specifies how to sort entries. Valid values are "asc" (ascending order) and "desc" (descending order).
sort_key A string that specifies the field to sort by.
sort_mode An enum value that specifies how to sort entries. Valid values are "auto", "alpha" (alphabetically), "alpha_case" (alphabetically, case sensitive), or "num" (numerically).
 

Saved search parameters

The properties that are available for saved searches correspond to the parameters for the saved/searches endpoint in the REST API.

This table summarizes the properties you can set for a saved search.

Parameter

Description

name Required. A string that contains the name of the saved search.
search Required. A string that contains the search query.
action.* A string with wildcard arguments to specify specific action arguments.
action.email A Boolean that indicates the state of the email alert action. Read only.
action.email.auth_password A string that specifies the password to use when authenticating with the SMTP server. Normally this value is set while editing the email settings, but you can set a clear text password here that is encrypted when Splunk is restarted.
action.email.auth_username A string that specifies the username to use when authenticating with the SMTP server. If this is empty string, authentication is not attempted.
action.email.bcc A string that specifies the BCC email address to use if "action.email" is enabled.
action.email.cc A string that specifies the CC email address to use if "action.email" is enabled.
action.email.command A string that contains the search command (or pipeline) for running the action.
action.email.format An enum value that indicates the format of text and attachments in the email ("plain", "html", "raw", or "csv"). Use "plain" for plain text.
action.email.from A string that specifies the email sender's address.
action.email.hostname A string that specifies the hostname used in the web link (URL) that is sent in email alerts. Valid forms are "hostname" and "protocol://hostname:port".
action.email.inline A Boolean that indicates whether the search results are contained in the body of the email.
action.email.mailserver A string that specifies the address of the MTA server to be used to send the emails.
action.email.maxresults The maximum number of search results to send when "action.email" is enabled.
action.email.maxtime A number indicating the maximum amount of time an email action takes before the action is canceled. The valid format is number followed by a time unit ("s", "m", "h", or "d"), for example "5d".
action.email.pdfview A string that specifies the name of the view to deliver if "action.email.sendpdf" is enabled.
action.email.preprocess_results A string that specifies how to pre-process results before emailing them.
action.email.reportCIDFontList Members of an enumeration in a space-separated list specifying the set (and load order) of CID fonts for handling Simplified Chinese(gb), Traditional Chinese(cns), Japanese(jp), and Korean(kor) in Integrated PDF Rendering.
action.email.reportIncludeSplunkLogo A Boolean that indicates whether to include the Splunk logo with the report.
action.email.reportPaperOrientation An enum value that indicates the paper orientation ("portrait" or "landscape").
action.email.reportPaperSize An enum value that indicates the paper size for PDFs ("letter", "legal", "ledger", "a2", "a3", "a4", or "a5").
action.email.reportServerEnabled A Boolean that indicates whether the PDF server is enabled.
action.email.reportServerURL A string that contains the URL of the PDF report server, if one is set up and available on the network.
action.email.sendpdf A Boolean that indicates whether to create and send the results as a PDF.
action.email.sendresults A Boolean that indicates whether to attach search results to the email.
action.email.subject A string that specifies the subject line of the email.
action.email.to A string that contains a comma- or semicolon-delimited list of recipient email addresses. Required if this search is scheduled and "action.email" is enabled.
action.email.track_alert A Boolean that indicates whether running this email action results in a trackable alert.
action.email.ttl The number of seconds indicating the minimum time-to-live (ttl) of search artifacts if this email action is triggered. If the value is a number followed by "p", it is the number of scheduled search periods.
action.email.use_ssl A Boolean that indicates whether to use secure socket layer (SSL) when communicating with the SMTP server.
action.email.use_tls A Boolean that indicates whether to use transport layer security (TLS) when communicating with the SMTP server.
action.email.width_sort_columns A Boolean that indicates whether columns should be sorted from least wide to most wide, left to right. This value is only used when "action.email.format"="plain", indicating plain text.
action.populate_lookup A Boolean that indicates the state of the populate-lookup alert action. Read only.
action.populate_lookup.command A string that specifies the search command (or pipeline) to run the populate-lookup alert action.
action.populate_lookup.dest A string that specifies the name of the lookup table or lookup path to populate.
action.populate_lookup.hostname A string that specifies the host name used in the web link (URL) that is sent in populate-lookup alerts. Valid forms are "hostname" and "protocol://hostname:port".
action.populate_lookup.maxresults The maximum number of search results to send in populate-lookup alerts.
action.populate_lookup.maxtime The number indicating the maximum amount of time an alert action takes before the action is canceled. The valid format is number followed by a time unit ("s", "m", "h", or "d").
action.populate_lookup.track_alert A Boolean that indicates whether running this populate-lookup action results in a trackable alert.
action.populate_lookup.ttl The number of seconds indicating the minimum time-to-live (ttl) of search artifacts if this populate-lookup action is triggered. If the value is a number followed by "p", it is the number of scheduled search periods.
action.rss A Boolean that indicates the state of the RSS alert action. Read only.
action.rss.command A string that contains the search command (or pipeline) that runs the RSS alert action.
action.rss.hostname A string that contains the host name used in the web link (URL) that is sent in RSS alerts. Valid forms are "hostname" and "protocol://hostname:port".
action.rss.maxresults The maximum number of search results to send in RSS alerts.
action.rss.maxtime The maximum amount of time an RSS alert action takes before the action is canceled. The valid format is number followed by a time unit ("s", "m", "h", or "d").
action.rss.track_alert A Boolean that indicates whether running this RSS action results in a trackable alert.
action.rss.ttl The number of seconds indicating the minimum time-to-live (ttl) of search artifacts if this RSS action is triggered. If the value is a number followed by "p", it is the number of scheduled search periods.
action.script A Boolean that indicates the state of the script alert action. Read only.
action.script.command A string that contains the search command (or pipeline) that runs the script action.
action.script.filename A string that specifies the file name of the script to call, which is required if "action.script" is enabled.
action.script.hostname A string that specifies the hostname used in the web link (URL) that is sent in script alerts. Valid forms are "hostname" and "protocol://hostname:port".
action.script.maxresults The maximum number of search results to send in script alerts.
action.script.maxtime The maximum amount of time a script action takes before the action is canceled. The valid format is number followed by a time unit ("s", "m", "h", or "d").
action.script.track_alert A Boolean that indicates whether running this script action results in a trackable alert.
action.script.ttl The number of seconds indicating the minimum time-to-live (ttl) of search artifacts if this script action is triggered. If the value is a number followed by "p", it is the number of scheduled search periods.
action.summary_index A Boolean that indicates the state of the summary index alert action. Read only.
action.summary_index._name A string that specifies the name of the summary index where the results of the scheduled search are saved.
action.summary_index.command A string that contains the search command (or pipeline) that runs the summary-index action.
action.summary_index.hostname A string that specifies the hostname used in the web link (URL) that is sent in summary-index alerts. Valid forms are "hostname" and "protocol://hostname:port".
action.summary_index.inline A Boolean that indicates whether to run the summary indexing action as part of the scheduled search.
action.summary_index.maxresults The maximum number of search results to send in summary-index alerts.
action.summary_index.maxtime A number indicating the maximum amount of time a summary-index action takes before the action is canceled. The valid format is number followed by a time unit ("s", "m", "h", or "d"), for example "5d".
action.summary_index.track_alert A Boolean that indicates whether running this summary-index action results in a trackable alert.
action.summary_index.ttl The number of seconds indicating the minimum time-to-live (ttl) of search artifacts if this summary-index action is triggered. If the value is a number followed by "p", it is the number of scheduled search periods.
actions A string that contains a comma-delimited list of actions to enable, for example "rss,email".
alert.digest_mode A Boolean that indicates whether Splunk applies the alert actions to the entire result set or digest ("true"), or to each individual search result ("false").
alert.expires The amount of time to show the alert in the dashboard. The valid format is number followed by a time unit ("s", "m", "h", or "d").
alert.severity A number that indicates the alert severity level (1=DEBUG, 2=INFO, 3=WARN, 4=ERROR, 5=SEVERE, 6=FATAL).
alert.suppress A Boolean that indicates whether alert suppression is enabled for this scheduled search.
alert.suppress.fields A string that contains a comma-delimited list of fields to use for alert suppression.
alert.suppress.period A value that indicates the alert suppression period, which is only valid when "Alert.Suppress" is enabled. The valid format is number followed by a time unit ("s", "m", "h", or "d").
alert.track An enum value that indicates how to track the actions triggered by this saved search. Valid values are: "true" (enabled), "false" (disabled), and "auto" (tracking is based on the setting of each action).
alert_comparator A string that contains the alert comparator. Valid values are: "greater than", "less than", "equal to", "rises by", "drops by", "rises by perc", and "drops by perc".
alert_condition A string that contains a conditional search that is evaluated against the results of the saved search.
alert_threshold A value to compare to before triggering the alert action. Valid values are: integer or integer%. If this value is expressed as a percentage, it indicates the value to use when "alert_comparator" is set to "rises by perc" or "drops by perc".
alert_type A string that indicates what to base the alert on. Valid values are: "always", "custom", "number of events", "number of hosts", and "number of sources". This value is overridden by "alert_condition" if specified.
args.* A string containing wildcard arguments for any saved search template argument, such as "args.username"="foobar" when the search is search $username$.
auto_summarize A Boolean that indicates whether the scheduler ensures that the data for this search is automatically summarized.
auto_summarize.command A string that contains a search template that constructs the auto summarization for this search.
auto_summarize.cron_schedule A string that contains the cron schedule for probing and generating the summaries for this saved search.
auto_summarize.dispatch.earliest_time A string that specifies the earliest time for summarizing this saved search. The time can be relative or absolute; if absolute, use the "dispatch.time_format" parameter to format the value.
auto_summarize.dispatch.latest_time A string that contains the latest time for summarizing this saved search. The time can be relative or absolute; if absolute, use the "dispatch.time_format" parameter to format the value.
auto_summarize.dispatch.ttl The number of seconds indicating the time to live (in seconds) for the artifacts of the summarization of the scheduled search. If the value is a number followed by "p", it is the number of scheduled search periods.
auto_summarize.max_disabled_buckets A number that specifies the maximum number of buckets with the suspended summarization before the summarization search is completely stopped, and the summarization of the search is suspended for the "auto_summarize.suspend_period" parameter.
auto_summarize.max_summary_ratio A number that specifies the maximum ratio of summary size to bucket size, which specifies when to stop summarization and deem it unhelpful for a bucket. The test is only performed if the summary size is larger than the value of "auto_summarize.max_summary_size".
auto_summarize.max_summary_size A number that specifies the minimum summary size, in bytes, before testing whether the summarization is helpful.
auto_summarize.max_time A number that specifies the maximum time (in seconds) that the summary search is allowed to run. Note that this is an approximate time because the summary search stops at clean bucket boundaries.
auto_summarize.suspend_period A string that contains the time indicating when to suspend summarization of this search if the summarization is deemed unhelpful.
auto_summarize.timespan A string that contains a comma-delimited list of time ranges that each summarized chunk should span. This comprises the list of available granularity levels for which summaries would be available.
cron_schedule A string that contains the cron-style schedule for running this saved search.
description A string that contains a description of this saved search.
disabled A Boolean that indicates whether the saved search is enabled.
dispatch.* A string that specifies wildcard arguments for any dispatch-related argument.
dispatch.buckets The maximum number of timeline buckets.
dispatch.earliest_time A time string that specifies the earliest time for this search. Can be a relative or absolute time. If this value is an absolute time, use "dispatch.time_format" to format the value.
dispatch.latest_time A time string that specifies the latest time for this saved search. Can be a relative or absolute time. If this value is an absolute time, use "dispatch.time_format" to format the value.
dispatch.lookups A Boolean that indicates whether lookups for this search are enabled.
dispatch.max_count The maximum number of results before finalizing the search.
dispatch.max_time The maximum amount of time (in seconds) before finalizing the search.
dispatch.reduce_freq The number of seconds indicating how frequently Splunk runs the MapReduce reduce phase on accumulated map values.
dispatch.rt_backfill A Boolean that indicates whether to back fill the real-time window for this search. This value is only used for a real-time search.
dispatch.spawn_process A Boolean that indicates whether Splunk spawns a new search process when running this saved search.
dispatch.time_format A string that defines the time format that Splunk uses to specify the earliest and latest time.
dispatch.ttl The number indicating the time to live (ttl) for artifacts of the scheduled search (the time before the search job expires and artifacts are still available), if no alerts are triggered. If the value is a number followed by "p", it is the number of scheduled search periods.
displayview A string that contains the default UI view name (not label) in which to load the results.
is_scheduled A Boolean that indicates whether this saved search runs on a schedule.
is_visible A Boolean that indicates whether this saved search is visible in the saved search list.
max_concurrent The maximum number of concurrent instances of this search the scheduler is allowed to run.
next_scheduled_time A string that indicates the next scheduled time for this saved search. Read only.
qualifiedSearch A string that is computed during run time. Read only.
realtime_schedule A Boolean that specifies how the scheduler computes the next time a scheduled search is run:
  • When "true": The schedule is based on the current time. The scheduler might skip some scheduled periods to make sure that searches over the most recent time range are run.
  • When "false": The schedule is based on the last search run time (referred to as "continuous scheduling") and the scheduler never skips scheduled periods. However, the scheduler might fall behind depending on its load. Use continuous scheduling whenever you enable the summary index option ("action.summary_index").

The scheduler tries to run searches that have real-time schedules enabled before running searches that have continuous scheduling enabled.

request.ui_dispatch_app A string that contains the name of the app in which Splunk Web dispatches this search.
request.ui_dispatch_view A string that contains the name of the view in which Splunk Web dispatches this search.
restart_on_searchpeer_add A Boolean that indicates whether a real-time search managed by the scheduler is restarted when a search peer becomes available for this saved search. The peer can be one that is newly added or one that has become available after being down.
run_on_startup A Boolean that indicates whether this search is run when Splunk starts. If the search is not run on startup, it runs at the next scheduled time. It is recommended that you set this value to "true" for scheduled searches that populate lookup tables.
vsid A string that contains the view state ID that is associated with the view specified in the "displayview" attribute.