feat(#9489): collect telemetry for offline freetext searching #9525

m5r · 2024-10-10T17:12:23Z

Description

This PR adds telemetry collection for searches without storing any PII/PHI by storing only the properties that matched against the query.
It would have been more straightforward to edit the views and make it emit the property that matched but that meant re-indexing medic-client for 0 immediate benefit to the end users. So instead I hooked into webapp code to record a telemetry entry after the user selected a contact/report from the search results.

Code review checklist

Readable: Concise, well named, follows the style guide, documented if necessary.
Documented: Configuration and user documentation on cht-docs
Tested: Unit and/or e2e where appropriate
Internationalised: All user facing text
Backwards compatible: Works with existing data and configuration or includes a migration. Any breaking changes documented in the release notes.

Compose URLs

If Build CI hasn't passed, these may 404:

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

m5r · 2024-10-22T13:32:57Z

This is an example of what a telemetry sample with this new metric would look like

{
  "_id": "telemetry-2024-10-21-chw-0aadf69e-aa28-4504-ad39-22790755f763",
  "_rev": "1-0fc9e7509e3898e2eb5669bd1f0dcbaa",
  "type": "telemetry",
  "metrics": {
    "search_match:contacts_by_freetext:name": {
      "sum": 7,
      "min": 1,
      "max": 1,
      "count": 7,
      "sumsqr": 7
    },
    "search_match:contacts_by_freetext:patient_id": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:contacts_by_freetext:patient_id:$value": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:contacts_by_freetext:phone": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:contacts_by_freetext:phone:$value": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:contacts_by_type_freetext:name": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:contacts_by_type_freetext:name:$value": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:contacts_by_type_freetext:phone": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:reports_by_freetext:contact:$value": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:content_type": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:content_type:$value": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:fields.patient_id": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:reports_by_freetext:fields.patient_name": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:fields.patient_short_name": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:fields.patient_short_name_start": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:fields.patient_uuid": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:reports_by_freetext:form": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:form:$value": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:from": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:reports_by_freetext:from:$value": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:patient_age_in_years:$value": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:patient_id:$value": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:reports_by_freetext:patient_name:$value": {
      "sum": 2,
      "min": 1,
      "max": 1,
      "count": 2,
      "sumsqr": 2
    },
    "search_match:reports_by_freetext:patient_uuid:$value": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    },
    "search_match:reports_by_freetext:t_danger_signs_referral_follow_up:$value": {
      "sum": 1,
      "min": 1,
      "max": 1,
      "count": 1,
      "sumsqr": 1
    }
  }
}

…hared the same scope

…textRequest.params.key`

…` view

m5r · 2024-10-24T17:39:10Z

shared-libs/search/src/generate-search-requests.js

