Note: For the most up to date documentation for the Splunk SDK for C#, see http://dev.splunk.com/csharp.
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.
Version 2.0 introduces new modern APIs that leverage the latest .NET platform advancements.
- Async - All APIs are 100% asynchronous supporting the new async/await features.
- All APIs follow .NET guidelines and abide by FxCop and StyleCop rules.
- Reactive Extensions - Splunk Enterprise query results implement IObservable, allowing usage with the .NET Reactive Extensions.
- Support for cross-platform development - The Splunk API client (Splunk.Client.dll) in the new version is a Portable Class Library supporting .NET development on multiple platforms.
Below is an example of a simple One Shot Search:
using Splunk.Client;
var service = new Service(new Uri("https://localhost:8089"));
//login
await service.LogOnAsync("admin", "changeme");
//create a One Shot Search and retrieve the results
var searchResults = await service.SearchOneShotSearchAsync("search index=_internal | head 10");
//loop through the results
foreach (var result in searchResults)
{
//write out the raw event
Console.WriteLine(string.Format("{0:D8}: {1}", ++recordNumber, result.GetValue("_raw")));
}.NET 4.5/Mono 3.4, PCL (Windows 8.1, Windows Phone 8.1, iOS (via Xamarin.iOS), Android (via Xamarin.Android)
The Splunk SDK for C# version 2.x is a rewrite of the existing SDK, and introduces completely new APIs.
Important: Applications built with Splunk SDK for C# version 1.x will not recompile using Splunk SDK for C# version 2.xf.
Splunk SDK for C# version 2.x includes a subset of the capability in version 1.0 of the SDK, and focuses on the most common scenarios that we have seen customers using. The major focus areas are search, search jobs, configuration, and modular inputs.
Following is a breakdown of the areas covered:
- Login
- Access control (users and passwords)
- Searches (normal, blocking, oneshot, and export)
- Jobs
- Reports ("saved searches" in Splunk Enterprise 5)
- Configuration and Config Properties
- Indexes
- Inputs (sending simple and streamed events to Splunk Enterprise)
- Applications
- Modular inputs
For detailed API coverage, see this coverage matrix.
We will publish guidance on how to migrate applications built using the Splunk SDK for C# 1.x to use the Splunk SDK for C# 2.x.
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# version 2.x.
If you haven't already installed Splunk Enterprise, download it at http://www.splunk.com/download. For more information about installing and running Splunk Enterprise and system requirements, see the Splunk Installation Manual.
The Splunk SDK for C# supports development in the following environments:
The Splunk SDK for C# supports development in Microsoft Visual Studio 2012 and later
You will need to install Code Contracts for .NET (be sure to close Visual Studio before you install it or the install will not work, despite appearing to).
To run the unit tests you will need to install an xUnit runner:
- If you use resharper, install its xUnit.net Test Support.
- Otherwise, install the xUnit.net runner for Visual Studio 2012 and 2013.
The Splunk SDK for C# support development in Xamarin Studio and Mono Develop. You will need to set the MonoCS complitation constant in the project settings for Splunk.Client.csproj and Splunk.ModularInputs.csproj.
To run the unit tests you will need to download the latest release of xUnit and run using the command line tools or GUI runner.
Before the intial release, you can download the Splunk SDK C# NuGet packages from MyGet. Add the following feed to your package sources in Visual Studio: https://splunk.myget.org/F/splunk-sdk-csharp-pcl/
The following packages are in that feed:
- Splunk.Client - Client for Splunk's REST API. This is a portable library.
- Splunk.ModularInputs - Functionality for building Modular Inputs.
Note: Both packages will be published to NuGet when the SDK releases.
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.
To build from source after extracting or cloning the SDK, do the following"
- At the root level of the splunk-sdk-csharp-pcl directory, open the splunk-sdk-csharp-pcl.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 full unit tests which run using xunit as well as several examples.
The solution is organized into src, examples and tests folders.
Splunk.Client- Client for Splunk's REST API.Splunk.ModularInputs- Functionality for building Modular Inputs.Splunk.Client.Helpers- Helper utilities used by tests and samples.
Windows8/Search- Contains a Windows Store Search App.authenticate- Connects to a Splunk Instance and retrieves Splunk's session token.list_apps- Lists installed applications on a Splunk instance.mock-context- Demonstrates how to use the included HTTP record/play framework for unit tests.mock-interface- Demonstrates how to mock the functional interface for Splunk entities.mock-object- Demontrates how to mock concrete SDK objects and fake out HTTP responses for unit tests.normal-search- Performs a normal search against a Splunk instance and retrieves results using both enumeration and with Rx.random-numbers- Sample modular input which returns a randoml generated numbers.saved-searches- Creates a new saved search and retrieves results.search-export- Creates a search and usings splunk's Export endpoint to push back results.search-realtime- Creates a realtime search.search-response-message-stream- Demonstrates how to execute long-running search jobs and how to useJob.GetSearchReponseMessageAsync.search- Performs a One Shot search.submit- Creates an index and then sends events over HTTP to that index
- unit-tests - Contains unit tests for all of the classes in the SDK. Does not require a Splunk instance.
- acceptance-tests - Contains end to end tests using the SDK. These tests by default will go against a Splunk instance. Tests can also be run in playback mode by setting
MockContext.ModetoPlaybackinApp.Config.
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 more about the Splunk REST API, see the REST API Reference.
-
For more about about Splunk in general, see Splunk>Docs.
Stay connected with other developers building on Splunk.
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. Send an email to [email protected] and include "Splunk SDK for C# PCL" in the subject line.
-
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 csharp tags to identify your questions)
- Splunkdev Google Group
-
Splunk will NOT provide support for the extension if the core library (the code in the '1. src' 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 code—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.