Help:Extension:EventStreamConfig

From mediawiki.org
Languages:
PD Note: When you edit this page, you agree to release your contribution under the CC0. See Public Domain Help Pages for more info. PD

This EventStreamConfig extension provides library functions and an API endpoint for exporting event stream configuration from the $wgEventStreams MediaWiki configuration variable.

This allows for centralized configuration of streams for both MediaWiki and external uses.

  • The EventLogging extension uses this with ResourceLoader to load configs for streams used on certain pages to dynamically configure client stream settings, like sample rate.
  • Mobile apps use the API endpoint to dynamically configure client stream settings like sample rate.
  • EventGate event intake service(s) use this to ensure that only events of a specific schema title are allowed into a stream.
  • EventBus and other server side event producers uses this to figure out which event intake service a given stream should be produced to.

Usage[edit]

MediaWiki Config[edit]

$wgEventStreams is a list of individual stream configs. Each stream config must minimally specify its schema_title and its stream name settings. In $wgEventStreams, stream may either be a static stream name string, or a regex that matches stream names for which the stream config should be used.

Example:

$wgEventStreams = [
    'test.event' => [
        'stream' => 'test.event',
        'schema_title' => 'test/event',
        'sample_rate' => 0.15,
    ],
    'nonya' => [
        'stream' => 'nonya',
        'schema_title' => 'mediawiki/nonya',
        'sample_rate' => 0.5,
    ],
    'mediawiki.virtual_page_view' => [
        'stream' => 'mediawiki.virtual_page_view',
        'schema_title' => 'mediawiki/page/virtual-view',
        'sample_rate' => 0.1,
    ],
    '/^mediawiki.edit(\..+)?/' => [
        'stream' => '/^mediawiki.edit(\..+)?/',
        'schema_title' => 'mediawiki/edit',
        'sample_rate' => 0.8,
    ],
];

(Note: sample_rate is just an example setting)

Getting configs for a list of streams[edit]

StreamConfigs#get takes a list of stream names to return configs for. $wgEventStreams is keyed by stream name or stream regex pattern, and it is searched for stream names that match. The return value is a map from requested stream name to the matched stream config. By default any settings in StreamConfig::INTERNAL_SETTINGS are removed from the returned stream configs; as they are often not useful for client side configuration. The $includeAllSettings parameter disables this behavior.

Example:

$streamConfigs = MediaWikiServices::getInstance()->getService('EventStreamConfig.StreamConfigs');
$streamConfigs->get( ['test.event', 'mediawiki.edit.cohort1'] );

returns

[
   'test.event' => [
       'sample_rate' => 0.15,
   ],
   'mediawiki.edit.cohort1' => [
       'sample_rate' => 0.8,
   ]
]

streamconfigs MW API endpoint[edit]

curl http://wiki.domain.org/w/api.php?action=streamconfigs&format=json&streams=test.event|mediawiki.edit.cohort1
# returns
{
    "test.event" => {
        "sample_rate" => 0.15
    },
    "mediawiki.edit.cohort1": {
        "sample_rate" => 0.8
    }
}