Dependencies

• Understanding of the Game Server Metrics feature - You should familiarize yourself with the definition and limitations of the Game Server Metrics feature by reading the Introduction to Game Server Metrics page.

Key Concepts

• A Metric or Statistics Time Series is a collection of values over time.
• A Cohort Time Series is a collection of values over Cohorts over time.
• A Cohort can be a day, such as D0 for a Daily Cohort Time Series like retention, or a name, such as "UnhandledExceptionError" for the incident reports by type Metric.
• A Daily Cohort refers to a type of Cohort Time Series where each Cohort represents a specific day (e.g., D0, D1, D2, etc.). This approach tracks Metrics over time by grouping data into Daily Cohorts, which typically measure days since a specific event, such as user registration. It provides a structured way to analyze trends and behaviors across distinct daily intervals.

Overview

It's possible to easily add custom Metrics through server code without needing to customize your LiveOps Dashboard. However, you first need to consider if the game server Metrics are the right place for your data. If you want to track large amounts of data and perform data transformations or different visualizations after the data has been collected, consider using a dedicated analytics pipeline instead. See Implementing Analytics Events in Game Logic for an introduction to analytics events. If you want an easy way to visualize aggregate data without data transformations after collection, game server Metrics are the right place!

You can add Metrics of many different variants, from simple cases such as the number of sessions, to Daily Cohort Metrics such as retention. We'll also go over how to customize the dashboard behavior of your Metrics, including setting required permissions, as well as custom categories and more. Adding your custom Metric is done purely on the backend, and you don't need to customize your LiveOps Dashboard for your custom Metrics to show up! Read on to find out how to add and customize your own Metrics!

Adding your own metrics

You will need to inherit from StatisticsTimeSeriesRegistryBase to create your own Time Series registry. To define a new Metric, or Statistics Time Series, as it's called in a more generic context here, create a new static member of your chosen Metric variant type (explained later). For now, let's create a new StatisticsSimpleTimeSeries. At this point you will also need to know the type of the event that you'll be aggregating, but don't worry, we'll define it properly in the next section.

We'll also create a custom category for our Metric, which will show up as an additional tab on the Metrics page of the LiveOps Dashboard.

public class MyGameStatisticsTimeSeriesRegistry : StatisticsTimeSeriesRegistryBase
{
    // We create our own Metrics category and set it to be the last in order
    public static CategoryDefinition GameCategory = new("My Game", 999);

    // Here we define our new Time Series and set all of its parameters, 
    // including what mode we are aggregating the data in, 
    // the type of the values,
    // and what will show up in the description spaces on the LiveOps Dashboard.
    public static StatisticsSimpleTimeSeries<StatisticsEventPlayerAdWatched, long> PlayerAdsWatched = new(
        new StatisticsSimpleTimeSeries<StatisticsEventPlayerAdWatched, long>.SetupParams(
            seriesKey: "adsWatchedTotal",
            mode: StatisticsBucketAccumulationMode.Count),
        StatisticsTimeSeriesDashboardInfo.Simple<long>(
            name: "Ads Watched",
            purposeDescription: "Total number of ads watched.",
            implementationDescription: "This metric counts whenever a player successfully watches an ad.",
            GameCategory));
    
    public MyGameStatisticsTimeSeriesRegistry() { }
    // You can use this method to initialize Daily Cohort Metrics and Metrics that require Metaplay services
    protected override void GameInitializeSingleton(IMetaplayServiceProvider services, int[] dailyCohorts) { }

    // Registering our custom category
    protected override CategoryDefinition[] GameCategories => [GameCategory];
    // Registering our custom metric
    protected override IReadOnlyList<IStatisticsTimeSeries> GameSharedTimeSeries => [PlayerAdsWatched];
    protected override IReadOnlyList<IStatisticsTimeSeries> GameDailyOnlyTimeSeries => [];
}

In the case of the simple Time Series, we'll also add it to the GameSharedTimeSeries list. This adds the new Metric to the registry. For Time Series that are daily only, you would add your Time Series to the GameDailyOnlyTimeSeries list.

Adding a StatisticsEventType

