StatisticsService

Getting it

local StatisticsService = Engine:GetService("StatisticsService")

Overview

StatisticsService is one place to record what happens in your game and send it wherever it needs to go:

• Roblox Analytics: economy, funnel, onboarding, progression and custom events go to AnalyticsService through a queue that respects Roblox's rate limits, so events are not silently dropped during busy moments.
• Counters, gauges and timings for live numbers such as "rounds played" or "average round length".
• Automatic tracking of sessions (join, leave, play time), purchases, server start and close, and every server script error.
• Discord webhooks that post selected events, batched and rate-limited, or periodic digests.
• Custom sinks: send batches of events to your own function.
• Persistence (optional): daily and lifetime totals saved through DataService.

Every recorded event fires EventLogged, so you can also react to them in code.

local StatisticsService = Engine:GetService("StatisticsService")

-- Economy: the player earned 50 coins from a quest
StatisticsService:LogEconomyEvent(player, "Source", "Coins", 50, newBalance, "Gameplay", "Quest_Forest")

-- Progression: the player finished level 3
StatisticsService:LogProgressionEvent(player, "Campaign", "Complete", 3, "Forest Temple")

-- Live counter
StatisticsService:Increment("RoundsPlayed")

-- Error alerts in Discord
StatisticsService:CreateWebhook("Alerts", DISCORD_WEBHOOK_URL, { Kinds = { "Error" } })

Roblox Analytics events

These map to Roblox's AnalyticsService events and also go to webhooks, sinks and counters.

LogEconomyEvent

StatisticsService:LogEconomyEvent(player, flow: "Source" | "Sink", currency: string, amount: number, endingBalance: number, transactionType: string, itemSku: string?, fields?): Event?

Money in ("Source") or out ("Sink"). transactionType is a Roblox transaction type name such as "Gameplay", "Shop", "IAP" or "ContextualPurchase" (or the enum).

LogProgressionEvent

StatisticsService:LogProgressionEvent(player, pathName: string, status: "Start" | "Complete" | "Fail", level: number, levelName: string?, fields?): Event?

LogFunnelStepEvent / LogOnboardingFunnelStepEvent

StatisticsService:LogFunnelStepEvent(player, funnelName: string, step: number | string, stepName: string?, fields?): boolean
StatisticsService:LogOnboardingFunnelStepEvent(player, step: number, stepName: string?, fields?): boolean

Steps of a funnel, such as a shop flow or the tutorial. Steps are logged once per funnel session. See Funnels.

LogPurchaseEvent

StatisticsService:LogPurchaseEvent(player, purchaseType: "Product" | "GamePass" | "Asset" | "Plus" | "Subscription", itemId, robux: number?, fields?): Event?

MonetizationService calls this for you when LogToStatistics is on.

LogCustomEvent

StatisticsService:LogCustomEvent(player: Player?, name: string, value: number?, fields?): Event?

Custom fields

Roblox events carry up to three custom fields. Engine events can carry up to MaxFieldCount named fields; map the ones Roblox should receive to its three slots:

Field values are strings, numbers or booleans; long values are cut to MaxFieldLength.

Funnels

StatisticsService:CreateFunnel(name: string, steps: { string }?, options: { Onboarding?, RestartOnFirstStep? }?): Funnel

A funnel object tracks each player's progress through named steps and gives every attempt a session id, which Roblox needs to connect the steps.

local shop = StatisticsService:CreateFunnel("Shop", { "Opened", "ViewedItem", "Purchased" }, { RestartOnFirstStep = true })

shop:Step(player, "Opened")
shop:Step(player, "ViewedItem", { Item = "Sword" })

:GetFunnel(name), :FindFunnel(name) and :GetFunnels() look funnels up.

Counters

Quick numbers kept in memory (and in the persisted totals when enabled).

Each map keeps at most MaxKeysPerMap names; additional names are counted under "(other)".

Automatic tracking

Discord webhooks

CreateWebhook

StatisticsService:CreateWebhook(name: string, url: string, options: WebhookOptions?): Webhook

An Embed is { Title?, Description?, Url?, Color?, Fields?, Footer?, Timestamp?, Thumbnail?, Image? } with fields { Name, Value, Inline? }.

Messages are rate-limited per webhook, retried on network errors, and Discord's Retry-After is respected.

Custom sinks

StatisticsService:CreateSink(name: string, handler: (events: { Event }) -> (), options: SinkOptions?): Sink

Calls your handler with batches of events (BatchSize events, or whatever arrived within FlushSeconds), filtered by Kinds and Names. Use it to forward events to your own backend through HttpService. A Sink has :Flush(), :Destroy(), Enabled, QueuedCount, DeliveredCount, DroppedCount and a Delivered signal.

Persistence

With DataStoreEnabled = true, counters, events, economy totals, funnels and (optionally) errors are added to a DataStore per UTC day and in a lifetime total every DataStoreFlushSeconds. Totals from all servers are combined.

Events and properties

An Event is { Id, Kind, Name, Time, Clock, Player?, UserId?, PlayerName?, Value?, Fields, Data, PlaceId, JobId }. Kinds: Custom, Economy, Funnel, Onboarding, Progression, Purchase, Session, Error, Server.

On shutdown the service waits up to ShutdownFlushSeconds for the DataStore, webhooks and sinks to finish.

Configuration

Types

export type Event
export type EventKind
export type Fields = { [string]: string | number | boolean }
export type Funnel
export type FunnelOptions
export type Webhook
export type WebhookOptions
export type Embed
export type EmbedField
export type Sink
export type SinkOptions
export type Snapshot
export type Aggregate = { Count: number, Sum: number, Min: number, Max: number }
export type ErrorRecord
export type PurchaseType = "Product" | "GamePass" | "Asset" | "Plus" | "Subscription"
export type EconomyFlow = "Source" | "Sink"
export type ProgressionStatus = "Start" | "Complete" | "Fail"