splunk-job
Search job lifecycle orchestration for Splunk.
Purpose
Manage the complete lifecycle of Splunk search jobs including creation, monitoring, control actions (pause/cancel/finalize), and cleanup.
Risk Levels
| Operation | Risk | Notes |
|---|---|---|
| Get job status | - | Read-only |
| List jobs | - | Read-only |
| Create job | - | Easily reversible via cancel |
| Pause/unpause job | ⚠️ | Can be undone |
| Finalize job | ⚠️ | Returns partial results |
| Cancel job | ⚠️ | Stops execution |
| Delete job | ⚠️⚠️ | Removes job and results |
Triggers
- •"job", "search job", "SID"
- •"status", "progress", "state"
- •"cancel", "pause", "unpause", "finalize"
- •"list jobs", "delete job"
Job States (dispatchState)
code
QUEUED → PARSING → RUNNING → FINALIZING → DONE
→ FAILED
→ PAUSED (on pause action)
| State | Description |
|---|---|
| QUEUED | Job waiting in queue |
| PARSING | SPL being parsed |
| RUNNING | Search executing |
| FINALIZING | Results being finalized |
| DONE | Completed successfully |
| FAILED | Error occurred |
| PAUSED | Paused by user |
CLI Commands
| Command | Description |
|---|---|
job create | Create search job, return SID |
job status | Get dispatchState, progress, stats |
job poll | Wait for job completion with timeout |
job cancel | Issue /control/cancel action |
job pause | Issue /control/pause action |
job unpause | Issue /control/unpause action |
job finalize | Issue /control/finalize action |
job ttl | Set job time-to-live |
job touch | Touch a job to extend its TTL |
job list | List all search jobs for user |
job delete | Remove job from dispatch directory |
Examples
Create and Monitor Job
bash
# Create job splunk-as job create "index=main | stats count by sourcetype" --earliest -1h # Output: Job created: 1703779200.12345 # Check status splunk-as job status 1703779200.12345 # Output: State: RUNNING, Progress: 45%, Events: 12345 # Wait for completion splunk-as job poll 1703779200.12345 --timeout 300 # Output: Job completed: DONE, Results: 42
Job Control
bash
# Pause running job splunk-as job pause 1703779200.12345 # Resume paused job splunk-as job unpause 1703779200.12345 # Cancel job splunk-as job cancel 1703779200.12345 # Finalize (stop and return current results) splunk-as job finalize 1703779200.12345
Job Management
bash
# List all jobs splunk-as job list # Output: Table of active jobs with status # Extend TTL (positional arg: SID TTL_VALUE) splunk-as job ttl 1703779200.12345 3600 # Delete job splunk-as job delete 1703779200.12345
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/services/search/v2/jobs | POST | Create job |
/services/search/v2/jobs/{sid} | GET | Get job status |
/services/search/v2/jobs/{sid}/control | POST | Control actions |
/services/search/jobs | GET | List jobs |
/services/search/jobs/{sid} | DELETE | Delete job |
Control Actions
python
# Available actions for /control endpoint
actions = ['cancel', 'pause', 'unpause', 'finalize', 'touch', 'setttl', 'enablepreview', 'disablepreview']
# POST /services/search/v2/jobs/{sid}/control
# data={'action': 'cancel'}
Job Properties
| Property | Description |
|---|---|
sid | Search job ID |
dispatchState | Current state |
doneProgress | Completion 0.0-1.0 |
eventCount | Events scanned |
resultCount | Results produced |
scanCount | Buckets scanned |
runDuration | Execution time |
ttl | Time to live |
isFailed | Failure flag |
isPaused | Pause flag |
Best Practices
- •Always set time bounds in the search query
- •Use appropriate timeout for poll_job.py
- •Cancel jobs when results are no longer needed
- •Monitor progress for long-running searches
- •Extend TTL for jobs you need to keep
Related Skills
- •splunk-search - Query execution
- •splunk-export - Result extraction