To define a new event type, create a class deriving from StatisticsEventBase. The base is a MetaSerializable class, so we'll need the MetaSerializableDerived attribute with a unique type code. Here we'll use 100 to differentiate from the SDK events. Inside the class, you'll need to set the UniqueKey of the event, which should be a combination of the timestamp and any data that makes your event unique, for example the EntityId of the player involved.

/// <summary>
/// Player ad successfully watched event.
/// </summary>
[MetaSerializableDerived(100)]
[MetaReservedMembers(0, 100)]
public class StatisticsEventPlayerAdWatched : StatisticsEventBase
{
    public override string   UniqueKey => Invariant($"upgrade/{PlayerId}/{Timestamp:O}"); // Date format is ISO 8601. (yyyy-MM-dd)

    /// <summary> EntityId of the player who watched the ad. </summary>
    [MetaMember(1)] public EntityId PlayerId { get; private set; }

    StatisticsEventPlayerAdWatched() { }
    public StatisticsEventPlayerAdWatched(MetaTime timestamp, EntityId playerId) : base(timestamp)
    {
        PlayerId = playerId;
    }
}

This defines the event that will be used by our new Metric. Note that you can use the same event for multiple Metrics, changing the Metric variant and aggregation modes.

Writing Events

You can write an event to the database with StatisticsEventWriter.WriteEventAsync(). The method takes a function parameter that should return a new object of your custom event type. The method provides a timestamp to the parameter function. Continuing our "ad watched" example from above (custom callback in PlayerActor.cs):

using Metaplay.Server.StatisticsEvents;
...
async Task OnAdWatchCompletedCallbackAsync()
{
    // Write a new statistics event, with optional error logging
    await StatisticsEventWriter.WriteEventAsync(timeStamp => new StatisticsEventPlayerAdWatched(timeStamp, _entityId))
        .ContinueWith((err) => _log.Error(err.Exception, "Failed to write player ad watched event"), 
            TaskContinuationOptions.OnlyOnFaulted);
}

Added database load

Your events will introduce some database load, so keep their occurrence to a reasonable frequency.

Metric Variants

There are several Metric variants you can use, depending on what kind of data you want to track.

Time Series Types

• Simple - Used to track simple Metrics like the number of sessions or the number of times a button was clicked.
• Cohort - Used to track Metrics with Cohorts like the number of sessions per country.
• DailyCohort - Used to track Daily Cohorts like retention. The Cohort in Daily Cohort Metrics is the number of days since the user has registered.
• SimpleCombined - Used to create a Metric that is derived from two simple metrics. For example, total cumulative session length divided by number of sessions can be used to derive average session length.
• CohortCombined - Used to create a Metric that is derived from two Cohort metrics. For example, combining retained users per day with purchases per retained day Cohorts gives average revenue per retained day.
• SimpleCohortCombined - Used to create a Metric that is derived from a simple and a Cohort metric. For example, retention percentage is calculated from retained users per day Cohorts divided by the registered users on the given day.

Below is an example of a CohortCombined Metric that calculates the Average Revenue Per Daily Active User (ARPDAU) by country:

// Create a metric that calculates average revenue per user per country
public static StatisticsCohortCombinedSeries<int, int, double> ArpdauPerCountry = new(
    new StatisticsCohortCombinedSeries<int, int, double>.SetupParams(
        seriesKey: "arpdauPerCountry",
        series1: DauPerCountry,     // A cohort metric tracking active users per country
        series2: RevenuePerCountry, // A cohort metric tracking revenue per country
        bucketCombiner: (userCount, revenue) =>
            userCount is > 0 && revenue is > 0 ?
            (double)revenue / userCount : 0),
    StatisticsTimeSeriesDashboardInfo.Cohort<double>(
            name: "ARPDAU By Country",
            purposeDescription: "Average revenue per active user by country.",
            implementationDescription: "Total revenue divided by active user count for each country.",
            MonetizationCategory)
        .WithUnit("$", true)
        .WithDecimalPrecision(2));

Each of the non-combined time series types above have additionally two variants, which are used to define which events the Metric should listen to:

Event-Typed Metrics (Single Event Type)

• These metrics are bound to exactly one specific event type that you create.
• They specify the event type directly in the generic type parameter of the time series class
• Example: Tracking global achievement unlocks with StatisticsEventAchievementUnlocked.

