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 only works from the UI thread of the Browser process.
Use a service connector and get a MojoUkmRecorder.
ukm::mojom::UkmRecorderInterfacePtr interface; service_connector->BindInterface( content::mojom::kBrowserServiceName, mojo::MakeRequest(&interface)); ukm::MojoUkmRecorder ukm_recorder(std::move(interface));
Note: This will eventually move out of the browser service.
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.
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. 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.