Dedicated telemetry backend #

By default, telemetry events travel over the same game and social backends that serve the rest of your gameplay traffic. Pragma Engine can also run telemetry on a dedicated telemetry backend, advertised as the TELEMETRY backend type that handles telemetry events independently of the game and social backends.

Routing telemetry to its own backend isolates high-volume event traffic from the latency-sensitive game and social RPCs that players depend on. The telemetry backend can be scaled on its own to absorb event spikes, and a slow or degraded telemetry path won’t impact the availability of core game and social sessions. The feature is opt-in on both the platform and the SDK; when it’s disabled, telemetry behaves exactly as before.

Enabling #

Enabling a dedicated telemetry backend is a two-sided change: the platform must advertise a telemetry gateway, and the SDK must be configured to route telemetry to it. Dedicated telemetry is only applicable for multinode shards and must be enabled via our infra tooling. Your CSM can help get thing set up.

Platform #

On Pragma-managed infrastructure, the dedicated telemetry backend is provisioned for you. Contact your customer support representative with the shard you’d like it enabled on, and Pragma will stand up and advertise the telemetry gateway for that shard.

SDK #

Opt the Unreal SDK in by setting PragmaSdkConfig.DedicatedTelemetryMode. It takes one of three values:

ValueBehavior
Off (default)No dedicated telemetry. Telemetry events route to their named game or social backend, exactly as before.
UseGameTokenTelemetry events route to the dedicated telemetry backend, authenticated with the game token.
UseSocialTokenTelemetry events route to the dedicated telemetry backend, authenticated with the social token.

Set it in DefaultGame.ini under the PragmaSdkConfig section:

[/Script/PragmaSDK.PragmaSdkConfig]
DedicatedTelemetryMode=UseSocialToken

When DedicatedTelemetryMode is anything other than Off but the platform isn’t advertising a telemetry backend, telemetry falls back to the named game or social backend, so it’s safe to enable the SDK side ahead of the platform side.

Server-side #

Game and social platform services and plugin implementations record their own telemetry events through TelemetryClientNodeService. It routes intra-cluster when no dedicated telemetry backend is configured, and over a partner call to the dedicated backend when one is — the same fallback behavior as the SDK.

import java.util.UUID
import pragma.telemetry.client.TelemetryClientEvent
import pragma.telemetry.client.TelemetryClientNodeService

//...

private lateinit var telemetryClient: TelemetryClientNodeService

override suspend fun run() {
    telemetryClient = nodeServicesContainer[TelemetryClientNodeService::class]
}

fun recordPurchase(playerId: UUID, skuId: String) {
    telemetryClient.recordEvent(
        TelemetryClientEvent(
            sourceId = playerId.toString(),
            name = "purchase-fulfilled",
            data = PurchaseFulfilledPayload(skuId),
        )
    )
}

recordEvent takes a single TelemetryClientEvent; recordEvents takes a List<TelemetryClientEvent>. Each event carries a sourceId, a name, and a data payload that must be a Kotlin data class. Both return a Job — the send happens in the background, and failures are logged rather than surfaced to the caller, so callers don’t need to wrap calls in their own fire-and-forget handling.

game:
  serviceConfigs:
    TelemetryBackendClientConfig:
      bearerToken: <encrypted-bearer-token>
SettingDefaultDescription
bearerTokenUNCONFIGUREDThe bearer token presented to the telemetry backend’s partner gateway. Must belong to an identity granted the telemetry.events.create permission on the telemetry backend.
telemetryProtocolinherited from GamePartnerGatewayConfig.protocol (game) or SocialPartnerGatewayConfig.protocol (social)The protocol used for calls to the telemetry backend; only override to point this client somewhere different.
maximumConcurrentRequests10Hot-reloadable cap on concurrent outbound requests to the telemetry backend.

The dedicated backend’s host and port aren’t set on this config — they come from the shared, per-gateway telemetryHost/telemetryPort that Pragma provisions when standing up the telemetry backend for your shard (see “Platform” above).

The TelemetryBackendClientConfig will have its bearerToken provisioned through infra. This is one of the things your CSM can make sure is configured correctly. It is also possible to configure this value in engine config, using the portal to generate it and homebase to encrypt it.


Pragma Analytics
Load Testing