View as Markdown

Rule¶

Field	Type	Description
id	string	Rule identifier. It must be unique across the workflow it belongs to.
ootb	bitdrift.public.unary.explorations.v1.Rule.RuleOOTBConfiguration	Represents the rule for logs we provide out of the box in our SDKs. (Only one of ootb, or match, chart, flush, funnel, start, sankey_diagram, take_screenshot, measure_time, server_funnel_step, timeout, state_change can be set)
match	bitdrift.public.unary.explorations.v1.Rule.RuleMatchConfiguration	Represents a rule that can match logs, filtering the body or fields. (Only one of match, or ootb, chart, flush, funnel, start, sankey_diagram, take_screenshot, measure_time, server_funnel_step, timeout, state_change can be set)
chart	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration	This is an action rule that can be used to collect metrics and display them in a chart. (Only one of chart, or ootb, match, flush, funnel, start, sankey_diagram, take_screenshot, measure_time, server_funnel_step, timeout, state_change can be set)
flush	bitdrift.public.unary.explorations.v1.Rule.RuleFlushConfiguration	This is an action rule that flushes the circular buffers to the server. (Only one of flush, or ootb, match, chart, funnel, start, sankey_diagram, take_screenshot, measure_time, server_funnel_step, timeout, state_change can be set)
funnel	bitdrift.public.unary.explorations.v1.Rule.RuleFunnelConfiguration	This is an action rule that can be used to collect metrics in every step of the workflow and display them in a funnel chart. (Only one of funnel, or ootb, match, chart, flush, start, sankey_diagram, take_screenshot, measure_time, server_funnel_step, timeout, state_change can be set)
start	bitdrift.public.unary.explorations.v1.Rule.RuleStartConfiguration	This represents a rule that can be used as the start of the workflow, allowing multiple initial conditions for the workflow to be specified. This rule is neither a matcher nor an action: it just provides a starting point for the workflow. (Only one of start, or ootb, match, chart, flush, funnel, sankey_diagram, take_screenshot, measure_time, server_funnel_step, timeout, state_change can be set)
sankey_diagram	bitdrift.public.unary.explorations.v1.Rule.RuleSankeyDiagramConfiguration	An action rule used to collect dynamic paths visited by a workflow, along with statistics on the frequency of visits for each path. (Only one of sankey_diagram, or ootb, match, chart, flush, funnel, start, take_screenshot, measure_time, server_funnel_step, timeout, state_change can be set)
measure_time	bitdrift.public.unary.explorations.v1.Rule.RuleMeasureTime	An action rule used to generate a log with the time difference between to other nodes. (Only one of measure_time, or ootb, match, chart, flush, funnel, start, sankey_diagram, take_screenshot, server_funnel_step, timeout, state_change can be set)
timeout	bitdrift.public.unary.explorations.v1.Rule.RuleTimeout	Timeout rule transition. (Only one of timeout, or ootb, match, chart, flush, funnel, start, sankey_diagram, take_screenshot, measure_time, server_funnel_step, state_change can be set)
state_change	bitdrift.public.unary.explorations.v1.Rule.RuleStateChangeConfiguration	A rule that matches on state changes. (Only one of state_change, or ootb, match, chart, flush, funnel, start, sankey_diagram, take_screenshot, measure_time, server_funnel_step, timeout can be set)

Example¶

JSON

{
  "id": "abc-123-def",
  "match": {
    "conditionals": [
      {
        "conditions": [
          {
            "id": "abc-123-def",
            "is_custom_lhs": false,
            "is_json_path": false,
            "lhs": "example",
            "lhs_state_scope": "GLOBAL_STATE",
            "match_type": "STRING",
            "operator": "EQUAL",
            "rhs": "example"
          }
        ]
      }
    ],
    "os": "ALL"
  }
}

Rule.RuleStateChangeConfiguration¶