@@ -191,7 +191,7 @@ const sortByLastVisitedDate = () => {
 const makeCombinedParams = (freetextRequest, typeKey) => {
  const type = typeKey[0];
  const params = {};
-  if (freetextRequest.key) {
+  if (freetextRequest.params.key) {


This is a fix for key:value queries against the view contacts_by_type_freetext. Without this, these queries would fail silently and the select2 input would show an infinite loader until a different query would return results. If this has never been noticed before I believe the key:value search feature isn't used very much...

webapp/src/ts/modules/contacts/contacts-content.component.ts

m5r · 2024-10-24T17:41:51Z

webapp/src/ts/modules/contacts/contacts-content.component.ts

      selectedContact,
      forms,
      loadingContent,
      loadingSelectedContactReports,
      contactsLoadingSummary,
      filters,
    ]) => {
+      this.recordSearchTelemetry(this.selectedContact, selectedContact, filters);


We don't need to block the main thread by awaiting for this promise here, it can run in the background just fine

I have seen it suggested that if you have a promise in TS code that you deliberately do not want to await, you preface it with void:

void this.recordSearchTelemetry(this.selectedContact, selectedContact, filters);

I don't think we have done this much, but maybe it is time to start?

Seems like we should either do that, or leave an inline comment so future us does not think we just forgot the await...

I've only ever seen the void operator used in minified JS code to shorten undefined to void 0 and gain 3 bytes for each occurrence 😂

But looking into your suggestion, it seems to be what typescript devs @ microsoft recommend when you want to fire and forget a promise

+1 to start doing that

m5r · 2024-10-24T17:49:14Z

webapp/src/ts/services/select2-search.service.ts

@@ -77,17 +83,39 @@ export class Select2SearchService {
    this.searchService
      .search('contacts', filters, searchOptions)
      .then((documents) => {
-        if (currentQuery === params.data.q) {


This would always be true because currentQuery is defined and assigned a value in the same scope here. By pulling it into a class field, it can now be used to discard outdated results

tatilepizs

Looks great @m5r thank you for reorganizing the telemetry.wdio-spec.js test ⭐
I only left one comment, that is not a blocker

PS: I only checked the tests section.

tests/e2e/default/telemetry/telemetry.wdio-spec.js

jkuester

Very nice! Great e2e tests!

jkuester · 2024-10-25T20:44:25Z

webapp/src/ts/modules/reports/reports-content.component.ts

    ]) => {
+      this.recordSearchTelemetry(this.selectedReports, selectedReport, filters);


Can we get some unit tests for this behavior?

jkuester · 2024-10-25T20:48:48Z

webapp/src/ts/modules/contacts/contacts-content.component.ts

      selectedContact,
      forms,
      loadingContent,
      loadingSelectedContactReports,
      contactsLoadingSummary,
      filters,
    ]) => {
+      this.recordSearchTelemetry(this.selectedContact, selectedContact, filters);


I have seen it suggested that if you have a promise in TS code that you deliberately do not want to await, you preface it with void:

void this.recordSearchTelemetry(this.selectedContact, selectedContact, filters);

I don't think we have done this much, but maybe it is time to start?

jkuester · 2024-10-25T20:49:43Z

webapp/src/ts/modules/contacts/contacts-content.component.ts

      selectedContact,
      forms,
      loadingContent,
      loadingSelectedContactReports,
      contactsLoadingSummary,
      filters,
    ]) => {
+      this.recordSearchTelemetry(this.selectedContact, selectedContact, filters);


Seems like we should either do that, or leave an inline comment so future us does not think we just forgot the await...

jkuester · 2024-10-25T20:51:44Z

webapp/src/ts/modules/contacts/contacts-content.component.ts

      selectedContact,
      forms,
      loadingContent,
      loadingSelectedContactReports,
      contactsLoadingSummary,
      filters,
    ]) => {
+      this.recordSearchTelemetry(this.selectedContact, selectedContact, filters);


Can we get some unit tests for this logic?

jkuester · 2024-10-25T21:15:46Z

webapp/src/ts/services/select2-search.service.ts

+  private selectEl;
+  private currentQuery: string | null = null;
+  private onContactSelect;


I don't think it is going to work to have this state here at the service level. I double-checked and confirmed that if you have a form with more than one select-contact field, then the init function below is going to get called for each of the contact selectors in the form. (And this state will only be set for the last one).

Maybe I am missing something here, but is there a reason we cannot setup the select2:select event listener somewhere like the initSelect2 method (for each given selector) instead of doing it in the generic query method?

That's a good catch... I landed with registering this event listener in the query method because this is where I had access to the user's search to hook up with the contact the user would end up selecting.
I also couldn't find anything in select2 docs to retrieve the search text programmatically without writing code that looks like a pile of hacks with a mix of jQuery and DOM element querying 😅

But! I think I found a solution. I'll come back and resolve this convo if this works.

jkuester · 2024-10-25T21:26:05Z

webapp/src/ts/services/select2-search.service.ts

+          }
+
+          const doc = await this.getDoc(docId);
+          await this.searchTelemetryService.recordContactByTypeSearch(doc, search);


Minor, but technically I think this will only hit the contacts_by_type_freetext view if the types param above is valued. Otherwise, I guess shared-libs/search will just route this to contacts_by_freetext...

Right, but select2-search is only ever used to retrieve contacts by type, no?

Select2SearchService is initialized twice in the codebase. First occurrence in

cht-core/webapp/src/ts/modals/send-message/send-message.component.ts

Lines 174 to 189 in b7b2629

private initPhoneField($phone, initialValue) {

return Promise

.all([

this.settingsService.get(),

this.contactTypesService.getAll()

])

.then(([settings, contactTypes = []]) => {

const searchIds = contactTypes.map(type => type.id);

const personTypes = contactTypes

.filter(type => type.person)

.map(type => type.id);

const select2Options = this.getSelect2Options(settings, personTypes, contactTypes, initialValue);

return this.select2SearchService.init($phone, searchIds, select2Options);

});

}

And the second occurrence in

cht-core/webapp/src/ts/modals/edit-report/edit-report.component.ts

Lines 42 to 53 in 59b42e2

return this.contactTypesService

.getPersonTypes()

.then(types => {

const typeIds = types.map(type => type.id);

const options = {

allowNew: false,

initialValue: this.report?.contact?._id || this.report?.from,

};

return this.select2SearchService.init(this.getSelectElement(), typeIds, options);

})

.catch(err => console.error('Error initialising select2', err));

}

Both times it's initialized with the types parameter and then that gets translated into a query against medic-client/contacts_by_type in

cht-core/shared-libs/search/src/generate-search-requests.js

Lines 137 to 148 in 843888c

const contactTypeRequest = (filters, sortByLastVisitedDate) => {

if (!filters.types) {

return;

}

const view = 'medic-client/contacts_by_type';

let request;

if (filters.types.selected && filters.types.options) {

request = getRequestForMultidropdown(view, filters.types, getKeysArray);

} else {

// Used by select2search

request = getRequestWithMappedKeys(view, filters.types.selected, getKeysArray);

}

and its results get "merged" with the freetext query results in

cht-core/shared-libs/search/src/generate-search-requests.js

Lines 274 to 276 in 843888c

if (hasTypeRequest && freetextRequests?.length) {

return getCombinedContactsRequests(freetextRequests, contactsByParentRequest, typeRequest);

}

Select2Search is also inited by the db-object-widget:

cht-core/webapp/src/js/enketo/widgets/db-object-widget.js

Line 59 in 4547885

Select2Search.init($selectInput, contactTypes, { allowNew, filterByParent }).then(function() {

I did some double-checking and confirmed that when you use the select-contact appearance _without a type-* appearance, it will call through to just the contacts_by_freetext view (since the types in the search request are empty).

🫡 your enketo-fu is always appreciated, I'll handle this case

Okay I pushed what I think will cover this scenario but I'm about to drop off. I've noted to myself to manually test it and also add unit tests for this particular case

Okay there was no straightforward way to unit test this so I went for an e2e test 🙂

webapp/src/ts/services/search-telemetry.service.ts

…olon query

webapp/src/ts/services/select2-search.service.ts

…mise

m5r linked an issue Oct 16, 2024 that may be closed by this pull request

Add telemetry for offline freetext searching #9489

Open

m5r added 13 commits October 23, 2024 11:13

wip

991b281

remove unused code

77d84fd

collect telemetry for searches against the contacts_by_freetext view

95a8b77

change telemetry key

5cc183f

wip reports_by_freetext

913b1fc

wip contacts_by_type_freetext

0e2cafd

cleanup contacts_by_freetext telemetry

b76d85e

collect telemetry for searches against the reports_by_freetext view

5d21f72

fix currentQuery being always equal to params.data.q since they s…

6b94414

…hared the same scope

freetextRequest.key never exists, I think we were looking for `free…

843888c

…textRequest.params.key`

collect telemetry for searches against the `contacts_by_type_freetext…

de70aad

…` view

fix test

d7c322a

e2e test for contact search telemetry

bf001aa

m5r force-pushed the 9489-offline-search-telemetry branch from cd123a8 to bf001aa Compare October 23, 2024 10:16

m5r added 8 commits October 23, 2024 14:32

e2e test for report search telemetry

b5e5ee4

e2e test for contact_by_type search telemetry

bffd0a0

return early

abfd112

extract findMatchingProperties

5c241a7

ok sonar.

cea6292

is sonar happy with contacts-content.component.ts?

5589861

is sonar happy with reports-content.component.ts too?

19712b6

refactor 👍

a2d3fff

m5r marked this pull request as ready for review October 24, 2024 17:36

m5r commented Oct 24, 2024

View reviewed changes

webapp/src/ts/modules/contacts/contacts-content.component.ts Show resolved Hide resolved

m5r commented Oct 24, 2024

View reviewed changes

m5r requested a review from jkuester October 24, 2024 17:49

m5r requested a review from tatilepizs October 24, 2024 17:49

tatilepizs approved these changes Oct 25, 2024

View reviewed changes

tests/e2e/default/telemetry/telemetry.wdio-spec.js Show resolved Hide resolved

jkuester requested changes Oct 25, 2024

View reviewed changes

m5r added 7 commits October 28, 2024 13:09

refactor extra select2:select event listener

31d5b6b

don't bother looping over the doc fields when we have a key:value c…

a5a3b98

…olon query

move propertyPath initialization

ab8d9e5

revert db after telemetry test

b6e3b6b

use void keyword to mark promises as intentionally not awaited

bca463f

fix telemetry test

ef1918a

fix select2-search telemetry

6cdb9cc

m5r commented Oct 28, 2024

View reviewed changes

webapp/src/ts/services/select2-search.service.ts Show resolved Hide resolved

m5r added 10 commits October 28, 2024 21:07

remove void operator and add comment why we're not awaiting the pro…

e59da86

…mise

handle select2search case where it calls contacts_by_freetext

4b59c92

for..of => Promise.all

156457a

unit test report search telemetry

06a86b5

unit test contact search telemetry

ab8bf82

add e2e test for select2 without contact type

3ff8d1c

clean up e2e test

8bcd070

wow is sonar finally happy with void here?

2e75674

oops forgot some leftovers to clean up

32ddecc

clean up telemetry db before running our telemetry tests

857203f

m5r requested a review from jkuester October 30, 2024 18:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(#9489): collect telemetry for offline freetext searching #9525

feat(#9489): collect telemetry for offline freetext searching #9525

m5r commented Oct 10, 2024 •

edited by github-actions bot

Loading

m5r commented Oct 22, 2024

m5r Oct 24, 2024

jkuester Oct 25, 2024

m5r Oct 24, 2024

jkuester Oct 25, 2024

jkuester Oct 25, 2024

m5r Oct 28, 2024

m5r Oct 24, 2024

tatilepizs left a comment

jkuester left a comment

jkuester Oct 25, 2024

jkuester Oct 25, 2024

jkuester Oct 25, 2024

jkuester Oct 25, 2024

jkuester Oct 25, 2024

m5r Oct 28, 2024

jkuester Oct 25, 2024

m5r Oct 28, 2024

m5r Oct 28, 2024

jkuester Oct 28, 2024

m5r Oct 28, 2024

m5r Oct 28, 2024

m5r Oct 30, 2024

		]) => {
		this.recordSearchTelemetry(this.selectedReports, selectedReport, filters);

	private initPhoneField($phone, initialValue) {
	return Promise
	.all([
	this.settingsService.get(),
	this.contactTypesService.getAll()
	])
	.then(([settings, contactTypes = []]) => {
	const searchIds = contactTypes.map(type => type.id);
	const personTypes = contactTypes
	.filter(type => type.person)
	.map(type => type.id);
	const select2Options = this.getSelect2Options(settings, personTypes, contactTypes, initialValue);

	return this.select2SearchService.init($phone, searchIds, select2Options);
	});
	}

	return this.contactTypesService
	.getPersonTypes()
	.then(types => {
	const typeIds = types.map(type => type.id);
	const options = {
	allowNew: false,
	initialValue: this.report?.contact?._id \|\| this.report?.from,
	};
	return this.select2SearchService.init(this.getSelectElement(), typeIds, options);
	})
	.catch(err => console.error('Error initialising select2', err));
	}

	const contactTypeRequest = (filters, sortByLastVisitedDate) => {
	if (!filters.types) {
	return;
	}
	const view = 'medic-client/contacts_by_type';
	let request;
	if (filters.types.selected && filters.types.options) {
	request = getRequestForMultidropdown(view, filters.types, getKeysArray);
	} else {
	// Used by select2search
	request = getRequestWithMappedKeys(view, filters.types.selected, getKeysArray);
	}

	if (hasTypeRequest && freetextRequests?.length) {
	return getCombinedContactsRequests(freetextRequests, contactsByParentRequest, typeRequest);
	}

feat(#9489): collect telemetry for offline freetext searching #9525

Are you sure you want to change the base?

feat(#9489): collect telemetry for offline freetext searching #9525

Conversation

m5r commented Oct 10, 2024 • edited by github-actions bot Loading

Description

Code review checklist

Compose URLs

License

m5r commented Oct 22, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tatilepizs left a comment

Choose a reason for hiding this comment

jkuester left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m5r commented Oct 10, 2024 •

edited by github-actions bot

Loading