SNIPPETS

This section helps you to get hands on experience on the basic functions of EventLog_Analyzer_API

 

To start a connection

You can initiate the connection with the below command

 

  1. from connection import *

 

To create connection object

  1. c = Connection()
  2. conn = c.open_connection()

 

You can now use this conn object to access the search APIs

Note: Always assign a connection object to a variable instead of doing it inline. At a later point,the variable will be useful to close the connection.

 

 

Setting the Request Objects

After establishing the connection,you need to verify the API key with the server and set it in the request object as follows:

 

  1. reqObj = Request()
  2. reqObj.key = auth.get_key("client/")

 

Closing the connection

Now that the connection has been established and request object has been set,you can proceed with your code. Once you are done, close the connection with the following command

 

  1. c.close_connection()

 

Performing a simple search

  1. Set the request object
  1. reqObj = Request()
  2. reqObj.startTime = "2014-01-01 00:00"
  3. reqObj.endTime = "2014-01-01 23:59"
  4. reqObj.query = "HOSTNAME = twister"

 

  1.  Then call the Search API through the client object.
  1. response = conn.search(reqObj)

 

  1. Finally, read the results from the response object.
  1. result = response.result

                

  1. If no results are found, then a SearchException : no hits got / end of search is thrown
Note:
Results are a list of map wherein each entry is a record and each record contains fieldsd and its corresponding values. By default the result contains 10 records. You can change this by setting the count in the following response object:
reqObj.requiredHitsCount = myCount
Replace the value 'myCount' with your own count value.     
Note on Time Parameters
If you have not specified the start and end time, then the search is automatically performed from the current date to the current time. 
If only the start time is specified, then the search is carried out from that time to the current time

 

Getting sorted results

If you want the result to be sorted with respect to a specific field, then you can do that with the following commands:

 

  1. reqObj = Request()
  2. reqObj.startTime = "2014-01-01 00:00"
  3. reqObj.endTime = "2014-01-01 23:59"
  4. reqObj.query = "*"
  5. reqObj.sortByFieldName = "<YOUR_FIELD_NAME>"
  6. response = conn.search (reqObj)
  7. result = response.result

           
Command Output: With this set of commands, your search results from 2014-01-01 00:00 to 2014-01-01 23:59 will be sorted based on the given field name specified in the place <YOUR_FIELD_NAME>

Note: If the specified field name does not exist, then a 'SearchException: The field <field name> does not exist' is thrown

 

Getting distinct fields for a query
 If you want to find the distinct values in a specific field, then you can do that with the following commands:

 

  1. reqObj = Request()
  2. reqObj.startTime = "2014-01-01 00:00"
  3. reqObj.endTime = "2014-01-01 23:59"
  4. reqObj.query = "*"
  5. reqObj.needDistinctOf = "<YOUR_FIELD_NAME>"
  6. response = conn.search (reqObj)
  7. result = response.distinctFields

 

Command Output: Now you get the distinct values of the field <YOUR_FIELD_NAME> specified from 2014-01-01 00:00 to 2014-01-01 23:59  

Note: If the specified field name does not exist, then a 'SearchException: The field <field name> does not exist' is thrown

 

Getting facets for a query
 In addition to the simple search, if you want to set the field name to findthe facets, facet count and top/bottom facet in the request object, then you can do that by executing the commands as below:

  1. reqObj = Request()
  2. reqObj.startTime = "2014-01-01 00:00"
  3. reqObj.endTime = "2014-01-01 23:59"
  4. reqObj.query = "*"
  5. reqObj.facetByField = "SEVERITY"
  6. reqObj.facetCount = 10
  7. reqObj.topFacet = True
  8. response = conn.search (reqObj)
  9. result = response.facetFieldValues

 

Command Output: The result now contains the top 10 facets of the specified field with its corresponding count.

 

 

Note: If the specified field name does not exist then a 'SearchException: The field <field name> does not exist' is thrown

 

Exporting search results to CSV

To export the search results as CSV file, set the command 'reqObj.CSVNeeded' as true. CSV files will be generated for the subsequest searches, until you set the value as 'false'.  Refer to the steps here, to specify the location wherein the CSV files have to be saved

 

  1. reqObj = Request()
  2. reqObj.startTime = "2014-01-01 00:00"
  3. reqObj.endTime = "2014-01-01 23:59"
  4. reqObj.query = "*"
  5. reqObj.CSVNeeded = True
  6.  
  7. response = conn.search (reqObj)
  8. result = response.facetFieldValues

 

Command Output: The 'result' contains the path of exported files.

 

Note: If the specified CSV location path could not be accessed, then a 'SearchException: Error writing to csv file' is thrown

 

Pagination

A simple search gives you the first N result records/ If you want the next set of records, then you need to perform the search by setting the paging information in the previous response of  the current request object.

 

  1. reqObj = Request()
  2. reqObj.startTime = "2014-01-01 00:00"
  3. reqObj.endTime = "2014-01-01 23:59"
  4. reqObj.query = "*"
  5. reqObj.requiredHitsCount = 10
  6. response = conn.search (reqObj)
  7. result = response.result

 

Command Output: The 'result'  displays the first page of the search result. 

 

If you want to move to the next set of results (forward pagination), then execute the below command:

 

  1. reqObj.forwardSearch = True
  2. while(notEndOfSearch):
  3. reqObj.pagingInfo = response.pagingInfo
  4. result = response.result

 

If you want the previous set of results (backward pagination), then execute the below command:

 

  1. reqObj.forwardSearch = False
  2. while(notEndOfSearch):
  3. reqObj.pagingInfo = response.pagingInfo
  4. result = response.result

 

Note:
A  'SearchException'  is thrown if overflow/underflow conditions occur.
If the result end is reached, then paging does not stop, but throws an exception. We recommend the developers to take care of the boundary conditions (overflow/underflo) by checking the count agains the 'totalCount' in the response object.

 

Getting the available fields

The below command allows you to get the list of fields upon which the search operations can be performed

 

  1. fields = response.searchableFields

 

Note: The 'fields' value got from this command are not exhaustive. It contains all the fields that are common to a lot of records.

 

Getting only the meta information and not the entire search data

To get just the meta information about the search (like searchable fields, facets, search count etc., ) and not the entire search data, you can set the recordsNeeded field as false as below:

 

  1. reqObj.recordsNeeded = false

 

Note: This count information is approximate and tends towards the exact value for every iteration of the search. We recommend the developers to update the count everytime when checking for overflows/underflows while pagination

 

Authentication Method

 

As you install the EventLog_Analyzer_API server, you will be given with the Authentication certificate. Any EventLog_Analyzer_API client that wants to access the API server need to have this certificate. Access to the server is restricted in the absence of authentication certificate. Every API call is processed by the Search Server only if the Client has the aforementioned certificate.

 

Steps involved in Authentication

Every API Client generates a key with the authentication certificate using the 'auth module' as below:

 

  1. reqObj.key = auth.get_key(/pathget_key/to/certificate)


The API Server calculates the key using its certificate and proceed further operations only if both the keys match. If the keys doesn't match then 'SearchException:Certificate error! Contact your Sysadmin!' is thrown.