Field	Type	Description
state_changes	bitdrift.public.unary.explorations.v1.LegacyStateChangeMatch	The state change that must be observed to match this rule.
conditionals	repeated bitdrift.public.unary.explorations.v1.Conditional	An array of conditionals that need to match in order to advance in the graph. The first dimension of the conditionals array is the OR'ed, the second dimension is AND'ed. Such that [ [{ lhs: 'A', operator: '==', rhs: 'a', matchType: 'string' }, { lhs: 'B', operator: '==', rhs: 'b', matchType: 'string' }], [{ lhs: 'A', operator: '==', rhs: 'c', matchType: 'string' }] ] ...means (A==a AND B==b) OR (A==c) Note that this will be executed with the fields available through field providers, so both OOTB and custom fields can be used in the conditionals despite there being no way to pass log fields to state changes. `log` and `log_level` are not available in this context.

Example¶

JSON

{
  "conditionals": [
    {
      "conditions": [
        {
          "id": "abc-123-def",
          "is_custom_lhs": false,
          "is_json_path": false,
          "lhs": "example",
          "lhs_state_scope": "GLOBAL_STATE",
          "match_type": "STRING",
          "operator": "EQUAL",
          "rhs": "example"
        }
      ]
    }
  ],
  "state_changes": {
    "from": {
      "match_type": "STRING",
      "operator": "GREATER_THAN",
      "value": "example"
    },
    "key": "example-key",
    "scope": "GLOBAL_STATE",
    "to": {
      "match_type": "STRING",
      "operator": "GREATER_THAN",
      "value": "example"
    }
  }
}

Rule.RuleOOTBConfiguration¶

Field	Type	Description
event_id	string	An identifier of the event this rule represents. Options are for example: app-launch, app-terminate, etc.
os	bitdrift.public.unary.explorations.v1.Rule.OperatingSystem	Operating system this rule is meant to match. The combination of the os and the event_id defines the conditionals that are going to be computed for this rule.
conditionals	repeated bitdrift.public.unary.explorations.v1.Conditional	An array of conditionals that need to match in order to advance in the graph. The first dimension of the conditionals array is the OR'ed, the second dimension is AND'ed. Such that [ [{ lhs: 'A', operator: '==', rhs: 'a', matchType: 'string' }, { lhs: 'B', operator: '==', rhs: 'b', matchType: 'string' }], [{ lhs: 'A', operator: '==', rhs: 'c', matchType: 'string' }] ] ...means (A==a AND B==b) OR (A==c)

Example¶

JSON

{
  "conditionals": [
    {
      "conditions": [
        {
          "id": "abc-123-def",
          "is_custom_lhs": false,
          "is_json_path": false,
          "lhs": "example",
          "lhs_state_scope": "GLOBAL_STATE",
          "match_type": "STRING",
          "operator": "EQUAL",
          "rhs": "example"
        }
      ]
    }
  ],
  "event_id": "abc-123-def",
  "os": "ALL"
}

Rule.RuleFlushConfiguration¶

Field	Type	Description
id	string	The server-generated ID for this rule action. This can be used to query for sessions that arrive at this rule action.
applied_daily_limit	uint32	The daily capture limit for the rule. This can come from various sources so returns the source currently in use. i.e. the configured limit (from per_day_limit), the global limit of 100, or from shard config.
match_id	string	Points to a step's match ID that will trigger session capture when this flush rule is hit.

Example¶

JSON

{
  "applied_daily_limit": 25,
  "id": "abc-123-def",
  "match_id": "match-abc"
}

Rule.RuleMetricChartConfiguration¶

Field	Type	Description
time_series	repeated bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.TimeSeries	Explicit lists of time series to generate for this rule.

Example¶

JSON

{
  "time_series": [
    {
      "aggregated_id": "abc-123-def",
      "rate": {
        "denominator": {
          "match_id": "match-abc",
          "name": "My Workflow"
        },
        "denominator_id": "abc-123-def",
        "group_by": {
          "values": [
            {
              "log_body": false
            }
          ]
        },
        "numerator": {
          "match_id": "match-abc",
          "name": "My Workflow"
        },
        "numerator_id": "abc-123-def"
      },
      "track_unique": {
        "device_id": true
      }
    }
  ]
}

