Revamp docs as UBI has evolved. #8800
Conversation
Signed-off-by: Eric Pugh <epugh@opensourceconnections.com>
epugh
requested review from
kolchfa-aws,
Naarcha-AWS,
vagimeli,
AMoo-Miki,
natebower and
dlvenable
as code owners
|
Replaces #8799 which has signoff/rebase issues. |
|
Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Editorial review -> Merged. Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer. When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference). The doc reviewer will arrange for an editorial review. |
|
@jzonthemtn could you give a quick pass through on the tech side... I don't think much has changed! |
Signed-off-by: Eric Pugh <epugh@opensourceconnections.com>
Signed-off-by: Eric Pugh <epugh@opensourceconnections.com>
Signed-off-by: Eric Pugh <epugh@opensourceconnections.com>
|
This documentation PR is ready for review. |
|
I wanted to follow up and see if we could get this merged? |
|
@epugh Thanks for following up! I will review this week and put it through editorial review. Please tag me if you have any questions. |
There was a problem hiding this comment.
@epugh Please see my comments and let me know if you have any questions. Thanks.
_search-plugins/ubi/index.md
Outdated
| @@ -39,7 +41,7 @@ The UBI documentation is organized into two categories: *Explanation and referen | |||
| | Link | Description | | |||
| | :--------- | :------- | | |||
| | [UBI plugin](https://github.com/opensearch-project/user-behavior-insights) | How to install and use the UBI plugin. | | |||
| | [UBI client data structures]({{site.url}}{{site.baseurl}}/search-plugins/ubi/data-structures/) | Sample JavaScript structures for populating the event store. | | |||
| | [UBI JavaScript Collector]({{site.url}}{{site.baseurl}}/search-plugins/ubi/ubi-javascript-collector/) | Clientside JavaScript library to capture events. | | |||
There was a problem hiding this comment.
| | [UBI JavaScript Collector]({{site.url}}{{site.baseurl}}/search-plugins/ubi/ubi-javascript-collector/) | Clientside JavaScript library to capture events. | | |
| | [UBI JavaScript Collector]({{site.url}}{{site.baseurl}}/search-plugins/ubi/ubi-javascript-collector/) | A client-side JavaScript library for capturing events. | |
| @@ -16,8 +16,8 @@ The User Behavior Insights (UBI) data collection process involves tracking and r | |||
|
|
|||
| For UBI to function properly, the connections between the following fields must be consistently maintained within an application that has UBI enabled: | |||
|
|
|||
| - [`object_id`](#object_id) represents an ID for whatever object the user receives in response to a query. For example, if you search for books, it might be an ISBN code of a book, such as `978-3-16-148410-0`. | |||
| - [`query_id`](#query_id) is a unique ID for the raw query language executed and the `object_id` values of the _hits_ returned by the user's query. | |||
| - [`object_id`](#object_id) represents an ID for whatever object the user receives in response to a query. For example, if you search for books, it might be an ISBN number for a book, such as `978-3-16-148410-0`. | |||
There was a problem hiding this comment.
| - [`object_id`](#object_id) represents an ID for whatever object the user receives in response to a query. For example, if you search for books, it might be an ISBN number for a book, such as `978-3-16-148410-0`. | |
| - [`object_id`](#object_id) represents an ID for whatever object the user receives in response to a query. For example, if you search for books, it might be an ISBN for a book, such as `978-3-16-148410-0`. |
| - [`object_id`](#object_id) represents an ID for whatever object the user receives in response to a query. For example, if you search for books, it might be an ISBN code of a book, such as `978-3-16-148410-0`. | ||
| - [`query_id`](#query_id) is a unique ID for the raw query language executed and the `object_id` values of the _hits_ returned by the user's query. | ||
| - [`object_id`](#object_id) represents an ID for whatever object the user receives in response to a query. For example, if you search for books, it might be an ISBN number for a book, such as `978-3-16-148410-0`. | ||
| - [`query_id`](#query_id) is a unique ID for the raw query language executed and the `object_id` maps to the primary identifier of the _hits_ returned by the user's query. |
There was a problem hiding this comment.
Could we reword this? Query ID seems to be a unique ID for the raw query, correct? Not the query language?
| - [`query_id`](#query_id) is a unique ID for the raw query language executed and the `object_id` maps to the primary identifier of the _hits_ returned by the user's query. | |
| - [`query_id`](#query_id) is a unique ID for the raw query executed, while the `object_id` maps to the primary identifier of the _hits_ returned by the user's query. |
| @@ -138,11 +138,11 @@ All underlying query information and results (`object_ids`) are stored in the `u | |||
|
|
|||
| The `ubi_queries` index [schema](https://github.com/OpenSearch-project/user-behavior-insights/tree/main/src/main/resources/queries-mapping.json) includes the following fields: | |||
|
|
|||
| - `timestamp` (events and queries): A UNIX timestamp indicating when the query was received. | |||
| - `timestamp` (events and queries): A ISO 8601 formatted timestamp indicating when the query was received. | |||
There was a problem hiding this comment.
| - `timestamp` (events and queries): A ISO 8601 formatted timestamp indicating when the query was received. | |
| - `timestamp` (events and queries): An ISO 8601-formatted timestamp indicating when the query was received. |
|
|
||
| <p id="client_id"> </p> | ||
|
|
||
| - `client_id`: The client that issues the query. This is typically a web browser used by a unique user. | ||
| The `client_id` in both the **UBI queries** and **UBI events** indexes must be consistent. | ||
|
|
||
| - `timestamp`: When the event occurred, either in UNIX format or formatted as `2018-11-13T20:20:39+00:00`. | ||
| - `timestamp`: When the event occurred, using ISO 8601 format such as `2018-11-13T20:20:39+00:00Z`. |
There was a problem hiding this comment.
| - `timestamp`: When the event occurred, using ISO 8601 format such as `2018-11-13T20:20:39+00:00Z`. | |
| - `timestamp`: The time the event occurred in ISO 8601 format, such as `2018-11-13T20:20:39+00:00Z`. |
| The method `getQueryId()` refers to a helper method to generate a unique query id (and stores it in the session). | ||
| Here is a sample method: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ```js |
| } | ||
| return id; | ||
| }; | ||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ``` | |
| {% include copy.html %} |
|
|
||
| ## Tracking the event | ||
|
|
||
| Sending the event to the backend is as simple as: |
There was a problem hiding this comment.
| Sending the event to the backend is as simple as: | |
| You can send the event to the backend by calling the `trackEvent` method: |
|
|
||
| ## Tracking queries | ||
|
|
||
| You have the option of tracking queries using the client (instead of using the UBI plugin for OpenSearch). |
There was a problem hiding this comment.
| You have the option of tracking queries using the client (instead of using the UBI plugin for OpenSearch). | |
| You can optionally track queries using the client (instead of using the UBI plugin for OpenSearch). |
|
|
||
| You have the option of tracking queries using the client (instead of using the UBI plugin for OpenSearch). | ||
|
|
||
| This looks very similar to tracking events: |
There was a problem hiding this comment.
| This looks very similar to tracking events: | |
| The code is similar to tracking events: |
|
@epugh Just checking in on this PR. I'd like to get it through editorial review because UBI is part of 2.19 now. |
kolchfa-aws
added
backport 2.19
and removed
backport 2.18
Thanks for checking in. Let me add it to the list for next week to update the PR. One big thing is that we now have a "OpenSearch Ingestion" template for people to use, and that isn't part of this PR.... |
Signed-off-by: Eric Pugh <epugh@opensourceconnections.com>
| | [UBI index schema]({{site.url}}{{site.baseurl}}/search-plugins/ubi/schemas/) | Documentation on the individual OpenSearch query and event stores. | | ||
| UBI includes the following elements: | ||
| * [ubi.js](https://github.com/opensearch-project/user-behavior-insights/tree/main/ubi-javascript-collector/ubi.js): a client-side JavaScript library that captures searches and events. | ||
| * A machine-readable [schema](https://github.com/o19s/ubi) that faciliates interoperablity of the UBI specification. |
| | :--------- | :------- | | ||
| | [UBI Request/Response Specification](https://github.com/o19s/ubi/) | The industry-standard schema for UBI requests and responses. The current version references UBI Specification 1.0.0. | | ||
| | [UBI index schema]({{site.url}}{{site.baseurl}}/search-plugins/ubi/schemas/) | Documentation on the individual OpenSearch query and event stores. | | ||
| UBI includes the following elements: |
There was a problem hiding this comment.
Might be unclear when I'm new to UBI: Do I need all these elements?
I could imagine a diagram being helpful at the beginning of this page to show the recommended way of using UBI and how the different elements play together.
| <td> | ||
| <h2>Explanation</h2> | ||
| <ul> | ||
| <li><a href="https://UBISearch.dev">Why UBI?</a></li> |
There was a problem hiding this comment.
I think this page should answer "Why UBI?". If it doesn't no one will follow any link presented on this page.
Additionally, two links to the community page are not necessary.
| <td> | ||
| <h2>How To Guides</h2> | ||
| <ul> | ||
| <li><a href="https://github.com/opensearch-project/user-behavior-insights">How to install and use the UBI plugin</a><b>do we keep this</b></li> |
There was a problem hiding this comment.
The first item in the "How To Guides" section should take the user to the recommended way to use UBI.
I'm in favor of keeping the installation as plugin for now at least.
| <li><a href="{{site.url}}{{site.baseurl}}/search-plugins/ubi/ubi-dashboard-tutorial/">How to build a custom dashboard with UBI data.</a></li> | ||
| <li><a href="{{site.url}}{{site.baseurl}}/search-plugins/ubi/dsl-queries/">How to write queries for UBI data in OpenSearch query DSL.</a></li> | ||
| <li><a href="{{site.url}}{{site.baseurl}}/search-plugins/ubi/sql-queries/">How to write analytic queries for UBI data in SQL.</a></li> | ||
| <li><a href="https://github.com/o19s/chorus-opensearch-edition/blob/main/katas/006_protecting_sensitive_information.md">How to protect sensistive information when using UBI.</a> <small>Part of Chorus series.</small></li> |
There was a problem hiding this comment.
Do readers of the documentation know about the Chorus series? Is Part of Chorus series. a helpful information?
| <ul> | ||
| <li><a href="https://o19s.github.io/ubi/docs/html/1.2.0/query.request.schema.html">Query Tracking Specification</a></li> | ||
| <li><a href="https://o19s.github.io/ubi/docs/html/1.2.0/event.schema.html">Event Tracking Specification</a></li> | ||
| <li><a href="{{site.url}}{{site.baseurl}}/search-plugins/ubi/schemas/">UBI Plugin Schema</a><b>DO WE KEEP THIS</b></li> |
There was a problem hiding this comment.
I think it adds value as it gives an explanation to the schema. Having that said, I can see that this might be more of an explanation than a reference.
Description
UBI has evolved since it was first released in May 2024. This is an update of the documentation. We have introduced an explicit JS client, so we can streamline the documentation by referencing the deployed document.
Issues Resolved
Will solve opensearch-project/user-behavior-insights#61
Version
2.18
Frontend features
n/a
Checklist
For more information on following Developer Certificate of Origin and signing off your commits, please check here.