Metrics Platform/How to/Choose your language/Setup for Java

From Wikitech

Requirements

First, make sure you have completed the earlier steps:

  1. Metrics Platform/How to/Setup Mediawiki for Metrics Platform

Overview

The Java MPC is a standalone library that

  • requires the instantiation of a MetricsClient object, which accepts an instance of ClientMetadata in its constructor.
  • The ClientMetadata instance must provide app-specific getters for the values of contextual attributes.
  • As described in the Metrics Platform API, these values are submitted along with whatever custom data is passed into submitMetricsEvent.
  • The nested class method Builder.build of the enclosing MetricsClient class is responsible for instantiating an EventProcessor, a MetricsClient, and for fetching stream configurations.

Stream configurations are fetched periodically, with frequency defined by streamConfigFetchInterval in class MetricsClient, which also periodically processes the submission of queued events to the destination event intake service. If stream configurations are not yet available, queued events are held temporarily in the event queue (input buffer) per available space (as allocated in eventQueue's definition in MetricsClient, which can be overridden using method eventQueueCapacity).

If the event queue is full, events are dropped from the queue with a logged warning (from MetricsClient method submit). The metrics client will continue to send queued events to the destination event service at regular intervals (defined by sendEventsInterval). Successfully submitted events are removed from the event queue. Failed event submissions produce an error and remain in the event queue to be retried on the next queued events submission attempt.

Writing MediaWiki instrumentation code using the EventLogging extension

A Metrics Platform instrument is creating by calling one of the submit API methods provided by the MP library. These methods can take the following arguments:

  • streamName, a string, is required.
  • schemaId, a string, is optional/required depending on which submit method is used.
  • action, a string, is optional/required depending on which submit method is used.
  • InteractionData, a group of key/value pairs, is optional. If it's present, each key must be in snake case, using only lowercase letters, digits, and '_', and starting with a lowercase letter.

The available keys that can be used for InteractionData:

  • action_subtype
  • action_source
  • action_context
  • element_id
  • element_friendly_name
  • funnel_name
  • funnel_entry_token
  • funnel_event_sequence_position

Each value must be a string with the exception of funnel_event_sequence_position which is required to be an integer (this constraint is codified in the definition of common product metrics in the product_event YAML file. If additional types are supported in future, those types will be added there.)

Writing MediaWiki instrumentation code for apps

The Metrics Platform Java client library operates similarly to the other libraries in that different submit methods can be used to submit event data to the Metrics Platform. For example, once a MetricsClient object is instantiated, the methods MetricsClient::submitClick and MetricsClient::submitInteraction can be invoked to submit an event to the Metrics Platform, with zero or more interactionData elements (key / value pairs). The syntax of keys and the types of values are constrained in the same way described for JavaScript above.

// Parameters derived from client at instantiation of the Metrics Client object with options to pass in dynamic arguments at the time of event submission
ClientData clientData = new ClientData(
   agentData,
   pageData,
   mediawikiData,
   performerData,
);
InteractionData interactionData = new InteractionData(
   'action_value',
   'action_subtype_value',
   'action_source_value',
   'action_context_value',
);

metricsClient.submitClick(clientData, interactionData);

To use MetricsClient::submitInteraction with a custom schema:

Map<String, Object> customData = new HashMap<String, Object>();
customData.put("font_size", "small");
customData.put("is_full_width", true);
customData.put("screen_size", 1080);

metricsClient.submitInteraction(
   "custom_schema_id",
   "some_prefix.some_event_name",
   clientData,
   interactionData,
   customData
);

See Metrics_Platform/Implementations#Language-specific_Notes_and_Key_Differences for additional details about the Java library.

Next

Deploy your instrument

Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=Metrics_Platform/How_to/Choose_your_language/Setup_for_Java&oldid=2151600"