User journey

The xrelia agent provides a lightweight scripting engine for implementing synthetic requests and user journey monitoring. Instead of configuring individual checks through a UI, you can write JavaScript that performs real application workflows, validates responses, and reports the results back to xrelia.

This approach makes it easy to monitor complex user journeys such as authentication, checkout, payment processing, or any other sequence of HTTP requests.

How it works

The xrelia agent acts as the runtime engine, while your synthetic request logic lives in one or more JavaScript files.

The agent automatically discovers and executes scripts from a directory named scripts.

The agent pushes synthetic request results to xrelia via the API.

On a standard Linux installation, the scripts directory is:

/opt/xrelia/scripts

You can organize your synthetic requests across multiple JavaScript files in any way that is convenient for your project. A single file can perform one synthetic request or an entire user journey involving multiple dependent requests.

JavaScript runtime

The current version of the xrelia agent supports full ECMAScript 5.1.

The runtime is capable of executing JavaScript compiled to ES5, including output generated by Babel, the TypeScript compiler, and similar transpilation tools.

Future versions may add support for additional scripting languages such as Python or Lua.

Supported protocols

The current agent supports HTTP and HTTPS requests.

Synthetic request scripts can invoke REST APIs, web applications, and other HTTP-based services.

The scripting API

The xrelia agent exposes three functions to every script:

• xStart
• xFinish
• xFail

These functions provide a simple lifecycle for executing and reporting synthetic requests.

xStart

xStart initiates a synthetic request and performs the actual HTTP or HTTPS request.

It accepts the following arguments:

• Synthetic Request ID
• URL
• HTTP method
• Headers
• Request body

The Synthetic Request ID must match the corresponding synthetic request configured in the xrelia console.

Example:

const res = xStart(
  "SYNTHETIC_REQUEST_ID",
  "https://api.example.com/login",
  "post",
  headers,
  payload
);

The function returns a response object with the following properties:

• Request
• StatusCode
• Body

StatusCode contains the HTTP response status code.

Body contains the parsed response body returned by the server.

The Request object is the object that will eventually be reported back to xrelia.

xFinish

After examining the response, your script must set the request status and call xFinish.

The status is stored in Request.Status.

Use:

• 100 for success
• 0 for failure

Example:

res.Request.Status = res.StatusCode === 200 ? 100 : 0;
xFinish(res.Request);

xFail

xFail immediately marks a synthetic request as failed without executing it.

This is useful for dependent requests.

For example, if authentication fails, subsequent requests that require a valid session token should be reported as failed immediately rather than attempting to execute them.

Example:

xFail("DASHBOARD_REQUEST_ID");
xFail("PROFILE_REQUEST_ID");

Example: Authentication user journey

The following script performs a login request, validates the response, reports the result to xrelia, and captures a session token for subsequent requests.

const BASE_URL = "https://api.example.com";
const headers = {
  "content-type": "application/json"
};

// Login synthetic request

const resAuth = xStart(
  "SYNTHETIC_REQUEST_ID",
  BASE_URL + "/authenticate",
  "post",
  headers,
  {
    emailAddress: "me@example.com",
    password: "mypassword"
  }
);

resAuth.Request.Status =
  !resAuth.Body || resAuth.StatusCode === 200 ? 100 : 0;

xFinish(resAuth.Request);

if (resAuth.Request.Status > 0) {
  headers["x-session-token"] = resAuth.Body.sessionToken;

  // Additional synthetic requests can be executed here
} else {
  // Dependent synthetic requests cannot proceed

  xFail("SYNTHETIC_REQUEST2_ID");
  xFail("SYNTHETIC_REQUEST3_ID");
}

Building complete user journeys

The real power of the scripting engine is the ability to model complete user journeys.

A single script can:

• authenticate a user
• capture authentication tokens
• invoke multiple APIs
• validate response payloads
• measure the success of each step
• report every synthetic request independently
• handle dependency failures gracefully

This allows xrelia to monitor the same critical workflows that your customers use in production, providing a much more accurate picture of application health than isolated endpoint checks.

Best practices

For reliable synthetic monitoring, we recommend:

• keeping synthetic request IDs synchronized with the xrelia console
• checking both HTTP status codes and response content
• failing dependent requests explicitly with xFail
• organizing related workflows into separate script files
• avoiding unnecessary network calls
• using realistic request payloads and authentication flows

The scripting engine is designed to be simple, deterministic, and lightweight, making it suitable for running continuously as part of the xrelia agent.