Meta Developers

Custom metrics are a way for creators to capture data about their TypeScript scripts while they run. This data shows when your scripts run and how long they take, which you can use to optimize world performance. You can view this data with the Performance Scrubbing tool or in Perfetto.

To use custom metrics:

Define and configure your own metrics in TypeScript.
Activate the defined metrics to ensure they appear in the scrubbing tool.
Create samplers to collect data.
Call the samplers’ collection functions in your scripts wherever you want to record data.

Create custom metrics and add to your scripts

To collect data about how your scripts run, you must define and configure the metrics you want to collect, create samplers, then call them in your scripts.

Define and activate custom metrics

First, define and configure your custom metrics by creating a new HorizonPerformanceMetricConfig object.

const testCounterMetric = new HorizonPerformanceMetricConfig(
  "counterMetric",
  ["helloThere", "helloThere2", "helloThere3"],
  HorizonTraceEventType.Counter,
  "100",
);

To create a metric, include the following parameters:

metricName : The metric name as a string. “counterMetric” in the example.
samplersList : A list of the names of the samplers that will provide data to this metric, as an array of strings. These samplers can be defined in any script file. [“helloThere”, “helloThere2”, “helloThere3”] in the example.
intendedTraceEventType : The HorizonTraceEvent type that corresponds to the sampler type for this metric. This determines the suffix (“milliseconds” or “none”) for the metric and the way it will be processed. “HorizonTraceEventType.Counter” in the example. The options are:
- Duration, which measures a length of time, such as how long a function took to run. Measured in milliseconds with microsecond precision.
- Marker, which measures an occurrence, such as whether code ran.
- Counter, which measures an arbitrary number, like how many times a block of code ran.
targetValue : The target value per frame as a string. This data will appear in the scrubbing tool. “100” in the example.

Once you’ve defined your custom metrics, activate the metrics you wish to see data for.

Note: If you don’t activate a metric its data won’t appear in the scrubbing tool.

CustomMetricsCoordinator.activateMetric(testCounterMetric);

Create samplers

Once you’ve defined custom metrics, you must create samplers to provide data for those metrics.

Samplers are objects that record data of different types. They feed data into your defined metrics.

The types of samplers correspond to the HorizonTraceEvent types:

We recommend using only one type of sampler per metric, but you can use any number of samplers of that type.

To create a sampler, pass in a name for the sampler as a string. This name must match one of the strings in the samplersList array passed into HorizonPerformanceMetricConfig.

// Create a count sampler
const testCountSampler = new HorizonCountSampler("helloThere");

You can use samplers from multiple script files in the same metric, since their names are defined by passing in a basic string.

Measure custom metrics in your code

Once you’ve defined your custom metrics and created samplers for them, choose the right places in your scripts to measure these metrics by calling the samplers’ collection functions.

For example, to measure how many times a function ran with our testSampler:

var numRuns = 0;

function testFunc(): void {
  // do stuff
  numRuns++;
}

testCountSampler.count(numRuns);

To use a duration sampler to measure the length of a function, set up your custom metric, activate it, create a HorizonDurationSampler and call it’s trace() method on the function you want to measure:

function funcToBeTraced(): void {
  // do stuff
}

// Define a duration custom metric
const testDurationMetric = new HorizonPerformanceMetricConfig(
  "durationMetric",
  ["durationHello"],
  HorizonTraceEventType.Duration,
  "10",
);

// Activate the metric
CustomMetricsCoordinator.activateMetric(testDurationMetric);

// Create a duration sampler
const testDurationSampler = new HorizonDurationSampler("helloThere");

// Call it's trace() method on the function to measure
durationSamplerEx.trace(funcToBeTraced);

For a marker sampler, call markerSamplerEx.mark().

Analyze custom metric data

Viewing Data in VR

Note: Only data from client-side scripts are available in the VR scrubbing tool.

To view data from the custom metrics you added to your client-side scripts, open the real-time metrics panel and use the scrubbing tool. Performance data is collected by profiling your scripts whenever the real-time metrics panel is open. Click Inspect to look at the profile data and scroll to the bottom of the pane to see your metrics data. A buffer of the last 30 seconds of data is available to view.

Viewing Data in Perfetto

You can use Perfetto to view data from the custom metrics you added to your client and server side scripts.

Create a trace using the instructions in the Tracing docs.
Open the Horizon Creator portal and find the trace. The name of the trace file should include “custom_metrics”.
Click Open in Perfetto to open the trace.

Now, you can analyze your custom metrics data from the trace in Perfetto.