Rule.RuleMetricChartConfiguration.DataReference¶

A reference to data extracted from a previous rule in the workflow path.

Field	Type	Description
match_id	string	Points to a step's match ID to extract the value from. If extraction type is measured_time, this must point to a Measure Time rule.
name	string	The name of the field to extract the value from. (Only one of name, or measured_time can be set)
measured_time	bool	Extract the measured time from a completed Measure Time rule. This can only be set if the match_id points to a Measure Time rule. (Only one of measured_time, or name can be set)

Example¶

JSON

{
  "match_id": "match-abc",
  "name": "My Workflow"
}

Rule.RuleMetricChartConfiguration.TimeSeries¶

Field	Type	Description
rate	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.TimeSeries.Rate	A rate metric time series. (Only one of rate, or histogram, count, average_count can be set)
histogram	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.TimeSeries.Histogram	A histogram metric time series. (Only one of histogram, or rate, count, average_count can be set)
count	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.TimeSeries.Count	A count metric time series. (Only one of count, or rate, histogram, average_count can be set)
average_count	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.TimeSeries.AverageCount	An average count metric time series. (Only one of average_count, or rate, histogram, count can be set)
aggregated_id	string	This is the normalized ID for the time series. It is the ID that ends up being used in chart data requests, attaching alerts, etc.
track_unique	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.TimeSeries.TrackUnique	Whether to track unique contributions to each aggregation interval for this time series.

Example¶

JSON

{
  "aggregated_id": "abc-123-def",
  "rate": {
    "denominator": {
      "match_id": "match-abc",
      "name": "My Workflow"
    },
    "denominator_id": "abc-123-def",
    "group_by": {
      "values": [
        {
          "log_body": false
        }
      ]
    },
    "numerator": {
      "match_id": "match-abc",
      "name": "My Workflow"
    },
    "numerator_id": "abc-123-def"
  },
  "track_unique": {
    "device_id": true
  }
}

Rule.RuleMetricChartConfiguration.TimeSeries.Rate¶

A rate metric that is going to be generated for this time series. This is done by emitting simple counters for each of the extracted values and computing the ratio server-side.

Field	Type	Description
numerator	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.DataReference	The data reference to use for the rate numerator.
denominator	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.DataReference	The data reference to use for the rate denominator.
numerator_id	string	The server-generated ID for this rate metric. This can be used to query for the metric.
denominator_id	string	The server-generated ID for the denominator metric. This can be used to query for the metric.
group_by	bitdrift.public.unary.explorations.v1.GroupBy	An optional group by configuration for the time series. The chart will select a limited number of time series based on a top K lookup of the most relevant time series. If the group by is not set, the generated chart will show the time series as a single line.

Example¶

JSON

{
  "denominator": {
    "match_id": "match-abc",
    "name": "My Workflow"
  },
  "denominator_id": "abc-123-def",
  "group_by": {
    "values": [
      {
        "log_body": false
      }
    ]
  },
  "numerator": {
    "match_id": "match-abc",
    "name": "My Workflow"
  },
  "numerator_id": "abc-123-def"
}

Rule.RuleMetricChartConfiguration.TimeSeries.Histogram¶

A histogram metric that is going to be generated for this time series. This is done by emitting histogram values for each value of the extracted value, aggregated server-side.

Field	Type	Description
value	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.DataReference	The data reference whose values will be recorded in the histogram.
group_by	bitdrift.public.unary.explorations.v1.GroupBy	An optional group by configuration for the time series. The chart will select a limited number of time series based on a top K lookup of the most relevant time series. If the group by is not set, the generated chart will show the time series with one line per (P50, P90, P99) percentile.
id	string	The server-generated ID for this histogram metric. This can be used to query for the metric.

Example¶

JSON

{
  "group_by": {
    "values": [
      {
        "log_body": false
      }
    ]
  },
  "id": "abc-123-def",
  "value": {
    "match_id": "match-abc",
    "name": "My Workflow"
  }
}

