Dedicated Telemetry Backend | Pragma Engine Documentation

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, a single node shard runs all services.

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 #

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

Value	Behavior
`Off` (default)	No dedicated telemetry. Telemetry events route to their named game or social backend, exactly as before.
`UseGameToken`	Telemetry events route to the dedicated telemetry backend, authenticated with the game token.
`UseSocialToken`	Telemetry 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.sendEventAsync(
        TelemetryClientEvent(
            sourceId = playerId.toString(),
            name = "purchase-fulfilled",
            data = PurchaseFulfilledPayload(skuId),
        )
    )
}

sendEventAsync takes a single TelemetryClientEvent; sendEventsAsync 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. There are also synchronous methods available.

game:
  serviceConfigs:
    TelemetryBackendClientConfig:
      bearerToken: <encrypted-bearer-token>
      telemetryHost: telemetry.internal.example.com
      telemetryPort: 12100

Setting	Default	Description
`bearerToken`	`UNCONFIGURED`	The partner 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.
`telemetryHost`	`""`	The host of the dedicated telemetry backend’s internal load balancer for partner calls. Empty routes intra-cluster instead. Pragma provisions this when standing up the telemetry backend for your shard (see Enabling above).
`telemetryPort`	`-1`	The port of the dedicated telemetry backend’s internal load balancer for partner calls. `-1` routes intra-cluster instead.
`telemetryProtocol`	inherited 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.
`maximumConcurrentRequests`	`10`	Hot-reloadable cap on concurrent outbound requests to the telemetry backend.
`enableHttpCompression`	`false`	Gzip-compress request bodies sent to the telemetry backend. Enable compression on the telemetry backend’s partner gateway first; see Enable compression on telemetry calls. Hot-reloadable.
`httpCompressionMinBodyBytes`	`200`	Request bodies smaller than this are sent uncompressed even when `enableHttpCompression` is on. Hot-reloadable.

Infra provisioning will set up all the necessary values. However, it’s also possible to configure things manually via in engine config, using homebase to encrypt secrets like the TelemetryBackendClientConfig.