Metrics Platform/How to/Deploy your instrument

Deployment

Once your instrumentation code has been tested, reviewed and merged, you are ready for deployment, which involves creating a stream and associating it with the event name(s) used by your instrument(s). To create a new stream, you will make some changes to the mediawiki-config repository to declare and configure the stream, and register it for use by the Metrics Platform.

Event streams are declared using the wgEventStreamsand wgEventLoggingStreamNames config variables. Metrics Platform streams have the same form, and appear in the same configuration files, as other Event Platform streams, but there are a couple requirements on the content to associate them with the Metrics Platform. These requirements are explained in Metrics Platform/Creating a Stream Configuration.

You will edit these variables in wmf-config/ext-EventStreamConfig.php (for production and beta clusters) or wmf-config/InitialiseSettings-labs.php (for beta only). ext-EventLogging.php will be used in both beta and production if no corresponding values are found in InitialiseSettings-labs.php. See Configuration files for additional information about the use of these files.

(Note: in a local development environment, these variables are normally declared in LocalSettings.php.)

Stream Configuration

We'll create a new Metrics Platform event stream called mediawiki.interwiki_link_hover. First, declare your stream in the wgEventStreams config variable, in one of the config files mentioned above.

<?php

// …

'wgEventStreams' => [
	'default' => [

		// …

        'mediawiki.interwiki_link_hover' => [
            'schema_title' => 'analytics/product_metrics/web/base',
			'destination_event_service' => 'eventgate-analytics-external',
            'producers' => [
                'metrics_platform_client' => [
                    // The contextual attributes that should be mixed into the event
                    // before it is submitted to this stream.
                    'provide_values' => [
                        "page_id",
			            "page_title",
        				"page_revision_id",
                        'mediawiki_is_production',
                    ],
                ],
            ],
	    ],
    ],
],

// …

In this example, showing the declaration of stream mediawiki.interwiki_link_hover, we see that schema_title specifies the Metrics Platform web base schema, the only schema option for use with Metrics Platform. We state that the Metrics Platform client should include the 4 contextual attributes page_id, page_title, page_revision_id, and mediawiki_is_production in the events it produces. See the definition of context_attribute in metrics_platform_client.schema.json for a complete list of supported contextual attributes.

See Metrics Platform/Creating a Stream Configuration for additional details regarding Metrics Platform stream configuration.

Register your stream for use

Next, list your stream in wgEventLoggingStreamNames so that Metrics Platform (by way of the EventLogging extension) will get the config for your stream and be able to produce these events.

'wgEventLoggingStreamNames' => [
	'default' => [
		// ...
		'mediawiki.interwiki_link_hover',
	],
],

If you've made these changes in InitialiseSettings-labs.php, you can find a reviewer to just merge your change and the config will be automatically synced to the beta cluster. If your instrumentation code changes are also merged, you'll then be sending these events in the beta environment.

If you've made these changes in ext-EventLogging.php, you'll need to schedule a Backport window deployment to sync out your config change to the production cluster. See Deployments and Backport windows for instructions.