Rule.RuleMetricChartConfiguration.TimeSeries.Count¶

A count metric that is going to be generated for this time series. This is done by emitting a counter with the extracted value.

Field	Type	Description
value	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.DataReference	The data reference whose values will be emitted into the counter.
group_by	bitdrift.public.unary.explorations.v1.GroupBy	An optional group by configuration for the time series. The chart will select a limited number of time series based on a top K lookup of the most relevant time series. If the group by is not set, the generated chart will show the time series as a single line.
id	string	The server-generated ID for this count metric. This can be used to query for the metric.

Example¶

JSON

{
  "group_by": {
    "values": [
      {
        "log_body": false
      }
    ]
  },
  "id": "abc-123-def",
  "value": {
    "match_id": "match-abc",
    "name": "My Workflow"
  }
}

Rule.RuleMetricChartConfiguration.TimeSeries.AverageCount¶

This time series type will produce an average counter, by emitting a synthetic denominator counter increment every time the numerator counter is extracted and incremented. In practice this is identical to rate, but the display will not be % based and the denominator is implicit.

Field	Type	Description
numerator	bitdrift.public.unary.explorations.v1.Rule.RuleMetricChartConfiguration.DataReference	The data reference to use for the average count numerator.
numerator_id	string	The server-generated ID for this rate metric. This can be used to query for the metric.
denominator_id	string	The server-generated ID for the denominator metric. This can be used to query for the metric.
group_by	bitdrift.public.unary.explorations.v1.GroupBy	An optional group by configuration for the time series. The chart will select a limited number of time series based on a top K lookup of the most relevant time series. If the group by is not set, the generated chart will show the time series as a single line.

Example¶

JSON

{
  "denominator_id": "abc-123-def",
  "group_by": {
    "values": [
      {
        "log_body": false
      }
    ]
  },
  "numerator": {
    "match_id": "match-abc",
    "name": "My Workflow"
  },
  "numerator_id": "abc-123-def"
}

Rule.RuleMetricChartConfiguration.TimeSeries.TrackUnique¶

Field	Type	Description
device_id	bool	This is computed entirely server-side and thus does not require any client emission.

Example¶

JSON

{
  "device_id": true
}

Rule.RuleSankeyDiagramConfiguration¶

Field	Type	Description
nodes	repeated bitdrift.public.unary.explorations.v1.Rule.RuleSankeyDiagramConfiguration.Node	The list of nodes. Since workflows can have loops and each node corresponds to a matcher within a workflow, it's possible for a given matcher and its corresponding node to be visited multiple times. For each visit, a new value is extracted. Additional details related to each node of the diagram. This data is not modified by the server during workflow updates, allowing the frontend to store information that remains stable between updates. All target nodes must be within the same flow.
id	string	The server-generated ID for this rule action. This uniquely identifies the Sankey diagram in a way which is consistent between workflows that define the same Sankey diagram.

Example¶

JSON

{
  "id": "abc-123-def",
  "nodes": [
    {
      "extract_field": "field_name",
      "id": "abc-123-def"
    }
  ]
}

Rule.RuleSankeyDiagramConfiguration.Node¶

Configuration for creating Sankey diagram nodes in response to workflow state updates. Each node corresponds to a matching rule.

Field	Type	Description
id	string	ID of the corresponding matching rule.
fixed	string	The fixed value. (Only one of fixed, or extract_field can be set)
extract_field	string	The name of the field whose value should be extracted. (Only one of extract_field, or fixed can be set)

Example¶

JSON

{
  "extract_field": "field_name",
  "id": "abc-123-def"
}

Rule.RuleMatchConfiguration¶

