Usage monitoring

Viewing the logs

You can search the query and event log to find query sessions that match the specified criteria. Searching the logs endpoint uses the standard Discovery query syntax for the parameters that are supported. The endpoint provides basic query functionality for viewing and searching through the recorded data.

The /api/v1/logs endpoint supports the following Discovery query parameters.

• query
• filter
• sort
• count
• offset
• version

For additional details on the function and syntax for the parameters see Query parameters.

Example of searching logs for a natural language query that contains the term “train”:

{url}/v1/logs?version=2019-04-30&query=train

Replace {url} with your URL.

The response of a logs query includes results that appear similar to Discovery document results. Each result is either a query or event, specified in the document type field.

Example query log:

{
            "customer_id": "",
            "environment_id": "252e6e82-c2d2-450e-9670-0008b0a3a99c",
            "natural_language_query": "how do i get from the airport to the city",
            "query_id": "_Qs35yOoa7",
            "document_results": {
                "count": 2,
                "results": [
                    {
                        "collection_id": "af9e1f41-6114-4d77-bca6-c9b99b2601b1",
                        "score": 6.724753491503856,
                        "position": 1,
                        "document_id": "4193eaa727d79b0f74597356dbcbb9a7"
                    },
                    {
                        "collection_id": "af9e1f41-6114-4d77-bca6-c9b99b2601b1",
                        "score": 5.791631414211986,
                        "position": 2,
                        "document_id": "bdcd6a9cc1438a3faa8c925f6a8d9429"
                    }
                ]
            },
            "event_type": "query",
            "session_token": "1_LKczxWGEWx5TJAi1_Qs35yOoa7",
            "created_timestamp": "2018-09-12T05:20:07.469Z"
        }

With query logs you can investigate the type of results returned to your end users and investigate ways to improve result quality using the approaches available in Discovery. For example:

• relevancy training, see Improving result relevance with the API and Improving result relevance with the tooling
• query operators
• query expansion
• custom configurations, see the Configuration reference

Creating event logs

Event logs are used to track the interactions of users within your application. This can help you understand how well your application is performing, as well as identify areas that you might need to focus on to improve results. Discovery provides an API that can be embedded in your application to track events. Calling this API with the appropriate information when a user performs an action sends a signal back to Discovery, which can then be viewed in the logs.

Events can help gather information on computing metrics (like clickthrough rate) to measure how effective the application is at helping end users find relevant information, or can be used to help seed training by reviewing the queries and clicks to start to build ground truth.

You can add this API wherever users interact with your results. For example, in a search UI, you can add the API when a user clicks on a document link. In a chatbot interface, you can use the API to track when the user clicks on Expand or More details.

Discovery results return additional information that can be used for tracking events, including a session token.

"matching_results": 179, "session_token": "1_LKczxWGEWx59fYD0_VV8HFUpb6"

To record an event, make a POST to the /api/v1/events endpoint. See the Events API for details.

Once an event is recorded, it can be read back out using the /api/v1/logs endpoint. Join events to the associated query using the session_token.