Interana provides a set of RESTful APIs as part of the External API. These APIs are language/platform agnostic.
The purpose of this article is to specifically assist in creating a language-specific implementation that can be used for your custom scenario. After completing this how-to, you will have ready-to-run code capable of querying Interana using the supported Interana APIs.
Assuming you have an Interana environment available, ensure that you can access the environment and can run queries using the UI. If you don't know the URL or don't have an environment, contact Interana Support (for Production environments) or your friendly Interana Solution Architect (for POC environments).
Interana dataset name
Access your Interana Environment and find the table or dataset to use for your queries.
You must have an authorization token to access the Interana API. This will allow you to access the API and pass the authentication step.
Contact Interana Support
This is the recommended path. This will be as simple as sending a quick email to Interana Support to request a token. Keep this token safe, since it can't be generated again.
Install the Python SDK
The Python SDK is available on PyPI as a direct download. For further details, pl. see the SDK sources.
pip install interanasdk
Installing this package provides a python SDK for easy access to the Interana Query APIs documented here. In addition, there is a utility (
ia_query_client) installed to allow for shell-level access to the APIs.
Note: This is a community supported SDK and we're providing it on a best-effort basis only. Interana will not provide support for this SDK.
This section describes how to create an implementation in Python.
We will use the Query SDK to assist in querying via Python. There are four main actions involved when attempting to query Interana using this SDK:
- Create an Interana client object
- Generate an Interana query object
- Tune the query, if needed
- Retrieve the results from Interana
Create an Interana client object
To get started, we will create an Interana client object. The purpose behind this step is to establish a connection to the Interana cluster that you will be querying from. To do this, start simply by specifying cluster host and the authorization token (from above). For eg:
from interanasdk import Client url = "<cluster domain here without no http(s) or slashes>" token = "<your authorization token>" client = Client(url, token)
Generate an Interana query object
Next, initialize a query object using the SDK. This step helps define and formulate the query to retrieve the data. Key info. needed will be the dataset to query against (from above), date range (assuming the querying is from X days back to now). Assumption will be a base query type (number visualization in Interana) and base aggregator type ("count *").
import datetime from interanasdk import Query dataset = "<your dataset name>" days_prior = 7 end_time = datetime.datetime.now() start_time = end_time - datetime.timedelta(days=days_prior) query = Query(dataset, start_time, end_time) query_type = "single_measurement" agg_type = "count_star" ia_col = "" query.add_query_info(type=query_type,aggregator=agg_type,column=ia_col)
Tune the query
Now you can filter the query object or issue group-by requests or change the query type. This step is not mandatory but can be used to further filter the query. Or do a group by to visualize the data differently. See the External API reference for more information about the parameters.
filter = "(`event` != \"userlogin\")" query.add_query_info(type=query_type, aggregator=agg_type, column=ia_col, filter=filter_expr) groupby_col = "event" query.add_params(group_by=[groupby_col])
Retrieve results from Interana
Issue the request to the Interana backend to retrieve the result set for your query. This is the final step to actually get the dataset for the query defined.
result = client.query(query) print result
Putting it all together: sample code
The complete code will look similar to the following:
#!/usr/bin/env python import datetime from interanasdk import Client, Query, InteranaError url = "salesdemo.interana.com" token = "Kl72RslnaXniep82kxgTbnlR5D77qPqchpPIUtuKcxpx21gbdheXd9mikfUh1pFyx1bUOK67V+S8Q19c0fgYPlJ7arrD0000" client = Client(url, token) dataset = "music" days_prior = 7 end_time = datetime.datetime.now() start_time = end_time - datetime.timedelta(days=days_prior) query = Query(dataset, start_time, end_time) query_type = "single_measurement" agg_type = "count_star" ia_col = "" query.add_query_info(type=query_type,aggregator=agg_type,column=ia_col) try: result = client.query(query) print result except InteranaError as e: print "Interana Error Recieved:" print "Error Code: %s, Error Details: %s" % (e.code,e.error) except Exception as ex: print "Exception Recieved:" print ex
Use the Interana SDK utility
Alternatively, as part of the install, use the helper script that leverages the SDK and provides an easy to use wrapper utility to access the Interana APIs directly. For more details on the implementation of the utility, look here.
$ ia_query_client -h usage: ia_query_client [-h] [-d DAYS_PRIOR] [-t QUERY_TYPE] [-a AGGREGATOR] [-c COLUMN_NAME] [-g GROUP_BY] [-f FILTERS] [-o OUTPUT_FILE] [-v] auth_token cluster_domain dataset
Additional language-specific implementations like R, MS-Excel, will be provided in the future.