The Splunk Software Development Kit (SDK) for C# 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 C# contains library code and examples that show how to programmatically interact with Splunk for a variety of scenarios including searching, saved searches, data inputs, and many more, along with building complete applications.
The information in this Readme provides steps to get going quickly. In the future we plan to roll out more in-depth documentation.
Here's what you need to get going with the Splunk SDK for C#.
If you haven't already installed Splunk, download it at http://www.splunk.com/download. For more information about installing and running Splunk and system requirements, see the Splunk Installation Manual.
Get the Splunk SDK for C#. Download the ZIP file and extract its contents.
If you are interested in contributing to the Splunk SDK for C#, you can get it from GitHub and clone the resources to your computer.
The Splunk SDK for C# supports development in Microsoft Visual Studio 2012. The minimum supported version of the .NET Framework is version 3.5. Visual Studio downloads are available on the Visual Studio Downloads webpage.
Before starting to develop custom software, you must first build the SDK. Once you've downloaded and extracted—or cloned—the SDK, do the following:
- At the root level of the splunk-sdk-csharp directory, open the SplunkSDK.sln file in Visual Studio.
- On the BUILD menu, click Build Solution.
This will build the SDK, the examples, and the unit tests.
The Splunk SDK for C# includes several examples and unit tests that are run at the command prompt.
To connect to Splunk, many of the SDK examples and unit tests take command-prompt 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 prompt, the SDK examples and unit tests use the values from the .splunkrc file.
To use a .splunkrc file:
First, create a new text file and save it as .splunkrc.
Windows might display an error when you try to name the file because ".splunkrc" looks like a nameless file with an extension. You can use the console window to create this file by going to the C:\Users\currentusername directory and entering the following at the command prompt:
Notepad.exe .splunkrc
A dialog box appears, asking whether you want to create a new file. Click Yes, and then continue creating the file.
In the new file, paste in the following. Be sure to customize any lines that apply to your Splunk instance.
# 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 in the current user's home directory—for instance:
C:\Users\currentusername\.splunkrc
Important: Storing login credentials in the .splunkrc file is only for convenience during development—this file isn't part of the Splunk platform and shouldn't be used for storing user credentials for production. And, if you're at all concerned about the security of your credentials, just enter them at the command line rather than saving them in the .splunkrc file.
You can start getting familiar with the Splunk SDK for C# by running the examples that came with the SDK. Examples are located in the \splunk-sdk-csharp\examples directory. When you build the SDK, the examples are built as well. You can run the examples at the command prompt.
This version of the Splunk SDK for C# contains the following examples:
| Example | Description |
|---|---|
| authenticate | Authenticates to the server and prints the received token. |
| list_apps | Lists the apps installed on the server. |
| modular_input | Creates a modular input executable that you can modify. |
| search | Runs a normal search using a specified search query. |
| search_oneshot | Runs a oneshot search using a specified search query. |
| search_realtime | Runs a real-time search, gets a number of snapshots, prints them, and then exits. |
| sharepoint_web_part | Shows you how to create a Splunk Web part for Microsoft SharePoint. |
| submit | Submits events into Splunk. |
To run an example from the command line:
At the command prompt, go to the Debug directory of the built example, for instance:
\splunk-sdk-csharp\examples\examplename\bin\Debug
Run the example by typing its name, for instance:
examplename.exe
For the examples that include search functionality, you will need to provide search criteria in the following form, where query_syntax is a valid search query:
examplename.exe --search="query_syntax"
For instance, in the directory for the search_oneshot example, you can enter the following at the command prompt:
search_oneshot.exe --search="search sourcetype="access_combined_wcookie" 10.2.1.44 | head 10"
This runs a oneshot search for sourcetype="access_combined_wcookie" 10.2.1.44 (the IP address 10.2.1.44 and a sourcetype of access_combined_wcookie) and prints the first ten results to the console window.
A great place to look for examples of how to use the Splunk SDK for C# is in the unit tests. These are the same tests that we used to validate the core SDK library. The unit tests are located in the \splunk-sdk-csharp\UnitTests directory. When you build the SDK, the unit tests are built as well.
Before you run the unit tests, you must specify the test settings file to use:
- On the TEST menu, point to Test Settings, and then click Select Test Settings File
- In the Open Settings File dialog box, navigate to the root folder of the Splunk SDK for C#.
- Select the file named "Local.runsettings", and then click Open.
To run the unit tests in Visual Studio:
- On the TEST menu, point to Run, and then choose the option you want.
Alternately, you can use the Test Explorer in Visual Studio:
- Click the TEST menu, point to Windows, and then click Test Explorer.
- In the Test Explorer pane, click Run All to run all the tests, or choose a different option from the Run menu.
For more information about running unit tests, see the topic Running Unit Tests with Test Explorer on the Microsoft Developer Network (MSDN).
| \examples | Examples demonstrating various SDK features |
| \lib | Third-party libraries used by the SDK |
| \SplunkSDK | Source for the SDK |
| \SplunkSDKHelper | Utilities shared by examples and unit tests |
| \UnitTests | 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-csharp/blob/master/CHANGELOG.md.
The master branch always represents a stable and released version of the SDK. You can read more about our branching model on our Wiki at https://github.com/splunk/splunk-sdk-csharp/wiki/Branching-Model.
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 C#.
-
For API reference documentation, see the Splunk SDK for C# 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.
Stay connected with other developers building on Splunk.
| [email protected] | |
| Issues | https://github.com/splunk/splunk-sdk-csharp/issues |
| Answers | http://splunk-base.splunk.com/tags/csharp/ |
| Blog | http://blogs.splunk.com/dev/ |
| @splunkdev |
If you want to make a code contribution, go to the Open Source page for more information.
-
You will be granted support if you or your company are already covered under an existing maintenance/support agreement. Visit http://www.splunk.com/support and click Submit a Case under Contact a Support Engineer.
-
If you are not covered under an existing maintenance/support agreement, you can find help through the broader community at:
- Splunk Answers (use the sdk and c# tags to identify your questions)
- Splunkdev Google Group
-
Splunk will NOT provide support for SDKs if the core library (the code in the SplunkSDK directory) has been modified. If you modify an SDK and want support, you can find help through the broader community and Splunk answers (see above). We would also like to know why you modified the core library—please send feedback to [email protected].
-
File any issues on GitHub.
You can reach the Dev Platform team at [email protected].
The Splunk SDK for C# is licensed under the Apache License 2.0. Details can be found in the LICENSE file.