public static StatisticsSimpleTimeSeries<StatisticsEventAchievementUnlocked, int> AchievementUnlocks = new(
    new StatisticsSimpleTimeSeries<StatisticsEventAchievementUnlocked, int>.SetupParams(
        seriesKey: "achievementUnlocks",
        mode: StatisticsBucketAccumulationMode.Count),
    StatisticsTimeSeriesDashboardInfo.Simple<int>(
        name: "Achievement Unlocks",
        purposeDescription: "Total number of achievements unlocked by all players.",
        implementationDescription: "Counts each time a player unlocks any achievement.",
        GameCategory));

Non-Event-Typed Metrics (Multiple Event Types)

• These metrics can listen to multiple different event types
• You specify the event types in the eventTypes parameter of the SetupParams constructor
• You also provide an event parser function that extracts values from those events
• Example: Tracking both logins and registrations in a single DAU metric

public static StatisticsSimpleTimeSeries<int> DailyActiveUsers = new StatisticsSimpleTimeSeries<int>(
    new StatisticsSimpleTimeSeries<int>.SetupParams(
        eventTypes: [typeof(StatisticsEventPlayerCreated), typeof(StatisticsEventPlayerLogin)],
        seriesKey: "dau",
        mode: StatisticsBucketAccumulationMode.Sum,
        eventParser: ev => ev switch
        {
            StatisticsEventPlayerCreated => 1,
            // Don't double count registration date.
            StatisticsEventPlayerLogin login => login.DaysSinceRegistered > 0 ? 1 : 0,
            _ => throw new ArgumentException($"Unexpected event type! {ev.GetType()}"),
        }),
    StatisticsTimeSeriesDashboardInfo.Simple<int>(
        name: "Daily Active Users",
        purposeDescription: "The size of your active player base. This is how popular your game is.",
        implementationDescription: "Number of unique players who logged in during the day.",
        category: EngagementCategory)
        .WithDailyOnly(true));

Time Series SetupParams

The StatisticsSimpleTimeSeries class and other Time Series classes take a SetupParams object as their first parameter. The SetupParams object can contain the following properties:

• seriesKey is a unique key for the Time Series, used as the database key. It's also used as the ID of the Metric in the LiveOps Dashboard code.
• mode sets how the values are accumulated within each bucket.
• eventTypes sets the tracked events for non-event-typed metrics.
• eventParser is a function that parses the event or events into the value that is accumulated.
• cohorts or dailyCohorts is a list of Cohort names (string) or days (int). These are used for the Cohort variants.
• storagePageKey is the key for the page where the data is stored. This is used when storing data in different pages. This can be left null to use the default page.

Additionally, combined Time Series have the following properties in their SetupParams:

• series1 and series2 are the series that are to be combined.
• bucketCombiner is a function that combines two Time Series values into one value.

Bucket Accumulation Modes

The bucket accumulation modes define how the values are accumulated within the bucket. Here are the available modes:

• Count - Used to count the number of occurrences of an event.
• Sum - Used to sum the values within a bucket.
• Avg - Used to calculate the average of values within a bucket.
• Min - Used to calculate the minimum of values within a bucket.
• Max - Used to calculate the maximum of values within a bucket.

Using DashboardInfo

With the StatisticsTimeSeriesDashboardInfo class, you can define how the Metric should look and behave on the LiveOps Dashboard. Let's look at the properties you can set for this class:

• Name sets the dashboard visible name of the metric.
• PurposeDescription is the description that summarizes the Metric and is always shown on the Metric cards.
• ImplementationDescription is the description that explains in more detail how the Metric has been collected. It is shown when the Metrics are expanded into the detail view.
• Category sets the category of the Metric, i.e. the tab under which the Metric is found.
• HasCohorts indicates whether the Metric has Cohorts . Metrics with Cohorts are shown with a different type of graph so it's important to set this to true when your Metric has Cohorts . See Metric variants above.
• Unit sets the unit of the values of the metric.
• UnitOnFront indicates whether the unit should be displayed in front of the value.
• DecimalPrecision sets the decimal precision of the values.
• IsHidden indicates whether the Metric is hidden by default. Use this for Metrics that are used to calculate other Metrics, but don't need to be shown themselves.
• YMinValue sets the minimum value of the y axis' maximum, that is, the highest value visible on the y axis when values are below it. When values go above it, the y axis will scale accordingly.
• DailyOnly indicates whether the Metric is only available in daily resolution.
• OrderIndex sets the order index of the metric. Metrics are sorted by this index on the dashboard, lower index first.
• CanBeNull indicates whether the Metric values can be null. If this is false, any null values are replaced with 0.
• RequiredPermission sets the permission required to view the Metric. The default permission is MetaplayPermissions.ApiMetricsView.
• IsDailyCohorts indicates whether the Metric is a Daily Cohorts Metric.
• ValueTransformer is a function that transforms the Metric value. This can be used to transform the value before it's displayed on the dashboard. For example, you can use it to convert a value to a percentage.

