Page Menu
Home
WickedGov Phorge
Search
Configure Global Search
Log In
Files
F7416418
EventLogging.php
No One
Temporary
Actions
Download File
Edit File
Delete File
View Transforms
Subscribe
Flag For Later
Award Token
Size
10 KB
Referenced Files
None
Subscribers
None
EventLogging.php
View Options
<?php
/**
* PHP API for logging events.
*
* @file
* @ingroup Extensions
* @ingroup EventLogging
*
* @author Ori Livneh <ori@wikimedia.org>
*/
namespace
MediaWiki\Extension\EventLogging
;
use
MediaWiki\Context\RequestContext
;
use
MediaWiki\Deferred\DeferredUpdates
;
use
MediaWiki\Extension\EventLogging\EventSubmitter\EventSubmitter
;
use
MediaWiki\Extension\EventLogging\Libs\JsonSchemaValidation\JsonSchemaException
;
use
MediaWiki\Extension\EventLogging\Libs\JsonSchemaValidation\JsonTreeRef
;
use
MediaWiki\Extension\EventLogging\MetricsPlatform\MetricsClientFactory
;
use
MediaWiki\Json\FormatJson
;
use
MediaWiki\Logger\LoggerFactory
;
use
MediaWiki\MediaWikiServices
;
use
Psr\Log\LoggerInterface
;
use
RuntimeException
;
use
Wikimedia\MetricsPlatform\MetricsClient
;
class
EventLogging
{
/**
* @var MetricsClient|null
*/
private
static
$metricsPlatformClient
;
/**
* Default logger.
*
* @internal
*/
public
static
function
getLogger
():
LoggerInterface
{
return
LoggerFactory
::
getInstance
(
'EventLogging'
);
}
private
static
function
getEventSubmitter
():
EventSubmitter
{
return
MediaWikiServices
::
getInstance
()->
get
(
'EventLogging.EventSubmitter'
);
}
/**
* Gets the singleton instance of the Metrics Platform Client (MPC).
*
* @see https://wikitech.wikimedia.org/wiki/Metrics_Platform
*/
public
static
function
getMetricsPlatformClient
():
MetricsClient
{
if
(
!
self
::
$metricsPlatformClient
)
{
/** @var MetricsClientFactory $metricsClientFactory */
$metricsClientFactory
=
MediaWikiServices
::
getInstance
()->
getService
(
'EventLogging.MetricsClientFactory'
);
self
::
$metricsPlatformClient
=
$metricsClientFactory
->
newMetricsClient
(
RequestContext
::
getMain
()
);
}
return
self
::
$metricsPlatformClient
;
}
/**
* Resets the Metrics Platform Client for testing purposes. See also the warning and note
* against {@link MediaWikiServices::resetServiceForTesting()}.
*
* @internal
*
* @throws RuntimeException If called outside a PHPUnit test
*/
public
static
function
resetMetricsPlatformClient
():
void
{
if
(
!
defined
(
'MW_PHPUNIT_TEST'
)
)
{
throw
new
RuntimeException
(
__METHOD__
.
' may only be called during unit tests.'
);
}
self
::
$metricsPlatformClient
=
null
;
}
/**
* Submit an event according to the given stream's configuration.
*
* @param string $streamName
* @param array $event
* @param LoggerInterface|null $logger @deprecated since 1.40. All messages will be logged
* via the `EventLogging.Logger` service
*/
public
static
function
submit
(
string
$streamName
,
array
$event
,
?
LoggerInterface
$logger
=
null
):
void
{
if
(
$logger
)
{
wfDeprecatedMsg
(
__METHOD__
.
': $logger parameter is deprecated'
,
'1.40'
);
}
self
::
getEventSubmitter
()->
submit
(
$streamName
,
$event
);
}
/**
* Transfer small data asynchronously using an HTTP POST.
* This is meant to match the Navigator.sendBeacon() API.
*
* @see https://w3c.github.io/beacon/#sec-sendBeacon-method
* @param string $url
* @param array $data
* @return bool
* @deprecated use submit with new Event Platform based schemas.
*/
public
static
function
sendBeacon
(
$url
,
array
$data
=
[]
)
{
$fname
=
__METHOD__
;
$urlUtils
=
MediaWikiServices
::
getInstance
()->
getUrlUtils
();
$url
=
$urlUtils
->
expand
(
$url
,
PROTO_INTERNAL
)
??
''
;
DeferredUpdates
::
addCallableUpdate
(
static
function
()
use
(
$url
,
$data
,
$fname
)
{
$options
=
$data
?
[
'postData'
=>
$data
]
:
[];
return
MediaWikiServices
::
getInstance
()->
getHttpRequestFactory
()
->
post
(
$url
,
$options
,
$fname
);
}
);
return
true
;
}
/**
* Legacy EventLogging entrypoint.
*
* NOTE: For forwards compatibility with Event Platform schemas,
* we hijack the wgEventLoggingSchemas revision to encode the
* $schema URI. If the value for a schema defined in
* EventLoggingSchemas is a string, it is assumed
* to be an Event Platform $schema URI, not a MW revision id.
* In this case, the event will be POSTed to EventGate.
*
* @param string $schemaName Schema name.
* @param int $revId
* revision ID of schema. $schemasInfo[$schemaName] will override this.
* @param array $eventData
* Map of event keys/vals.
* This is the 'event' field, as provided by the caller,
* not an encapsulated real event.
* @param int $options This parameter is deprecated and no longer used.
* @return bool Whether the event was logged.
* @deprecated use EventLogging::submit() with new Event Platform based schemas.
* @see https://wikitech.wikimedia.org/wiki/Event_Platform/Instrumentation_How_To#In_PHP
*/
public
static
function
logEvent
(
$schemaName
,
$revId
,
$eventData
,
$options
=
0
)
{
$config
=
MediaWikiServices
::
getInstance
()->
getMainConfig
();
$eventLoggingConfig
=
Hooks
::
getEventLoggingConfig
(
$config
);
$schemasInfo
=
$eventLoggingConfig
[
'schemasInfo'
];
$eventLoggingBaseUri
=
$eventLoggingConfig
[
'baseUrl'
];
// Get the configured revision id or $schema URI
// to use with events of a particular (legacy metawiki) EventLogging schema.
// $schemasInfo[$schemaName] overrides passed in $revId.
$revisionOrSchemaUri
=
$schemasInfo
[
$schemaName
]
??
$revId
??
-
1
;
// Encapsulate and other event meta data to eventData.
$event
=
self
::
encapsulate
(
$schemaName
,
$revisionOrSchemaUri
,
$eventData
);
if
(
isset
(
$event
[
'$schema'
]
)
)
{
// Assume that if $schema was set by self::encapsulate(), this
// event should be POSTed to EventGate via EventServiceClient submit()
self
::
submit
(
self
::
getLegacyStreamName
(
$schemaName
),
$event
);
return
true
;
}
else
{
// Else this will be sent to the legacy eventlogging backend
// via 'sendBeacon' by url encoding the json data into a query parameter.
if
(
!
$eventLoggingBaseUri
)
{
return
false
;
}
$json
=
self
::
serializeEvent
(
$event
);
$url
=
$eventLoggingBaseUri
.
'?'
.
rawurlencode
(
$json
)
.
';'
;
return
self
::
sendBeacon
(
$url
);
}
}
/**
*
* Converts the encapsulated event from an object to a string.
*
* @param array $event Encapsulated event
* @return string $json
*/
public
static
function
serializeEvent
(
$event
)
{
$eventData
=
$event
[
'event'
];
if
(
count
(
$eventData
)
===
0
)
{
// Ensure empty events are serialized as '{}' and not '[]'.
$eventData
=
(
object
)
$eventData
;
}
$event
[
'event'
]
=
$eventData
;
// To make the resultant JSON easily extracted from a row of
// space-separated values, we replace literal spaces with unicode
// escapes. This is permitted by the JSON specs.
return
str_replace
(
' '
,
'
\u
0020'
,
FormatJson
::
encode
(
$event
)
);
}
/**
* Validates object against JSON Schema.
*
* @throws JsonSchemaException If the object fails to validate.
* @param array $object Object to be validated.
* @param array|null $schema Schema to validate against (default: JSON Schema).
* @return bool True.
*/
public
static
function
schemaValidate
(
$object
,
$schema
=
null
)
{
if
(
$schema
===
null
)
{
// Default to JSON Schema
$json
=
file_get_contents
(
dirname
(
__DIR__
)
.
'/schemas/schemaschema.json'
);
$schema
=
FormatJson
::
decode
(
$json
,
true
);
}
// We depart from the JSON Schema specification in disallowing by default
// additional event fields not mentioned in the schema.
// See <https://bugzilla.wikimedia.org/show_bug.cgi?id=44454> and
// <https://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.4>.
if
(
!
array_key_exists
(
'additionalProperties'
,
$schema
)
)
{
$schema
[
'additionalProperties'
]
=
false
;
}
$root
=
new
JsonTreeRef
(
$object
);
$root
->
attachSchema
(
$schema
);
return
$root
->
validate
();
}
/**
* Randomise inclusion based on population size and a session ID.
* @param int $populationSize Return true one in this many times. This is 1/samplingRate.
* @param string $sessionId Hexadecimal value, only the first 8 characters are used
* @return bool True if the event should be included (sampled in), false if not (sampled out)
*/
public
static
function
sessionInSample
(
$populationSize
,
$sessionId
)
{
$decimal
=
(
int
)
base_convert
(
substr
(
$sessionId
,
0
,
8
),
16
,
10
);
return
$decimal
%
$populationSize
===
0
;
}
/**
* This encapsulates the event data in a wrapper object with
* the default metadata for the current request.
*
* NOTE: for forwards compatibility with Event Platform schemas,
* we hijack the wgEventLoggingSchemas revision to encode the
* $schema URI. If the value for a schema defined in
* EventLoggingSchemas is a string, it is assumed
* to be an Event Platform $schema URI, not a MW revision id.
* In this case, the event will be prepared to be POSTed to EventGate.
*
* @param string $schemaName
* @param int|string $revisionOrSchemaUri
* The revision id or a string $schema URI for use with Event Platform.
* @param array $eventData un-encapsulated event data
* @return array encapsulated event
*/
private
static
function
encapsulate
(
$schemaName
,
$revisionOrSchemaUri
,
$eventData
)
{
global
$wgDBname
;
$event
=
[
'event'
=>
$eventData
,
'schema'
=>
$schemaName
,
'wiki'
=>
$wgDBname
,
];
if
(
isset
(
$_SERVER
[
'HTTP_HOST'
]
)
)
{
$event
[
'webHost'
]
=
$_SERVER
[
'HTTP_HOST'
];
}
if
(
is_string
(
$revisionOrSchemaUri
)
)
{
$event
[
'$schema'
]
=
$revisionOrSchemaUri
;
// NOTE: `client_dt` is 'legacy' event time. `dt` is the preferred event time field
// and is set in EventServiceClient.
$event
[
'client_dt'
]
=
wfTimestamp
(
TS_ISO_8601
);
// Note: some fields will have defaults set by eventgate-wikimedia.
// See:
// - https://gerrit.wikimedia.org/r/plugins/gitiles/eventgate-wikimedia/+/refs/heads/master/eventgate-wikimedia.js#358
// - https://wikitech.wikimedia.org/wiki/Event_Platform/Schemas/Guidelines#Automatically_populated_fields
}
else
{
$event
[
'revision'
]
=
$revisionOrSchemaUri
;
$event
[
'userAgent'
]
=
$_SERVER
[
'HTTP_USER_AGENT'
]
??
''
;
}
return
$event
;
}
/**
* Prepend "eventlogging_" to the schema name to create a stream name for a migrated legacy
* schema.
*
* @param string $schemaName
* @return string
*/
private
static
function
getLegacyStreamName
(
string
$schemaName
):
string
{
return
"eventlogging_$schemaName"
;
}
}
class_alias
(
EventLogging
::
class
,
'EventLogging'
);
File Metadata
Details
Attached
Mime Type
text/x-php
Expires
Sun, Nov 22, 02:46 (1 d, 12 h)
Storage Engine
local-disk
Storage Format
Raw Data
Storage Handle
b6/22/188d0baf10dabc6b687329ee4d64
Default Alt Text
EventLogging.php (10 KB)
Attached To
Mode
rMWPROD MediaWiki Production
Attached
Detach File
Event Timeline
Log In to Comment