resourceloader: Require logName parameter in mw.log.deprecate()

When omitted it, it previously defaulted to the key string, which
would automatically lead to the creation of confusing and
non-descript Graphite metrics. (Via the WikimediaEvents extension
via the 'mw.deprecate' tracking topic.)

If Graphite tracking is intended, require the logName parameter
to be set. For example, in wikibits, a deprecated 'write' method
is set on the 'document' object. Its Graphite property under
mw/js/deprecate/ will be document_write because logName is set.
Without logName, it would previously create 'mw/js/deprecate/write'
as metric, which easily clashes and is not very understandable
in Grafana.

An exception is kept for properties of the window object as their
fully-qualified property name would always be identical due to
them being available as global variables.

Change-Id: I9d99fe0395ec5309eac0895f2419f7cd16caeb94

diff --git a/resources/src/startup/mediawiki.js b/resources/src/startup/mediawiki.js
index 8b2aa29..44e48e5 100644 (file)
--- a/resources/src/startup/mediawiki.js
+++ b/resources/src/startup/mediawiki.js
@@ -314,21 +314,23 @@
                 * @param {string} key Name of property to create in `obj`
                 * @param {Mixed} val The value this property should return when accessed
                 * @param {string} [msg] Optional text to include in the deprecation message
-                * @param {string} [logName=key] Optional custom name for the feature.
-                *  This is used instead of `key` in the message and `mw.deprecate` tracking.
+                * @param {string} [logName] Name for the feature for logging and tracking
+                *  purposes. Except for properties of the window object, tracking is only
+                *  enabled if logName is set.
                 */
                log.deprecate = function ( obj, key, val, msg, logName ) {
                        var stacks;
                        function maybeLog() {
-                               var name,
+                               var name = logName || key,
                                        trace = new Error().stack;
                                if ( !stacks ) {
                                        stacks = new StringSet();
                                }
                                if ( !stacks.has( trace ) ) {
                                        stacks.add( trace );
-                                       name = logName || key;
-                                       mw.track( 'mw.deprecate', name );
+                                       if ( logName || obj === window ) {
+                                               mw.track( 'mw.deprecate', name );
+                                       }
                                        mw.log.warn(
                                                'Use of "' + name + '" is deprecated.' + ( msg ? ( ' ' + msg ) : '' )
                                        );