This describes how to write client code to collect UKM data. Before you add new metrics, you should file a proposal. See go/ukm for more information.
Any events and metrics you collect need to be documented in //tools/metrics/ukm/ukm.xml
Important information to include:
<event name="GoatTeleported"> <owner>teleporter@chromium.org</owner> <summary> Recorded when a page teleports a goat. </summary> <metric name="Duration"> <summary> How long it took to teleport, in ns. </summary> </metric> <metric name="Mass"> <summary> The mass of the teleported goat, in kg, rounded to the nearest multiple of 10. </summary> </metric> </event>
In order to record UKM events, your code needs a UkmRecorder object, defined by //services/metrics/public/cpp/ukm_recorder.h
There are two main ways of getting a UkmRecorder instance.
Use ukm::UkmRecorder::Get(). This currently only works from the Browser process.
Use a service connector and get a MojoUkmRecorder.
std::unique_ptr<ukm::MojoUkmRecorder> ukm_recorder = ukm::MojoUkmRecorder::Create(context()->connector()); ukm::builders::MyEvent(source_id) .SetMyMetric(metric_value) .Record(ukm_recorder.get());
UKM identifies navigations by thier source ID and you'll need to associate and ID with your event in order to tie it to a main frame URL. Preferrably, get an existing ID for the navigation from another object.
The main methods for doing this are using one of the following methods:
ukm::SourceId source_id = GetSourceIdForWebContentsDocument(web_contents); ukm::SourceId source_id = ukm::ConvertToSourceId( navigation_handle->GetNavigationId(), ukm::SourceIdType::NAVIGATION_ID);
Currently, however, the code for passing these IDs around is incomplete so you may need to temporarily create your own IDs and associate the URL with them. However we currently prefer that this method is not used, and if you need to setup the URL yourself, please email us first at ukm-team@google.com. Example:
ukm::SourceId source_id = ukm::UkmRecorder::GetNewSourceId(); recorder->UpdateSourceUrl(source_id, main_frame_url);
Helper objects for recording your event are generated from the descriptions in ukm.xml. You can use them like so:
#include "services/metrics/public/cpp/ukm_builders.h" void OnGoatTeleported() { ... ukm::builders::GoatTeleported(source_id) .SetDuration(duration.InNanoseconds()) .SetMass(RoundedToMultiple(mass_kg, 10)) .Record(ukm_recorder); }
Build chromium and run it with ‘--force-enable-metrics-reporting’. Trigger your event and check chrome://ukm to make sure the data was recorded correctly.
You can pass your code a TestUkmRecorder (see //components/ukm/test_ukm_recorder.h) and then use the methods it provides to test that your data records correctly.