The properties can be set in the constructor helper methods for different Metric variants or using the With* methods of the StatisticsTimeSeriesDashboardInfo class. The helper methods include Simple(), SimplePercentage(), Cohort(), CohortPercentage(), DailyCohort() and DailyCohortPercentage(). The helper methods also take the value type as a type argument. Let's say you wanted to make a new Metric to track total ad watch time:

// The actual value type here is long, because we are measuring milliseconds. It could be double as well.
public static StatisticsSimpleTimeSeries<StatisticsEventPlayerAdWatched, long> TotalAdWatchTime = new StatisticsSimpleTimeSeries<StatisticsEventPlayerAdWatched, long>(
    new StatisticsSimpleTimeSeries<StatisticsEventPlayerAdWatched, long>.SetupParams(
        seriesKey: "totalAdWatchTime",
        mode: StatisticsBucketAccumulationMode.Sum,
        eventParser: adWatched => adWatched.AdWatchTime.Milliseconds),
    StatisticsTimeSeriesDashboardInfo.Simple<double>( // The LiveOps Dashboard visible value type is set to double as we're going to display it in minutes with decimals.
            name: "Ad Watch Time",
            purposeDescription: "How much ad watch time your player base is putting in.",
            implementationDescription: "Total cumulative ad watch time of all users.",
            category: GameCategory)
        .WithValueTransformer((value) => value / 60000.0)   // Ad watch time is stored in milliseconds, so transform that to be displayed as minutes
        .WithUnit(" min")                                   // Set the unit displayed on the y axis and in tooltips to " min"
        .WithDecimalPrecision(2)                            // Set the decimal precision to 2, eg. "1.00 min"
        .WithOrderIndex(100));                              // We place this metric later in order relative to other metrics in the same category.

The value transformer that we supplied to the dashboard info class will be applied whenever data is fetched from the backend and before it is sent to the LiveOps Dashboard.

For total ad watch time, you would need to add the AdWatchTime property of type MetaDuration to your ad watched event:

public class StatisticsEventPlayerAdWatched : StatisticsEventBase
{
    public override string   UniqueKey => Invariant($"upgrade/{PlayerId}/{Timestamp:O}"); // Date format is ISO 8601. (yyyy-MM-dd)

    /// <summary> EntityId of the player who watched the ad. </summary>
    [MetaMember(1)] public EntityId     PlayerId    { get; private set; }
    /// <summary> Amount of time the player spent watching the ad. </summary>
    [MetaMember(2)] public MetaDuration AdWatchTime { get; private set; }

    StatisticsEventPlayerAdWatched() { }
    public StatisticsEventPlayerAdWatched(MetaTime timestamp, EntityId playerId, MetaDuration adWatchTime) : base(timestamp)
    {
        PlayerId    = playerId;
        AdWatchTime = adWatchTime;
    }
}

As an example of a Cohort Metric, you could have total ad watch time per country:

public static StatisticsCohortTimeSeries<StatisticsEventPlayerAdWatched, long> TotalAdWatchTimePerCountry = new StatisticsCohortTimeSeries<StatisticsEventPlayerAdWatched, long>(
    new StatisticsCohortTimeSeries<StatisticsEventPlayerAdWatched, long>.SetupParams(
        seriesKey: "totalAdWatchTimePerCountry",
        storagePageKey: null,
        cohorts: AllCountries, // Array of names of all possible countries that the data could reference
        accumulationMode: StatisticsBucketAccumulationMode.Sum,
        eventParser: adWatched => (adWatched.Country, adWatched.WatchTime.Milliseconds)
        ),
    StatisticsTimeSeriesDashboardInfo.Cohort<double>(
        name: "Ad Watch Time Per Country",
        purposeDescription: "How much ad watch time has been racked up in each country.",
        implementationDescription: "Total cumulative ad watch time per country.",
        category: GameCategory)
        .WithValueTransformer((value) => value / 60000.0)
        .WithUnit(" min")
        .WithDecimalPrecision(2)
        .WithOrderIndex(10));

