Deprecation notice
The Splunk SDK for Ruby is deprecated.
What deprecation means:
- On June 1, 2017, the resources relating to the Splunk SDK for Ruby will be removed from dev.splunk.com and will only be available in the GitHub repository.
- Apps that use the Splunk SDK for Ruby will continue to work as they do now.
- Apps that use the Splunk SDK for Ruby will continue to be eligible for Splunk App Certification.
- Splunk will no longer provide feature enhancements, engineering support, or customer support for the Splunk SDK for Ruby.
Recommendation on new app development and app migration:
- Because Splunk is no longer investing in the Splunk SDK for Ruby, we recommend that any new app development be done using other approaches:
- Directly using our REST API in the language of their choice.
- Using one of our supported SDKs:
- Python (GitHub | dev.splunk.com)
- Java (GitHub | dev.splunk.com)
- JavaScript (GitHub | dev.splunk.com)
- C# (GitHub | dev.splunk.com)
- For existing apps that use the Splunk SDK for Ruby, while not necessary, we request that developers begin the migration process away from the Splunk SDK for Ruby. We encourage developers to provide feedback to Splunk at devinfo@splunk.com if there are any issues with migration.
Notice of removal:
- The Splunk SDK for Ruby will continue to be available on GitHub, should other developers want to clone or fork the project. Documentation is located on GitHub as well.
This Splunk Software Development Kit (SDK) for Ruby contains library code and examples designed to enable developers to build applications using Splunk.
Splunk is a search engine and analytic environment that uses a distributed map-reduce architecture to efficiently index, search, and process large time-varying data sets.
The Splunk product is popular with system administrators for aggregation and monitoring of IT machine data, security, compliance, and a wide variety of other scenarios that share a requirement to efficiently index, search, analyze, and generate real-time notifications from large volumes of time series data.
The Splunk developer platform enables developers to take advantage of the same technology used by the Splunk product to build exciting new applications that are enabled by Splunk's unique capabilities.
The Splunk SDK for Ruby contains code and some examples that show how to programmatically interact with Splunk for a variety of scenarios, including searching, saved searches, configuration, and many more. This SDK is still in progress and is missing features such as inputs. Stay tuned.
Here's what you need to get going with the Splunk SDK for Ruby.
If you haven't already installed Splunk, download it here. For more information about installing and running Splunk and system requirements, see Installing & Running Splunk.
The Splunk SDK for Ruby has been tested with Ruby 1.9.2 and Ruby 1.9.3. For best results, use one of those versions.
Get the Splunk SDK for Ruby from GitHub and clone the resources to your computer. Use the following command:
git clone https://github.com/splunk/splunk-sdk-ruby.git You can also download the SDK as a ZIP file, or install it directly (see below).
If you have cloned the Splunk SDK for Ruby from GitHub, you should first
install the latest version of rake. For example, open a command prompt and
enter the following:
gem install rakeThen you can install the Splunk SDK for Ruby by running the following command from the root of the repository (/splunk-sdk-ruby):
rake installOr, install the Splunk SDK for Ruby directly from RubyGems, without cloning the repository or downloading the ZIP file, by running:
gem install splunk-sdk-rubyIf you are using the Splunk SDK for Ruby in an application, we highly recommend that you use bundler, which installs the prerequisites when you deploy your application. Add the following line to your application's Gemfile to make bundler aware of the Splunk SDK for Ruby:
gem 'splunk-sdk-ruby'Then run the following command to install all of your application's dependencies, including the Splunk SDK for Ruby:
bundleExamples are located in several locations within the Splunk SDK for Ruby:
First, do not run the test suite against your production Splunk server! Install another copy of Splunk and run the test suite against that.
Second, update your installations of both the Rake build tool and the Test::Unit unit test framework from RubyGems:
gem install rake
gem install test-unitThe test suite reads the host to connect to and credentials to use from a .splunkrc file. To connect to Splunk, all of the SDK examples and unit tests take command-line arguments that specify values for the host, port, and login credentials for Splunk. For convenience during development, you can store these arguments as key-value pairs in a text file named .splunkrc. Then, when you don't specify these arguments at the command line, the SDK examples and unit tests use the values from the .splunkrc file.
To set up a .splunkrc file
Create a text file with the following format:
# Splunk host (default: localhost) host=localhost # Splunk admin port (default: 8089) port=8089 # Splunk username username=admin # Splunk password password=changeme # Access scheme (default: https) scheme=https
Save the file as .splunkrc in the current user's home directory.
On Mac OS X
Save the file as:
~/.splunkrcOn Windows
Save the file as:
C:\Users\[currentusername]\.splunkrcYou might get errors in Windows when you try to name the file because ".splunkrc" looks like a nameless file with an extension. You can use the command line to create this file; go to the C:\Users\[currentusername]\ directory and enter the following command:
Notepad.exe .splunkrcClick Yes, then continue creating the file.
Notes
In the base directory where you installed the Splunk SDK for Ruby, run
rake testIt should run many tests without error.
To generate code coverage of the test suite, first ensure you've installed the latest version of SimpleCov:
gem install simplecovTo generate the code coverage, run:
rake test COVERAGE=trueIt will produce a directory called coverage. Open coverage/index.html to see the coverage report.
Note: To protect your Splunk password, you may want to delete the .splunkrc file when you are done running the unit tests.
| /examples | Examples demonstrating various SDK features |
| /lib | Source for the Splunk library modules |
| /test | Source for unit tests |
The CHANGELOG.md file in the root of the repository contains a description of changes for each version of the SDK. You can also find it online at https://github.com/splunk/splunk-sdk-ruby/blob/master/CHANGELOG.md.
The master branch always represents a stable and released version of the SDK.
If you need to know more:
For all things developer with Splunk, your main resource is the Splunk Developer Portal.
For conceptual and how-to documentation, see the Overview of the Splunk SDK for Ruby.
For API reference documentation, see the Splunk SDK for Ruby Reference.
For more about the Splunk REST API, see the REST API Reference.
For more about about Splunk in general, see Splunk>Docs.
For more about this SDK's repository, see our GitHub Wiki.
If you would like to contribute to the SDK, go here for more information:
You can find help through the broader community at Splunk Answers (use the sdk and ruby tags to identify your questions).
You can reach the Dev Platform team at devinfo@splunk.com.
The Splunk Software Development Kit for Ruby is licensed under the Apache License 2.0. Details can be found in the LICENSE file.