Revamp docs as UBI has evolved. #8800
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Eric Pugh <[email protected]>
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 <[email protected]>
Signed-off-by: Eric Pugh <[email protected]>
Signed-off-by: Eric Pugh <[email protected]>
|
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. |
kolchfa-aws
reviewed
Dec 16, 2024
There was a problem hiding this comment.
@epugh Please see my comments and let me know if you have any questions. Thanks.
| @@ -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.
Suggested change
| | [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.
Suggested change
| - [`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?
Suggested change
| - [`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.
Suggested change
| - `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.
Suggested change
| - `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.
Suggested change
| ``` | |
| ```js |
| } | ||
| return id; | ||
| }; | ||
| ``` |
There was a problem hiding this comment.
Suggested change
| ``` | |
| ``` | |
| {% include copy.html %} |
|
|
||
| ## Tracking the event | ||
|
|
||
| Sending the event to the backend is as simple as: |
There was a problem hiding this comment.
Suggested change
| 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.
Suggested change
| 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.
Suggested change
| This looks very similar to tracking events: | |
| The code is similar to tracking events: |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.