You can create custom flows in Faros via the Flows API . Specifying a flow involves the following steps:

1. Defining the flow steps
2. Defining the flow tags (attributes that you might want to slice/dice flow metrics by)
3. Creating a flow definition using the flow steps and tags
4. Assigning a flow to the flow definition

Defining a flow step

(API Reference: Creates a flow step)

A flow step is any step in your process/workflow, and has two defining attributes: a traceId and a timestamp. For instance, the steps in an incident resolution flow might be the incident created step, the incident acknowledged step, and the incident resolved step. The traceId for each of these steps would be the incident id, and the timestamps would be the timestamps for when the incident was created, the incident was acknowledged, and the incident was resolved respectively.

To define a flow step, you need to specify the following parameters:

Most of these are self explanatory and easy to fill out. The trickiest parts are the query and the transform. The query is a graphql query over the Faros graph that selects the data of interest — in this case incidents with various timestamps; and the transform is a jsonata transform that tells Faros how to extract the traceId and the timestamp for each incident returned by the graphql query. For instance, for the incident created step, here is the query and corresponding transform:

query: >
	query MyQuery {
  	ims_Incident {
    	id
    	createdAt
  	}
	}
  
transform: >
	data.ims_Incident.{
		"traceID": id,
  	"at": createdAt != null ? createdAt : null
	}

Defining flow tags

(API reference: Creates flow tags)

Sometimes you may wish to associate additional data with your flow traces for slicing and dicing. For instance, you may wish to track incident severity with your incident resolution traces, so that you can analyze flow metrics by incident severity. This additional data can be stored as tags on a trace. Tags are once again defined using GraphQL queries and JSONata transforms. Here is what this would look like for our example incident resolution flow:

query: >
	query MyQuery {
  	ims_Incident {
    	id
    	severityCategory
    	priorityCategory
  	}
	}

transform: >
	data.ims_Incident.{
		"traceID": id,
  	"tags" : {
  		"severity": severityCategory,
    	"priority": priorityCategory
    }
	}

Creating a flow definition

(API reference: Creates a flow definition)

With the flow steps and tags defined, you can now define the flow itself. The flow definition is comprised of a series of flow steps, and spans between them. In our example incident resolution flow, we can define a Time to Acknowledge span and a Time to Fix span:

Spans come with additional parameters such as coalesce and defaultDuration that define behavior for when start or end steps for spans may be missing. For instance, if traces in your incident resolution flow are sometimes missing acknowledgement steps, you can set the coalesce parameter for the Time to Fix span to Preceding. This means that Faros will compute the Time to Fix span for a trace as the time from when the incident was created, to when it got resolved if the acknowledgement is missing.

📘

Note: Flow steps and tags can be re-used across flow definitions

Assigning a flow to a flow definition

(API reference: Creates a flow assignment)

Now to start seeing flow-related data in your metrics tables, simply assign a flow ID to the newly created flow definition. You can even reassign default flows that come out of the box with Faros to the custom flow definition that you've just created, so that out-of-the-box dashboards and charts that use the default flows will now use your custom flow instead.

Metrics

Once a flow has been assigned, refresh your metrics tables, and you will start seeing flow-related data populating in the Flow Duration metrics table. Filter the table to your specific Flow Id to see the traces and spans for your custom flow. For each trace, Faros automatically computes durations of different time spans in the flow, as well as the overall end to end time called the Overall Time span. You can now compute averages, medians, or other percentiles for different spans in your flow.