Skip to main content

Metrics

The Metrics feature in the iXR Platform has two parts:

  1. Metrics Page – Explore raw metrics visually.
  2. Posting Metrics – Send new metrics to the API.

🖥️ Metrics Page​

Use the Metrics page to filter and inspect raw metrics with a workflow similar to Grafana dashboards.

Metrics page — filters and results

🔎 Filters & Controls​

  • Metric Group – Choose a group (e.g., Users, Sessions, SettingDeleted).
  • Metric – Pick a specific metricCode within the selected group (e.g., iXR-Core-userSessionLength).
  • Start Date / End Date – Time range for your query.
  • Add Filter – Add extra key/value filters (e.g., DomainUserId, SessionType).
  • Apply – Runs the query with the selected filters.

🧱 Results Table​

  • Metric Name – The metric’s code.
  • Value – Parsed or summarized value (e.g., Duration: 8.426751).
  • Domain User – User identifier when present; N/A if not applicable.
  • Date – Timestamp (createdAt).

Rows are sortable (↑/↓), paginated (Rows per page), and expandable. Expanding a row opens Details, where you can:

  • View the full metricValue payload.
  • Copy values for debugging or reporting.
  • See normalized fields (Metric Name, Value, Domain User Id, Date).

📤 Posting Metrics​

The API allows you to submit metrics from your application or users. There are two endpoints:

  1. End User–Specific Metrics POST app/api/v1/projects/{projectId}/domain/metrics/user

  2. General Application Metrics POST app/api/v1/projects/{projectId}/domain/metrics

🎯 Purpose​

Submit analytics data either for:

  • A specific end user (user-tied events like sessions).
  • The application in general (system or project-wide events).

🧾 Request Headers​

  • Content-Type: application/json

📦 Request Body​

The request body is always a JSON object with the following fields:

FieldTypeRequired?Description
metricGroupCodestringYesLogical group for the metric (e.g., "Sessions", "SettingDeleted").
metricCodestringYesUnique or descriptive identifier for the metric.
createdAtstringNoISO-8601 timestamp when the metric was generated. Defaults to server time if omitted.
metricValueobjectYesKey–value payload storing the metric (any valid JSON structure).

Notes

  • If createdAt is omitted, the server sets it to the current date and time.
  • metricValue is stored as JSONB in the database.

🧪 Example Requests​

End User–Specific Metrics

{
  "metricGroupCode": "Sessions",
  "metricCode": "Session-14/05/2025",
  "createdAt": "2024-12-08T08:32:46.003Z",
  "metricValue": {
    "Start": "2024-12-08T08:32:46.003Z",
    "SessionType": "normal"
  }
}

🧭 Summary & Behaviors​

⏱️ Timestamp Handling​

  • If createdAt is not provided, the server defaults to the current time.
  • Supports both online (real-time) and offline (batched) submissions.

🗃️ Metric Value Storage​

  • metricValue is stored as JSONB in the database.

🧮 Session Grouping​

  • Reports can group metrics by a Session field inside metricValue.
  • Unique session IDs are recommended but not enforced; duplicates are allowed and simply affect granularity.

✅ Best Practices​

🕒 Use Accurate Timestamps

Always include createdAt when posting metrics. This ensures consistency across different devices and avoids relying on server defaults.

📦 Keep Metric Groups Organized

Use meaningful metricGroupCode and metricCode values (e.g., "Sessions", "FeatureUsage") so metrics are easier to query and analyze later.

🧮 Unique Session IDs

For session tracking, generate unique IDs per session. While duplicates are allowed, unique IDs improve report granularity and accuracy.

🔑 Consistent Keys in metricValue

Define a standard schema for keys inside metricValue (e.g., always use "UserId", "Device", "SessionType"). Consistency ensures metrics can be filtered and aggregated easily across different events.

🔎 Filter-Friendly Values

Design metricValue objects with fields that can be used as filters (e.g., SessionType, Device, UserId) for easier dashboard analysis.

⚡ Batch Submissions Wisely

When operating offline, batch metrics carefully and ensure ordering is preserved before posting them to the API.

💡 Business Case​

Business case — Feature Usage Tracking

Imagine your team has launched a new feature in your VR training application. You want to measure how often it is used, by whom, and under what conditions.

  • Each time a user triggers the feature, the app sends a metric event via the API.
  • The metricGroupCode could be "FeatureUsage".
  • The metricCode could be "VR-Scenario-Start".
  • The metricValue could store details such as:
{
  "UserId": "12345",
  "ScenarioId": "Intro-Level",
  "Device": "OculusQuest2",
  "StartTime": "2025-09-17T08:30:00Z"
}