Field	Type	Description
os	bitdrift.public.unary.explorations.v1.Rule.OperatingSystem	Operating system this rule is meant to match. The combination of the os and the conditionals defines the conditionals that are going to be computed for this rule.
conditionals	repeated bitdrift.public.unary.explorations.v1.Conditional	An array of conditionals that need to match in order to advance in the graph. The first dimension of the conditionals array is the OR'ed, the second dimension is AND'ed. Such that [ [{ lhs: 'A', operator: '==', rhs: 'a', matchType: 'string' }, { lhs: 'B', operator: '==', rhs: 'b', matchType: 'string' }], [{ lhs: 'A', operator: '==', rhs: 'c', matchType: 'string' }] ] ...means (A==a AND B==b) OR (A==c)

Example¶

JSON

{
  "conditionals": [
    {
      "conditions": [
        {
          "id": "abc-123-def",
          "is_custom_lhs": false,
          "is_json_path": false,
          "lhs": "example",
          "lhs_state_scope": "GLOBAL_STATE",
          "match_type": "STRING",
          "operator": "EQUAL",
          "rhs": "example"
        }
      ]
    }
  ],
  "os": "ALL"
}

Rule.RuleFunnelConfiguration¶

Field	Type	Description
ids	repeated string	The server-generated IDs for this funnel. This is generated by the server and may change during updates.
match_ids	repeated string	The match IDs in the workflow that correspond to the steps of the funnel. All match IDs must be from the same flow.

Example¶

JSON

{
  "ids": [
    "abc-123-def"
  ],
  "match_ids": [
    "match-abc"
  ]
}

Rule.RuleStartConfiguration¶

No fields

Rule.RuleMeasureTime¶

Field	Type	Description
name	string	A unique identifier for this node that will be included in the generated message body.
start_match_id	string	The start match ID of the step to start measuring from. Must be in the same flow as the end match ID.
end_match_id	string	The end match ID of the step to end measuring at. Must be in the same flow as the start match ID.
correlation_field_name	optional string	Allows the ability to measure time between two rules with a common correlation id. This is useful when the start and end can be racey and we end up measuring time between unrelated events. An example of this is when you measure download time and you get events like: - Download started, id=A - Download started, id=B - Download completed, id=A - Download completed, id=B Without this we'd be measuring the time between B started and A completed.
additional_extracted_fields	repeated string	Supplies optional fields that will be extracted from the log when the time measurement is completed.
measure_time_condition	bitdrift.public.unary.explorations.v1.Rule.RuleMeasureTime.MeasureTimeCondition	An optional condition to check when time measurement is complete. If specified, actions that target the match_id of this rule will only be triggered if the condition is met.

Example¶

JSON

{
  "additional_extracted_fields": [
    "field_name"
  ],
  "correlation_field_name": "field_name",
  "end_match_id": "match-abc",
  "measure_time_condition": {
    "duration_threshold": "3600s",
    "operator": "NOT_EQUAL"
  },
  "name": "My Workflow",
  "start_match_id": "match-abc"
}

Rule.RuleMeasureTime.MeasureTimeCondition¶

Field	Type	Description
operator	bitdrift.public.unary.explorations.v1.Operator	The operator to use when evaluating the duration threshold.
duration_threshold	google.protobuf.Duration	The duration threshold to use when evaluating the condition.

Example¶

JSON

{
  "duration_threshold": "3600s",
  "operator": "NOT_EQUAL"
}

Rule.RuleTimeout¶

This is valid anywhere a generic match or OOTB match rule is allowed, including attached to start with the caveat that we only allow a single timeout outbound from any origin.

Field	Type	Description
duration	uint32	The timeout duration for this rule.
duration_unit	bitdrift.public.unary.explorations.v1.Rule.RuleTimeout.DurationUnit	The unit for the timeout duration value.

Example¶

JSON

{
  "duration": 1,
  "duration_unit": "SECONDS"
}

Rule.RuleTimeout.DurationUnit¶

Name	Number	Description
MILLISECONDS	0
SECONDS	1
MINUTES	2
HOURS	3

Rule.OperatingSystem¶

Name	Number	Description
UNKNOWN	0	Unknown operating system. This should never be sent but is here to make sure we don't pick a default one when this field is not set.
IOS	1
ANDROID	2
UNIVERSAL	3	Universal is the intersection of all operating systems. This is used for events that support all operating systems.