Help:Extension:EventStreamConfig

From mediawiki.org
Jump to navigation Jump to search

EventStreamConfig[edit]

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 = [
    [
        'stream' => 'test.event',
        'schema_title' => 'test/event',
        'sample_rate' => 0.15,
    ],
    [
        'stream' => 'nonya',
        'schema_title' => 'mediawiki/nonya',
        'sample_rate' => 0.5,
    ],
    [
        'stream' => 'mediawiki.virtual_page_view',
        'schema_title' => 'mediawiki/page/virtual-view',
        'sample_rate' => 0.1,
    ],
    [
        'stream' => '/^mediawiki.edit(\..+)?/',
        'schema_title' => 'mediawiki/edit',
        'sample_rate' => 0.8,
    ],
];
</source>

(Note: <code>sample_rate</code> is just an example setting)

=== Getting configs for a list of streams ===

<code>StreamConfigs#get</code> takes a list of stream names to return configs for.  The <code>$wgEventStreams</code>
array is searched in order for the first <code>stream</code> that matches.  The return value
is a map from requested stream name to the matched stream config. By default
any settings in <code>StreamConfig::INTERNAL_SETTINGS</code> are removed from the returned
stream configs; as they are often not useful for client side configuration.
The <code>$includeAllSettings</code> parameter disables this behavior.

Example:

<syntaxhighlight lang="php">

$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
    }
}