Here, again, you would update the event with the needed information:

public class StatisticsEventPlayerAdWatched : StatisticsEventBase
{
    public override string   UniqueKey => Invariant($"upgrade/{PlayerId}/{Timestamp:O}"); // Date format is ISO 8601. (yyyy-MM-dd)

    /// <summary> EntityId of the player who watched the ad. </summary>
    [MetaMember(1)] public EntityId     PlayerId    { get; private set; }
    /// <summary> Amount of time the player spent watching the ad. </summary>
    [MetaMember(2)] public MetaDuration AdWatchTime { get; private set; }
    /// <summary> Name of the country the player is playing from. </summary>
    [MetaMember(2)] public string       Country     { get; private set; }

    StatisticsEventPlayerAdWatched() { }
    public StatisticsEventPlayerAdWatched(MetaTime timestamp, EntityId playerId, MetaDuration adWatchTime, string country) : base(timestamp)
    {
        PlayerId    = playerId;
        AdWatchTime = adWatchTime;
        Country     = country;
    }
}

Additionally, as you might have guessed, you need to supply those values when writing the events. The source of the data would depend on the APIs you use.

Customizing Permissions

As mentioned above, setting the required permissions for your custom Metrics is as easy as setting the corresponding value to StatisticsTimeSeriesDashboardInfo.RequiredPermission. You can do this with the WithRequiredPermission method in your Metrics definitions. The permission that are available by default are: api.metrics.view, assigned to the Game-Viewer and Game-Admin roles, and api.metrics.view_sensitive, assigned only to the Game-Admin role. In C# server code, the permissions can be referenced with the helper members MetaplayPermissions.ApiMetricsView and MetaplayPermissions.ApiMetricsViewSensitive, respectively.

If you want to customize which roles have access to which permissions or you want to set up custom roles, see the page on Dashboard User Authentication.

Overriding Default Daily Cohort Buckets

By default, Metaplay tracks Daily Cohorts daily up to a month, once per week up to 180 days, 28 days apart up to 3 years. If you want to have more precise data or track Cohorts for longer than three years, you can override the default DailyCohorts list.

public class MyTimeSeriesRegistry : StatisticsTimeSeriesRegistryBase
{
    protected override IEnumerable<int> DailyCohorts =>
        _defaultDailyCohorts.Concat(
            new int[]
            {
                // My custom cohorts. Every 28 days up to 6 years
                // Continued from 1120
                1148, 1176, 1204, 1232, 1260,
                1288, 1316, 1344, 1372, 1400,
                1428, 1456, 1484, 1512, 1540,
                1568, 1596, 1624, 1652, 1680,
                1708, 1736, 1764, 1792, 1820,
                1848, 1876, 1904, 1932, 1960,
                1988, 2016, 2044, 2072, 2100,
                2128, 2156, 2184, 2212, 2240
            });
    ...
}

Adding Daily Cohorts is a safe operation; however, note that data for Cohorts that have already passed will not be retroactively filled. Only new players reaching the newly added Cohorts will be counted. Removing Cohorts does not delete existing data; instead, the data will be hidden, and no new data will be recorded for those Cohorts.

Conclusion

Customizing game server Metrics allows you to gain deeper insights into your game's performance and player behavior. By defining your own Metrics and events you can tailor the data collection to your specific needs. Remember to consider the database load and choose the appropriate Metric variants and accumulation modes for your use case. With the flexibility provided by the Metrics system, you can create a comprehensive and customized set of Metrics for your game.

Further reading

For more information on setting up analytics events, see Implementing Analytics Events in Game Logic. If you're wondering about exporting data elsewhere, see Streaming Analytics Events to External Storage. Game server Metrics data cannot currently be exported from the game server.