diff --git a/src/bitdrift/public/shared/alerts/v1/alert_group.proto b/src/bitdrift/public/shared/alerts/v1/alert_group.proto index 15037112..70e5b775 100644 --- a/src/bitdrift/public/shared/alerts/v1/alert_group.proto +++ b/src/bitdrift/public/shared/alerts/v1/alert_group.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.shared.alerts.v1; diff --git a/src/bitdrift/public/shared/annotations/api_ootb_fields.proto b/src/bitdrift/public/shared/annotations/api_ootb_fields.proto index 47334587..3c371b23 100644 --- a/src/bitdrift/public/shared/annotations/api_ootb_fields.proto +++ b/src/bitdrift/public/shared/annotations/api_ootb_fields.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.shared.annotations; diff --git a/src/bitdrift/public/shared/annotations/dashboard_layout.proto b/src/bitdrift/public/shared/annotations/dashboard_layout.proto new file mode 100644 index 00000000..6dd65497 --- /dev/null +++ b/src/bitdrift/public/shared/annotations/dashboard_layout.proto @@ -0,0 +1,18 @@ +// api - bitdrift's client/server API definitions +// Copyright Bitdrift, Inc. All rights reserved. +// +// Use of this source code and APIs are governed by a source available license that can be found in +// the LICENSE file or at: +// https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + +syntax = "proto3"; + +package bitdrift.public.shared.annotations; + +import "google/protobuf/descriptor.proto"; + +// The minimum number of dashboard grid rows required by this enum value. +extend .google.protobuf.EnumValueOptions { + // The minimum number of dashboard grid rows required by this enum value. + uint32 minimum_row_span = 50012; +} diff --git a/src/bitdrift/public/shared/platform/v1/platform.proto b/src/bitdrift/public/shared/platform/v1/platform.proto index e8e132aa..0d0a41c8 100644 --- a/src/bitdrift/public/shared/platform/v1/platform.proto +++ b/src/bitdrift/public/shared/platform/v1/platform.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.shared.platform.v1; diff --git a/src/bitdrift/public/shared/workflows/v1/time_series.proto b/src/bitdrift/public/shared/workflows/v1/time_series.proto index ddb8e44c..ac8a401a 100644 --- a/src/bitdrift/public/shared/workflows/v1/time_series.proto +++ b/src/bitdrift/public/shared/workflows/v1/time_series.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.shared.workflows.v1; @@ -81,7 +82,8 @@ message TimeSeries { // // For workflow-backed time series, this maps back to one or more action IDs and can be reused as // `charts.v1.LimitStrategy.IdentifierMatch.DimensionIdentifier.id` when selecting specific groups - // from a later `GetChartsData` request. + // from a later `GetChartsData` request. It also associates the result with configured display + // metadata, including its title, in resolved chart responses. string id = 1 [(validate.rules).string = {min_len: 1}]; // The labels associated with this time series. @@ -100,12 +102,6 @@ message TimeSeries { // Note that this may not be set via all APIs. optional .bitdrift.public.shared.workflows.v1.Legend legend = 5; - // A simple title for the time series. This is a more compact version of the - // legend that can be used when the legend is too verbose. - // - // Note that this may not be set via all APIs. - optional string title = 6; - // The unique devices count for the entire series based on the TrackUnique configuration. // Deduplicates devices across the queried interval rather than summing bucket counts. // Rates normally count denominator devices; basic alerts can select numerator devices. diff --git a/src/bitdrift/public/stream/bdtail/v1/bdtail_api.proto b/src/bitdrift/public/stream/bdtail/v1/bdtail_api.proto index 675c79d4..e93b0dac 100644 --- a/src/bitdrift/public/stream/bdtail/v1/bdtail_api.proto +++ b/src/bitdrift/public/stream/bdtail/v1/bdtail_api.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.stream.bdtail.v1; diff --git a/src/bitdrift/public/stream/device_debug/v1/device_debug.proto b/src/bitdrift/public/stream/device_debug/v1/device_debug.proto index 90923358..156cea64 100644 --- a/src/bitdrift/public/stream/device_debug/v1/device_debug.proto +++ b/src/bitdrift/public/stream/device_debug/v1/device_debug.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.stream.device_debug.v1; diff --git a/src/bitdrift/public/unary/admin/v1/access.proto b/src/bitdrift/public/unary/admin/v1/access.proto index 0e542722..d33031fa 100644 --- a/src/bitdrift/public/unary/admin/v1/access.proto +++ b/src/bitdrift/public/unary/admin/v1/access.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.admin.v1; @@ -14,35 +15,48 @@ import "validate/validate.proto"; // The level of access granted to a principal. // -// In SetAccessRequest, an omitted access level defaults to VIEW. +// In `SetAccessRequest`, an omitted access level defaults to `VIEW`. enum AccessLevel { + // The principal can view the entity. VIEW = 0; + // The principal can view and edit the entity. EDIT = 1; + // The principal has no access to the entity, even when a broader grant would otherwise allow it. NONE = 2; } -// Message used when receiving queries for access permission levels. +// Selects entities by the access level a user or team has to them. message AccessPermissionQuery { + // An access level to match against. enum AccessLevel { + // Matches entities the principal can at least view. VIEW = 0; + // Matches entities the principal can edit. EDIT = 1; + // Matches entities the principal owns. OWNER = 2; } + // How a condition compares the principal's access with the requested level. enum Operator { + // Matches when the principal has the access level. IS = 0; + // Matches when the principal does not have the access level. IS_NOT = 1; } // A single predicate: e.g. "access IS EDIT" or "access IS_NOT OWNER". message Condition { + // How to compare the principal's access with `level`. .bitdrift.public.unary.admin.v1.AccessPermissionQuery.Operator operator = 1 [(validate.rules).enum = {defined_only: true}]; + // The access level to compare against. .bitdrift.public.unary.admin.v1.AccessPermissionQuery.AccessLevel level = 2 [(validate.rules).enum = {defined_only: true}]; } // All conditions must be true (logical AND). message AllOf { + // The conditions that must all match. repeated .bitdrift.public.unary.admin.v1.AccessPermissionQuery.Condition conditions = 1 [(validate.rules).repeated = { min_items: 1 max_items: 20 @@ -52,42 +66,53 @@ message AccessPermissionQuery { // A filter that matches when at least one AllOf group is satisfied (logical OR of ANDs). // Example: (IS VIEW AND IS_NOT OWNER) OR (IS EDIT) message AccessFilter { + // The condition groups, at least one of which must match. repeated .bitdrift.public.unary.admin.v1.AccessPermissionQuery.AllOf any_of = 1 [(validate.rules).repeated = { min_items: 1 max_items: 20 }]; } + // Selects entities by the access a user has, directly or through their teams. message Individual { + // The ID of the user whose access is evaluated. string user_id = 1 [(validate.rules).string = { min_len: 1 max_len: 100 }]; + // The access conditions the user must satisfy. .bitdrift.public.unary.admin.v1.AccessPermissionQuery.AccessFilter filter = 2; } + // Selects entities by the access a team has. message Team { + // The ID of the team whose access is evaluated. string team_id = 1 [(validate.rules).string = { min_len: 1 max_len: 100 }]; + // The access conditions the team must satisfy. .bitdrift.public.unary.admin.v1.AccessPermissionQuery.AccessFilter filter = 2; } oneof type { option (validate.required) = true; + // Queries the access of a user. .bitdrift.public.unary.admin.v1.AccessPermissionQuery.Individual individual = 1; + // Queries the access of a team. .bitdrift.public.unary.admin.v1.AccessPermissionQuery.Team team = 2; } } -// Used to represent the current access permission of an entity. -// This gives the full scope of which users/teams have what level of access, -// the level of access given to the entire org, and the ownership of the entity (team or user). +// The current access permissions of an entity. +// +// Lists the access level granted to each user and team, the access level granted to the entire +// organization, and the user or team that owns the entity. message AccessPermission { + // Access granted to a single user. message Individual { // The user who currently has access. .bitdrift.public.unary.common.v1.Owner details = 1; @@ -96,6 +121,7 @@ message AccessPermission { .bitdrift.public.unary.admin.v1.AccessLevel access = 2 [(validate.rules).enum = {defined_only: true}]; } + // Access granted to a team. message Team { // The team that currently has access. .bitdrift.public.unary.admin.v1.Team details = 1; @@ -104,15 +130,19 @@ message AccessPermission { .bitdrift.public.unary.admin.v1.AccessLevel access = 2 [(validate.rules).enum = {defined_only: true}]; } + // Access granted to the entire organization. message Org { // The access level currently granted to the organization. .bitdrift.public.unary.admin.v1.AccessLevel access = 1 [(validate.rules).enum = {defined_only: true}]; } + // The user or team that owns the entity. message Owner { oneof id { + // The user that owns the entity. .bitdrift.public.unary.common.v1.Owner user = 1; + // The team that owns the entity. .bitdrift.public.unary.admin.v1.Team team = 2; } } @@ -131,8 +161,11 @@ message AccessPermission { .bitdrift.public.unary.admin.v1.AccessPermission.Owner owner = 4; } +// Request to set the access permissions of a dashboard, view, or workflow. message SetAccessRequest { + // The access permissions to set. message SetAccessPermission { + // Access to grant a single user. message Individual { // The ID of the user to set access for. string id = 1 [(validate.rules).string = { @@ -144,6 +177,7 @@ message SetAccessRequest { .bitdrift.public.unary.admin.v1.AccessLevel access = 2 [(validate.rules).enum = {defined_only: true}]; } + // Access to grant a team. message Team { // The ID of the team to set access for. string id = 1 [(validate.rules).string = { @@ -155,19 +189,23 @@ message SetAccessRequest { .bitdrift.public.unary.admin.v1.AccessLevel access = 2 [(validate.rules).enum = {defined_only: true}]; } + // Access to grant the entire organization. message Org { // The access level to set for the organization. Defaults to VIEW when omitted. .bitdrift.public.unary.admin.v1.AccessLevel access = 1 [(validate.rules).enum = {defined_only: true}]; } + // The user or team to make the owner of the entity. message Owner { oneof id { option (validate.required) = true; + // The ID of the user to make the owner. string user_id = 1 [(validate.rules).string = { min_len: 1 max_len: 100 }]; + // The ID of the team to make the owner. string team_id = 2 [(validate.rules).string = { min_len: 1 max_len: 100 @@ -189,20 +227,24 @@ message SetAccessRequest { .bitdrift.public.unary.admin.v1.SetAccessRequest.SetAccessPermission.Owner owner = 4; } + // The access permissions to set on the target entity. .bitdrift.public.unary.admin.v1.SetAccessRequest.SetAccessPermission access_permission = 1; oneof target { option (validate.required) = true; + // The ID of the dashboard to update. string dashboard_id = 2 [(validate.rules).string = { min_len: 1 max_len: 100 }]; + // The ID of the view to update. string view_id = 3 [(validate.rules).string = { min_len: 1 max_len: 100 }]; + // The ID of the workflow to update. string workflow_id = 4 [(validate.rules).string = { min_len: 1 max_len: 100 @@ -210,6 +252,7 @@ message SetAccessRequest { } } +// Response containing the updated access permissions. message SetAccessResponse { // The new access permissions for the updated entity. .bitdrift.public.unary.admin.v1.AccessPermission result = 1; diff --git a/src/bitdrift/public/unary/admin/v1/admin.proto b/src/bitdrift/public/unary/admin/v1/admin.proto index f099f1d2..298e137f 100644 --- a/src/bitdrift/public/unary/admin/v1/admin.proto +++ b/src/bitdrift/public/unary/admin/v1/admin.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.admin.v1; diff --git a/src/bitdrift/public/unary/admin/v1/api.proto b/src/bitdrift/public/unary/admin/v1/api.proto index 72a9b90e..a7caa4cb 100644 --- a/src/bitdrift/public/unary/admin/v1/api.proto +++ b/src/bitdrift/public/unary/admin/v1/api.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.admin.v1; diff --git a/src/bitdrift/public/unary/admin/v1/connector.proto b/src/bitdrift/public/unary/admin/v1/connector.proto index 6c949dde..60ce36c9 100644 --- a/src/bitdrift/public/unary/admin/v1/connector.proto +++ b/src/bitdrift/public/unary/admin/v1/connector.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.admin.v1; diff --git a/src/bitdrift/public/unary/admin/v1/keys.proto b/src/bitdrift/public/unary/admin/v1/keys.proto index 18d3ed19..6b7efe7a 100644 --- a/src/bitdrift/public/unary/admin/v1/keys.proto +++ b/src/bitdrift/public/unary/admin/v1/keys.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.admin.v1; diff --git a/src/bitdrift/public/unary/admin/v1/notifications.proto b/src/bitdrift/public/unary/admin/v1/notifications.proto index 0b80e3ed..13405f9f 100644 --- a/src/bitdrift/public/unary/admin/v1/notifications.proto +++ b/src/bitdrift/public/unary/admin/v1/notifications.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.admin.v1; diff --git a/src/bitdrift/public/unary/admin/v1/permission.proto b/src/bitdrift/public/unary/admin/v1/permission.proto index 24ee7a32..ba6c0069 100644 --- a/src/bitdrift/public/unary/admin/v1/permission.proto +++ b/src/bitdrift/public/unary/admin/v1/permission.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.admin.v1; diff --git a/src/bitdrift/public/unary/admin/v1/teams.proto b/src/bitdrift/public/unary/admin/v1/teams.proto index fedf510a..a4230990 100644 --- a/src/bitdrift/public/unary/admin/v1/teams.proto +++ b/src/bitdrift/public/unary/admin/v1/teams.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.admin.v1; diff --git a/src/bitdrift/public/unary/admin/v1/users.proto b/src/bitdrift/public/unary/admin/v1/users.proto index 8f218397..6b6c7b48 100644 --- a/src/bitdrift/public/unary/admin/v1/users.proto +++ b/src/bitdrift/public/unary/admin/v1/users.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.admin.v1; diff --git a/src/bitdrift/public/unary/admin/v1/view.proto b/src/bitdrift/public/unary/admin/v1/view.proto index ba53afef..100879ba 100644 --- a/src/bitdrift/public/unary/admin/v1/view.proto +++ b/src/bitdrift/public/unary/admin/v1/view.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.admin.v1; @@ -224,10 +225,7 @@ message ListViewsRequest { // Selects which service's views to return. .bitdrift.public.unary.admin.v1.ListViewsRequest.ServiceType service_type = 1 [(validate.rules).enum = {defined_only: true}]; - // The preferred pagination parameters for the request. - // - // If both pagination and deprecated_offset or deprecated_limit are provided, - // pagination takes precedence. + // Selects the page of views to return. .bitdrift.public.unary.common.v1.Pagination pagination = 5; // An optional name to filter by. diff --git a/src/bitdrift/public/unary/alerts/v1/alerts.proto b/src/bitdrift/public/unary/alerts/v1/alerts.proto index e6195a0c..a2301713 100644 --- a/src/bitdrift/public/unary/alerts/v1/alerts.proto +++ b/src/bitdrift/public/unary/alerts/v1/alerts.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.alerts.v1; diff --git a/src/bitdrift/public/unary/alerts/v1/issue_alerts.proto b/src/bitdrift/public/unary/alerts/v1/issue_alerts.proto index f91bfa7a..9c5f3d87 100644 --- a/src/bitdrift/public/unary/alerts/v1/issue_alerts.proto +++ b/src/bitdrift/public/unary/alerts/v1/issue_alerts.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.alerts.v1; diff --git a/src/bitdrift/public/unary/alerts/v1/notifications.proto b/src/bitdrift/public/unary/alerts/v1/notifications.proto index a8784f06..c7cb501f 100644 --- a/src/bitdrift/public/unary/alerts/v1/notifications.proto +++ b/src/bitdrift/public/unary/alerts/v1/notifications.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.alerts.v1; diff --git a/src/bitdrift/public/unary/charts/v1/chart_id.proto b/src/bitdrift/public/unary/charts/v1/chart_id.proto index b94e6221..8ba0567a 100644 --- a/src/bitdrift/public/unary/charts/v1/chart_id.proto +++ b/src/bitdrift/public/unary/charts/v1/chart_id.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.charts.v1; diff --git a/src/bitdrift/public/unary/charts/v1/chart_metadata.proto b/src/bitdrift/public/unary/charts/v1/chart_metadata.proto index 4dbc61cd..e8b1fc15 100644 --- a/src/bitdrift/public/unary/charts/v1/chart_metadata.proto +++ b/src/bitdrift/public/unary/charts/v1/chart_metadata.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.charts.v1; @@ -294,8 +295,7 @@ message ChartMetadata { // its server-generated time_series_id. repeated .bitdrift.public.unary.charts.v1.ChartMetadata.MetricChartMetadata.TimeSeriesMetadata metadata = 4 [(validate.rules).repeated = {max_items: 100}]; - // Heat map properties stored independently from `display_mode`. When absent, clients may - // fall back to the deprecated properties in `heat_map_display_mode` for compatibility. + // Heat map properties, set independently from `display_mode`. .bitdrift.public.unary.charts.v1.ChartMetadata.MetricChartMetadata.HeatMapConfiguration heat_map_configuration = 12; } diff --git a/src/bitdrift/public/unary/common/v1/common.proto b/src/bitdrift/public/unary/common/v1/common.proto index 8e638f49..6d09123b 100644 --- a/src/bitdrift/public/unary/common/v1/common.proto +++ b/src/bitdrift/public/unary/common/v1/common.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.common.v1; diff --git a/src/bitdrift/public/unary/dashboards/v1/api.proto b/src/bitdrift/public/unary/dashboards/v1/api.proto index 386a5dfc..19964dcc 100644 --- a/src/bitdrift/public/unary/dashboards/v1/api.proto +++ b/src/bitdrift/public/unary/dashboards/v1/api.proto @@ -4,10 +4,12 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.dashboards.v1; +import "bitdrift/public/shared/annotations/dashboard_layout.proto"; import "bitdrift/public/shared/platform/v1/platform.proto"; import "bitdrift/public/shared/workflows/v1/time_series.proto"; import "bitdrift/public/unary/admin/v1/access.proto"; @@ -49,11 +51,12 @@ message ResolvedChart { // data API in order to fetch/stream the data. .bitdrift.public.unary.charts.v1.ChartIdentifier id = 1 [(validate.rules).message = {required: true}]; + // Options for a line chart. message Line { // If the line chart contains histograms with a top-K grouping, this - // provides a best-effort list of suggested percentiles. The chart should - // default to the 0th element in the list, and callers may override that - // value via the chart API. + // provides a best-effort list of suggested percentiles. The first element + // is the suggested default, and callers may select a different percentile + // via the chart API. // // If this list is empty, the chart does not have suggested default // percentile values, but callers may still choose a percentile via the @@ -65,14 +68,15 @@ message ResolvedChart { bool supports_multiple_percentiles = 3; } + // Identifies a pie chart. Pie charts have no additional options. message Pie {} // The legacy histogram bar visualization. message Bar { // If the line chart corresponding to this bar chart contains histograms with a // top-K grouping, this provides a best-effort list of suggested - // percentiles. The chart should default to the 0th element in the list, - // and callers may override that value via the chart API. + // percentiles. The first element is the suggested default, and callers may + // select a different percentile via the chart API. // // If this list is empty, the chart does not have suggested default // percentile values, but callers may still choose a percentile via the @@ -90,15 +94,18 @@ message ResolvedChart { // A generic metric heat map renders aggregate values as stat tiles. message MetricHeatMap {} + // Identifies a funnel chart. Funnel charts have no additional options. message Funnel {} + // Identifies a Sankey chart. Sankey charts have no additional options. message Sankey {} + // Options for a table chart. message Table { // If the line chart corresponding to this table contains histograms with a // top-K grouping, this provides a best-effort list of suggested - // percentiles. The chart should default to the 0th element in the list, - // and callers may override that value via the chart API. + // percentiles. The first element is the suggested default, and callers may + // select a different percentile via the chart API. // // If this list is empty, the chart does not have suggested default // percentile values, but callers may still choose a percentile via the @@ -110,8 +117,11 @@ message ResolvedChart { bool supports_multiple_percentiles = 2; } + // Identifies a session capture chart, which lists the sessions captured by its backing + // workflow. Query the captured sessions with `GetChartsData`. message SessionCapture {} + // The deployment status of the workflow that backs a chart. message BackingWorkflowDeploymentStatus { // The version number of the latest workflow deployment. uint64 version = 1; @@ -174,6 +184,7 @@ message ResolvedChart { .bitdrift.public.unary.dashboards.v1.DashboardChartMetadataOverrides dashboard_metadata_overrides = 28; } +// The size, position, and visibility of a chart or component on a dashboard. message DashboardLayoutSettings { // The number of columns this chart/component should span in the dashboard. optional uint32 column_span = 1 [(validate.rules).uint32 = {gt: 0}]; @@ -181,7 +192,7 @@ message DashboardLayoutSettings { // The number of rows this chart/component should span in the dashboard. optional uint32 row_span = 2 [(validate.rules).uint32 = {gt: 0}]; - // If true, the chart should be hidden from the dashboard. + // Whether the chart or component is hidden on the dashboard. bool is_hidden = 3; // The x/y position of the component within the dashboard. This, combined with the @@ -189,9 +200,11 @@ message DashboardLayoutSettings { // the chart will be placed at the end of the dashboard. optional uint32 x = 4; + // The vertical position of the component within the dashboard. optional uint32 y = 5; } +// A category of charts on a health dashboard. message DashboardGroup { // All the charts that should be displayed on this dashboard. repeated .bitdrift.public.unary.dashboards.v1.ResolvedChart charts = 1; @@ -203,11 +216,13 @@ message DashboardGroup { }]; // The minimum query interval for this group. For example, if this is set to - // 7 days, the default viewing window should be at least 7 days. + // 7 days, queries for this group should cover at least 7 days. .google.protobuf.Duration minimum_query_interval = 3; } +// Identifies a health dashboard or a custom dashboard. message DashboardIdentifier { + // Identifies the health dashboard for a platform. message HealthDashboard { // An optional target platform. If not provided, the dashboard groups for the default app will be // returned. The default app is the first element in the list of apps returned by the @@ -215,7 +230,9 @@ message DashboardIdentifier { .bitdrift.public.shared.platform.v1.Platform platform_target = 1; } + // Identifies a custom dashboard by ID. message CustomDashboard { + // The ID of the custom dashboard. string id = 1 [(validate.rules).string = { min_len: 1 max_len: 100 @@ -224,32 +241,43 @@ message DashboardIdentifier { oneof type { option (validate.required) = true; + // Selects a health dashboard. .bitdrift.public.unary.dashboards.v1.DashboardIdentifier.HealthDashboard health_dashboard = 1; + // Selects a custom dashboard. .bitdrift.public.unary.dashboards.v1.DashboardIdentifier.CustomDashboard custom_dashboard = 2; } } +// Request for `GetDashboard`. message GetDashboardRequest { // The identifier of the dashboard to fetch. .bitdrift.public.unary.dashboards.v1.DashboardIdentifier id = 3; } +// Response for `GetDashboard`. message GetDashboardResponse { + // The requested dashboard. .bitdrift.public.unary.dashboards.v1.Dashboard dashboard = 5; } +// A health dashboard or a custom dashboard. message Dashboard { + // A health dashboard, made of categorized chart groups for a platform. message HealthDashboard { + // The identifier of this health dashboard. .bitdrift.public.unary.dashboards.v1.DashboardIdentifier.HealthDashboard id = 1; + // The chart groups on this dashboard. repeated .bitdrift.public.unary.dashboards.v1.DashboardGroup dashboard_group = 2; // The possible platforms for this dashboard. repeated .bitdrift.public.shared.platform.v1.Platform platforms = 3; } + // A custom dashboard, made of tabs that hold charts and stylistic components. message CustomDashboard { + // The ID of the custom dashboard. string id = 1 [(validate.rules).string = { min_len: 1 max_len: 100 @@ -264,8 +292,11 @@ message Dashboard { // The last time this dashboard was viewed by the current user. .google.protobuf.Timestamp current_user_last_viewed = 8; + // A tab on a custom dashboard. message DashboardTab { + // A chart placed on a dashboard tab. message Chart { + // The ID of this chart within the dashboard. string id = 1 [(validate.rules).string = { min_len: 1 max_len: 100 @@ -282,11 +313,13 @@ message Dashboard { } } + // The ID of the tab. string id = 1 [(validate.rules).string = { min_len: 1 max_len: 100 }]; + // The display name of the tab. string name = 2 [(validate.rules).string = { min_len: 1 max_len: 255 @@ -300,6 +333,7 @@ message Dashboard { repeated .bitdrift.public.unary.dashboards.v1.DashboardStylisticComponent components = 4; } + // The tabs of the dashboard, in order. repeated .bitdrift.public.unary.dashboards.v1.Dashboard.CustomDashboard.DashboardTab tabs = 2; // The variables that can be used to filter the dashboard. These variables are the intersection @@ -310,8 +344,10 @@ message Dashboard { // A dashboard may be editable by multiple users, if editing permissions are shared with an individual, team, or org. .bitdrift.public.unary.common.v1.Owner owner = 4; + // Whether the authenticated user has marked this dashboard as a favorite. bool current_user_favorited = 5; + // Whether the authenticated user can edit this dashboard, and the reason. .bitdrift.public.unary.common.v1.Permission current_user_can_edit = 6; // The variables that are applied to every chart referenced in this dashboard. @@ -329,8 +365,10 @@ message Dashboard { oneof type { option (validate.required) = true; + // Set when the dashboard is a health dashboard. .bitdrift.public.unary.dashboards.v1.Dashboard.HealthDashboard health_dashboard = 2; + // Set when the dashboard is a custom dashboard. .bitdrift.public.unary.dashboards.v1.Dashboard.CustomDashboard custom_dashboard = 3; } @@ -338,7 +376,9 @@ message Dashboard { .bitdrift.public.unary.admin.v1.AccessPermission current_access_permissions = 4; } +// Request for `ListDashboards`. message ListDashboardsRequest { + // Criteria that limit which dashboards are returned. message Filters { // Filters dashboards by access permission levels for a specified user. // For example, callers can request dashboards where a user has EDIT access. @@ -352,11 +392,17 @@ message ListDashboardsRequest { optional bool favorites = 3; } + // A dashboard attribute and direction to order results by. message Sort { + // Dashboard attributes that results can be ordered by. enum SortKey { + // Unspecified sort key. Not a valid value. SORT_KEY_UNSPECIFIED = 0; + // Orders by dashboard title, case-insensitively. DASHBOARD_NAME = 1; + // Orders by the dashboard owner's name. OWNER_NAME = 2; + // Orders by when the authenticated user last viewed the dashboard. LAST_VIEWED = 3; } @@ -366,22 +412,31 @@ message ListDashboardsRequest { not_in: [0] }]; + // The direction to order by. .bitdrift.public.unary.common.v1.SortDirection direction = 2 [(validate.rules).enum = {defined_only: true}]; } + // The offset and limit of the page of dashboards to return. .bitdrift.public.unary.common.v1.Pagination pagination = 1; + // Optional criteria that limit which dashboards are returned. .bitdrift.public.unary.dashboards.v1.ListDashboardsRequest.Filters filters = 3; + // The orderings to apply, in priority order. Each later entry orders dashboards that tie on + // the earlier entries. If empty, the most recently created dashboards are returned first. repeated .bitdrift.public.unary.dashboards.v1.ListDashboardsRequest.Sort sort = 4 [(validate.rules).repeated = {max_items: 100}]; } +// Response for `ListDashboards`. message ListDashboardsResponse { + // The dashboards on the requested page. repeated .bitdrift.public.unary.dashboards.v1.Dashboard dashboards = 1; + // The total number of dashboards that match the request filters. uint64 total = 2; } +// Request for `GetWorkflowCharts`. message GetWorkflowChartsRequest { // The ID of the workflow to fetch the charts for. string workflow_id = 2 [ @@ -390,10 +445,13 @@ message GetWorkflowChartsRequest { ]; } +// Response for `GetWorkflowCharts`. message GetWorkflowChartsResponse { + // The charts defined by the workflow. repeated .bitdrift.public.unary.dashboards.v1.ResolvedChart charts = 1; } +// Selects two time series in a chart to compare. message InsightComparisonConfiguration { // The id of the first time series to compare against. string lhs_id = 1 [(validate.rules).string = { @@ -408,6 +466,7 @@ message InsightComparisonConfiguration { }]; } +// Options for querying a Sankey chart. message SankeyConfiguration { // The number of top-K paths to use when rendering the Sankey chart. // Defaults to 100 if not provided. @@ -419,16 +478,19 @@ message SankeyConfiguration { uint64 compaction_target = 2; } +// Options for aggregating counter time series in a chart. message CounterConfiguration { // The aggregation to use when presenting counter values in a table. .bitdrift.public.shared.workflows.v1.Counter.CounterAggregationType aggregation_type = 1 [(validate.rules).enum = {defined_only: true}]; } +// Options for aggregating rate time series in a chart. message RateConfiguration { // The aggregation to use when presenting rate values in a table. .bitdrift.public.shared.workflows.v1.Rate.RateAggregationType aggregation_type = 1 [(validate.rules).enum = {defined_only: true}]; } +// Options for querying a session capture chart. message SessionCaptureConfiguration { // Continues pagination using an opaque server token. .bitdrift.public.unary.common.v1.TokenPagination token_pagination = 1; @@ -437,6 +499,7 @@ message SessionCaptureConfiguration { repeated .bitdrift.public.shared.workflows.v1.AndFilter or_filter = 2 [(validate.rules).repeated = {max_items: 10}]; } +// Selects a chart and the options used to query its data. message ChartRequest { // The identifier of the chart to fetch data for. .bitdrift.public.unary.charts.v1.ChartIdentifier chart_id = 1 [(validate.rules).message = {required: true}]; @@ -455,32 +518,36 @@ message ChartRequest { // Optional configuration for the sankey chart. .bitdrift.public.unary.dashboards.v1.SankeyConfiguration sankey_configuration = 7; - // Counter configuration for the chart. Currently this is only used for resolving which table - // type to show in the case of a group by query. + // Selects how counter values are aggregated into a single value per group when chart data is + // returned as aggregated values, such as table data. .bitdrift.public.unary.dashboards.v1.CounterConfiguration counter_configuration = 8; - // Rate configuration for the chart. Currently this is only used for resolving which table - // type to show in the case of a group by query. + // Selects how rate values are aggregated into a single value per group when chart data is + // returned as aggregated values, such as table data. .bitdrift.public.unary.dashboards.v1.RateConfiguration rate_configuration = 9; // Optional configuration for session capture charts. .bitdrift.public.unary.dashboards.v1.SessionCaptureConfiguration session_capture_configuration = 13; - // Override the display mode for this chart. - // Uses the same oneof structure as RuleChartConfiguration.display_mode. - // If unset it will use the display mode defined in the workflow's rule chart configuration. + // Overrides the display mode for this chart. + // If unset, the display mode configured for the chart in its workflow is used. oneof display_mode { + // Returns the chart as time series. .bitdrift.public.unary.charts.v1.ChartMetadata.MetricChartMetadata.TimeSeriesDisplayMode time_series_display_mode = 10; + // Returns the chart as a table of aggregated values. .bitdrift.public.unary.charts.v1.ChartMetadata.MetricChartMetadata.TableDisplayMode table_display_mode = 11; // This is only valid if all time series in the chart are histograms. .bitdrift.public.unary.charts.v1.ChartMetadata.MetricChartMetadata.HistogramBarChartDisplayMode histogram_bar_chart_display_mode = 12; + // Returns the chart as metric heat map tiles. .bitdrift.public.unary.charts.v1.ChartMetadata.MetricChartMetadata.HeatMapDisplayMode heat_map_display_mode = 14; + // Returns the chart as pie chart data. .bitdrift.public.unary.charts.v1.ChartMetadata.MetricChartMetadata.PieChartDisplayMode pie_chart_display_mode = 16; + // Returns the chart as basic categorical bar data. .bitdrift.public.unary.charts.v1.ChartMetadata.MetricChartMetadata.BasicBarChartDisplayMode basic_bar_chart_display_mode = 17; // This is only valid if all time series in the chart are histograms. @@ -494,11 +561,13 @@ message ChartRequest { // Identifies chart data dimensions that may be deferred during GetChartsData and hydrated in a // follow-up call. enum DeferredChartsDataDimension { + // Unspecified dimension. Not a valid value. DEFERRED_CHARTS_DATA_DIMENSION_UNSPECIFIED = 0; // Unique-device counts present in chart data when TrackUnique is configured. DEFERRED_CHARTS_DATA_DIMENSION_UNIQUE_DEVICES = 1; } +// Request for `GetChartsData`. message GetChartsDataRequest { // List of all charts to fetch data for. repeated .bitdrift.public.unary.dashboards.v1.ChartRequest charts = 1 [(validate.rules).repeated = { @@ -506,6 +575,7 @@ message GetChartsDataRequest { max_items: 100 }]; + // The time range to query. .bitdrift.public.unary.common.v1.TimeRange time_range = 8; // If this is empty, the platform filter for the workflow backing each chart will be used. @@ -521,6 +591,7 @@ message GetChartsDataRequest { bool include_unique_device_counts = 9; } +// The resolved query state of a `GetChartsData` call, used to hydrate deferred chart data. message DeferredChartsDataContext { // The fully resolved chart requests for the original execution. // When the original request relied on top-K selection, each stored chart request should encode @@ -565,6 +636,7 @@ message LineChartResponse { repeated .bitdrift.public.shared.workflows.v1.TimeSeries time_series = 1; } +// Data for a pie chart. message PieChartResponse { // The complete table payload preserves rate details and deferred unique-device hydration. .bitdrift.public.unary.dashboards.v1.TableChartResponse table_data = 2; @@ -573,9 +645,11 @@ message PieChartResponse { // The complete table payload for basic categorical bars preserves rate details // and deferred unique-device hydration. message BasicBarChartResponse { + // The table data that backs the bars. .bitdrift.public.unary.dashboards.v1.TableChartResponse table_data = 1; } +// Data for a Sankey chart. message SankeyChartResponse { // A single state in the diagram. message Node { @@ -605,11 +679,13 @@ message SankeyChartResponse { repeated .bitdrift.public.unary.dashboards.v1.SankeyChartResponse.Link links = 2; } +// Data for a table chart. message TableChartResponse { // The tables to render for this chart. repeated .bitdrift.public.unary.dashboards.v1.Table tables = 1; } +// A table of aggregated values for one time series in a chart. message Table { // Headers for the columns of each group by field (for example, "country", "device_type", // etc.). If there are no group by fields this will be empty. @@ -624,21 +700,19 @@ message Table { // The unique devices for the entire table based on the TrackUnique configuration. optional uint64 unique_devices = 4; - // The title of table, which is derived from the TimeSeries title in the rule chart config. - string title = 5; - // The total count of cardinality overflows for this time series that occurred during the // query time period. .bitdrift.public.shared.workflows.v1.CardinalityOverflows cardinality_overflows = 6; // The ID that associates this table with its configured metric time series in the resolved - // chart metadata. + // chart metadata, including its display title. string time_series_id = 7 [(validate.rules).string = { min_len: 1 max_len: 255 }]; } +// A single aggregated value in a table. message TableValue { // The numeric value for this cell. double value = 1; @@ -647,9 +721,10 @@ message TableValue { .bitdrift.public.shared.workflows.v1.RateDetails rate_details = 2; } -// Used for generic metric tree maps. Each tile contains a reduced metric value +// Data for a metric heat map chart. Each tile contains a reduced metric value // and, when available, the corresponding time series for its sparkline. message MetricHeatMapChartResponse { + // A heat map tile for one combination of group-by values. message Tile { // The ordered group-by labels identifying this tile. repeated .bitdrift.public.shared.workflows.v1.LabelPair labels = 1 [(validate.rules).repeated.max_items = 100]; @@ -668,6 +743,7 @@ message MetricHeatMapChartResponse { repeated .bitdrift.public.unary.dashboards.v1.MetricHeatMapChartResponse.Tile tiles = 1; } +// A table row for one combination of group-by values. message TableRow { // Values that match `group_column_key_names`. repeated string group_column_values = 1; @@ -679,6 +755,7 @@ message TableRow { optional uint64 unique_devices = 3; } +// Data for a funnel chart. message FunnelChartResponse { // The funnel's steps. // The order of steps in the list corresponds to the order of metric IDs in @@ -687,7 +764,9 @@ message FunnelChartResponse { repeated .bitdrift.public.unary.charts.v1.FunnelStep steps = 1; } +// Histogram bucket data for a chart. message HistogramBarChartResponse { + // A histogram bucket covering a range of values. message Bucket { // The beginning of the range for this bucket, inclusive. double begin = 1; @@ -699,6 +778,7 @@ message HistogramBarChartResponse { uint64 count = 3; } + // Histogram buckets for one combination of group-by values. message PerGroupBy { // The value of the dimension that this group represents. repeated string dimensions = 1; @@ -710,15 +790,12 @@ message HistogramBarChartResponse { optional uint64 unique_devices = 3; } + // Histogram data for one time series in the chart. message PerTimeSeries { // Headers for the columns of each group by field (for example, "country", "device_type", // etc.). If there are no group by fields this will be empty. repeated string dimension_names = 1; - // The title of the histogram data, which is derived from the TimeSeries title in the rule chart - // config. - string title = 2; - // The total count of cardinality overflows for this time series that occurred during the // query time period. .bitdrift.public.shared.workflows.v1.CardinalityOverflows cardinality_overflows = 3; @@ -728,7 +805,7 @@ message HistogramBarChartResponse { repeated .bitdrift.public.unary.dashboards.v1.HistogramBarChartResponse.PerGroupBy per_group_by = 4; // The ID that associates this data with its configured metric time series in the resolved - // chart metadata. + // chart metadata, including its display title. string time_series_id = 5 [(validate.rules).string = { min_len: 1 max_len: 255 @@ -739,6 +816,7 @@ message HistogramBarChartResponse { repeated .bitdrift.public.unary.dashboards.v1.HistogramBarChartResponse.PerTimeSeries per_time_series = 1; } +// Data for a session capture chart. message SessionCaptureChartResponse { // The captured sessions that matched the request. repeated .bitdrift.public.unary.workflows.v1.CapturedSession captured_sessions = 1; @@ -750,6 +828,7 @@ message SessionCaptureChartResponse { uint32 daily_limit_remaining = 3; } +// Data for a single chart. message ChartData { // The chart that this data belongs to. .bitdrift.public.unary.charts.v1.ChartIdentifier chart_id = 1 [(validate.rules).message = {required: true}]; @@ -795,7 +874,7 @@ message ChartData { // Set to true if the chart is not found. bool chart_not_found = 12 [(validate.rules).bool = {const: true}]; - // Aggregate metric tree map data. + // Metric heat map data for the chart. .bitdrift.public.unary.dashboards.v1.MetricHeatMapChartResponse metric_heatmap_data = 15; // Basic categorical bar-chart data for the chart. @@ -803,6 +882,7 @@ message ChartData { } } +// Response for `GetChartsData`. message GetChartsDataResponse { // Data for each of the requested data. The order of the data will match the // order of the chart ids in the request. @@ -814,13 +894,16 @@ message GetChartsDataResponse { .bitdrift.public.unary.dashboards.v1.DeferredChartsDataContext deferred_data_context = 2; } +// Request for `HydrateChartsData`. message HydrateChartsDataRequest { // Typed passthrough context returned by GetChartsData for the original execution. The chart // requests embedded in this context determine which charts are hydrated. .bitdrift.public.unary.dashboards.v1.DeferredChartsDataContext deferred_data_context = 1 [(validate.rules).message = {required: true}]; } +// Response for `HydrateChartsData`. message HydrateChartsDataResponse { + // Hydrated data for one chart. message ChartDataHydration { // The hydrated chart data. Dimensions not included in hydrated_dimensions are left at their // default values. @@ -847,6 +930,7 @@ message HydrateChartsDataResponse { }]; } +// Request for `GetActiveDevices`. message GetActiveDevicesRequest { // The time range to inspect for active devices. .bitdrift.public.unary.common.v1.TimeRange time_range = 7; @@ -855,11 +939,13 @@ message GetActiveDevicesRequest { repeated .bitdrift.public.shared.platform.v1.Platform platform_filter = 6 [(validate.rules).repeated.max_items = 10]; } +// Response for `GetActiveDevices`. message GetActiveDevicesResponse { // The number of distinct active devices observed in the requested time range. uint64 devices = 1; } +// Request for `GetUniqueAppIds`. message GetUniqueAppIdsRequest { // The start of the time range to inspect. Defaults to 30 days before the // current time when unset. @@ -888,6 +974,7 @@ message GetUniqueAppIdsRequest { }]; } +// Response for `GetUniqueAppIds`. message GetUniqueAppIdsResponse { // The distinct platform, app ID, and app version combinations observed in the // requested time range. This is sorted by platform/app activity volume. @@ -900,20 +987,36 @@ message GetUniqueAppIdsResponse { bool versions_limited = 8; } +// A non-chart component on a dashboard, such as text or a divider. message DashboardStylisticComponent { + // A divider that separates sections of a dashboard. Dividers have no additional options. message Divider {} + // A block of text on a dashboard. message TextComponent { + enum TextVariant { + TEXT_VARIANT_UNSPECIFIED = 0; + TEXT_VARIANT_HEADING_1 = 1 [(shared.annotations.minimum_row_span) = 4]; + TEXT_VARIANT_HEADING_2 = 2 [(shared.annotations.minimum_row_span) = 3]; + TEXT_VARIANT_BODY = 3 [(shared.annotations.minimum_row_span) = 2]; + } + // The text to display in the component. string text = 1 [(validate.rules).string = { min_len: 1 max_len: 5000 }]; - // The variant of the text component, e.g. "h1", "h2", "p", etc. - string variant = 2 [(validate.rules).string = { - min_len: 1 - max_len: 50 + // The legacy text style. New callers should use `text_variant`. When both fields are set, + // `text_variant` takes precedence. + string variant = 2 [(validate.rules).string = {max_len: 50}]; + + // The semantic text variant. `dashboard_layout_settings.row_span` must be at least 4 for + // `TEXT_VARIANT_HEADING_1`, 3 for `TEXT_VARIANT_HEADING_2`, and 2 for + // `TEXT_VARIANT_BODY`. + optional .bitdrift.public.unary.dashboards.v1.DashboardStylisticComponent.TextComponent.TextVariant text_variant = 3 [(validate.rules).enum = { + defined_only: true + not_in: [0] }]; } @@ -934,9 +1037,11 @@ message DashboardStylisticComponent { max_len: 100 }]; + // The component's size and position on the dashboard. .bitdrift.public.unary.dashboards.v1.DashboardLayoutSettings dashboard_layout_settings = 4; } +// A variable that can filter the charts on a dashboard. message DashboardVariable { oneof variable_type { option (validate.required) = true; @@ -948,9 +1053,12 @@ message DashboardVariable { .google.protobuf.Timestamp earliest_contiguous_deployed_time = 2; } +// A chart placement on a custom dashboard: the chart, its layout, and its metadata overrides. message ChartComponentLayout { + // The chart to place on the dashboard. .bitdrift.public.unary.charts.v1.ChartIdentifier chart_id = 1; + // The chart's size and position on the dashboard. .bitdrift.public.unary.dashboards.v1.DashboardLayoutSettings layout_settings = 2; oneof metadata_update { @@ -967,14 +1075,20 @@ message ChartComponentLayout { } } +// Request for `FavoriteCustomDashboard`. message FavoriteCustomDashboardRequest { + // The dashboard whose favorite status is toggled. .bitdrift.public.unary.dashboards.v1.DashboardIdentifier identifier = 1; } +// Response for `FavoriteCustomDashboard`. message FavoriteCustomDashboardResponse {} +// Request for `UpsertCustomDashboard`. message UpsertCustomDashboardRequest { + // A tab on the dashboard. message DashboardTab { + // A chart placed on the tab. message Chart { // Optional ID of the chart being upsert. If not provided, the API will assume the chart needs to be created. optional string id = 1 [(validate.rules).string = { @@ -996,12 +1110,11 @@ message UpsertCustomDashboardRequest { // include all components, whether they are being updated or not. repeated .bitdrift.public.unary.dashboards.v1.UpsertCustomDashboardRequest.DashboardTab.Chart charts = 2 [(validate.rules).repeated = {max_items: 500}]; - // List of all stylistic components that should be rendered on the dashboard. The array *MUST* - // include all components, whether they are being updated or not. + // List of all stylistic components on the tab. The array *MUST* include all components, + // whether they are being updated or not. repeated .bitdrift.public.unary.dashboards.v1.DashboardStylisticComponent stylistic_components = 3 [(validate.rules).repeated = {max_items: 500}]; - // Optional display name/title for this dashboard tab. If unset, the tab will not have an explicit - // stored name and clients may derive an appropriate default label when rendering. + // Optional display name for this dashboard tab. If unset, the tab has no stored name. optional string name = 4 [(validate.rules).string = { min_len: 1 max_len: 255 @@ -1014,30 +1127,38 @@ message UpsertCustomDashboardRequest { max_len: 100 }]; + // The display title of the dashboard. string name = 2 [(validate.rules).string = { min_len: 1 max_len: 255 }]; + // The complete set of tabs for the dashboard. This replaces the dashboard's existing tabs. repeated .bitdrift.public.unary.dashboards.v1.UpsertCustomDashboardRequest.DashboardTab tabs = 3 [(validate.rules).repeated = {max_items: 100}]; // The variables that are applied to every chart referenced in this dashboard. repeated .bitdrift.public.unary.workflows.v1.GroupBy.Value dashboard_variables = 5 [(validate.rules).repeated = {max_items: 10}]; } +// Response for `UpsertCustomDashboard`. message UpsertCustomDashboardResponse { + // The saved dashboard. .bitdrift.public.unary.dashboards.v1.Dashboard.CustomDashboard dashboard = 1; } +// Request for `DeleteCustomDashboard`. message DeleteCustomDashboardRequest { + // The ID of the custom dashboard to delete. string id = 1 [(validate.rules).string = { min_len: 1 max_len: 100 }]; } +// Response for `DeleteCustomDashboard`. message DeleteCustomDashboardResponse {} +// Request for `ListCharts`. message ListChartsRequest { // Filters to apply when listing charts. // Filters are additive; only charts that match all specified filters will be returned. @@ -1066,14 +1187,19 @@ message ListChartsRequest { optional string chart_name = 4 [(validate.rules).string = {max_len: 255}]; } + // The offset and limit of the page of charts to return. .bitdrift.public.unary.common.v1.Pagination pagination = 1; + // Optional criteria that limit which charts are returned. .bitdrift.public.unary.dashboards.v1.ListChartsRequest.Filters filters = 3; } +// Response for `ListCharts`. message ListChartsResponse { + // The charts on the requested page. repeated .bitdrift.public.unary.dashboards.v1.ResolvedChart charts = 1; + // The total number of charts that match the request filters. uint32 total_count = 2; } diff --git a/src/bitdrift/public/unary/debug_files/v1/api.proto b/src/bitdrift/public/unary/debug_files/v1/api.proto index 813e8fa5..23819e66 100644 --- a/src/bitdrift/public/unary/debug_files/v1/api.proto +++ b/src/bitdrift/public/unary/debug_files/v1/api.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.debug_files.v1; diff --git a/src/bitdrift/public/unary/debug_files/v1/debug_files.proto b/src/bitdrift/public/unary/debug_files/v1/debug_files.proto index 27257787..bf572a0e 100644 --- a/src/bitdrift/public/unary/debug_files/v1/debug_files.proto +++ b/src/bitdrift/public/unary/debug_files/v1/debug_files.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.debug_files.v1; diff --git a/src/bitdrift/public/unary/device_debug/v1/device_debug.proto b/src/bitdrift/public/unary/device_debug/v1/device_debug.proto index 692bd694..c59f3459 100644 --- a/src/bitdrift/public/unary/device_debug/v1/device_debug.proto +++ b/src/bitdrift/public/unary/device_debug/v1/device_debug.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.device_debug.v1; @@ -110,13 +111,19 @@ message SendDeviceCommandResponse { } } -// Requests a device command's current status without waiting for execution or upload to complete. +// Requests a device command's status, optionally waiting for execution and upload to complete. message GetDeviceCommandRequest { // The opaque identifier returned by SendDeviceCommand. string command_id = 1 [(validate.rules).string = { max_len: 36 uuid: true }]; + + // Maximum readiness wait in seconds, from 0 to 30. Omitted or zero returns immediately. + // Returns on success, failure, or expiry; a deadline returns the latest observed `pending` + // snapshot. Success confirms finalized original upload, not optional attachment processing. + // Set the transport timeout above this wait plus ordinary response latency. + optional uint32 wait_seconds = 2 [(validate.rules).uint32.lte = 30]; } // Returns a snapshot of command state, upload progress, and terminal context, never attachment bytes. @@ -141,7 +148,10 @@ message GetDeviceCommandResponse { // When `attachment` is present, download it with // `GET /v1/device-commands/{command_id}/attachment`, using `device_command.command_id` and the // same authentication as the public API. Download and status reads require `DEVICE_DEBUG`. - // The download does not wait for execution, upload, or processing to finish. + // Downloads are immediate by default. Add `wait_seconds=1` through `wait_seconds=30` to wait + // for upload and the selected representation under one readiness deadline. Omitted or zero + // preserves immediate behavior. Timeout returns the existing not-ready HTTP 409, not partial + // bytes. Set the transport timeout above this wait plus download time. // // Append `?variant=raw` for the finalized original attachment, or assembled log JSON. This skips // optional processing, not the command-success requirement. Omit `variant` for the default @@ -247,7 +257,7 @@ message ListDeviceCommandInvocationsRequest { }]; // Exact match against the submission-time caller snapshot. Supply ID, email, or both (AND). - // At least one must be nonempty; name and avatar_uri are not supported. + // At least one must be nonempty; setting `name` is not supported. .bitdrift.public.unary.common.v1.Owner invoked_by = 2; // Matches a selector only. Arguments are not permitted in a history filter. @@ -451,13 +461,16 @@ service DebugService { // Retrieves the state and available results of a device command. // - // Returns the current snapshot without waiting for execution, upload, or processing. Poll while - // `pending` using a caller-chosen interval and deadline. `failed` and `expired` are terminal. + // Omit `wait_seconds` or use zero for an immediate snapshot. A positive value waits up to 30 + // seconds for success, failure, or expiry; timeout returns the latest observed `pending` snapshot. + // Retry pending reads within a caller-chosen deadline. `failed` and `expired` are terminal. // When `succeeded.attachment` is present, its original upload is complete and finalized; fetch // bytes with `GET /v1/device-commands/{command_id}/attachment?variant=raw`, substituting // `device_command.command_id`. No further upload polling is needed. Optional processing is a - // separate stage: inspect `GET /v1/device-commands/{command_id}/attachment/status` or handle - // HTTP 409 with `Retry-After` on the default download. See `GetDeviceCommandResponse.Succeeded` + // separate stage: inspect `GET /v1/device-commands/{command_id}/attachment/status`, or add + // `wait_seconds=1` through `wait_seconds=30` to the download to wait for its representation. + // A download wait timeout preserves HTTP 409; status-route reads remain immediate. + // See `GetDeviceCommandResponse.Succeeded` // for variants, download headers, and HTTP 4xx meanings. Success without `attachment` means there // is nothing to download. This method never includes attachment bytes or tracks workflow commands. rpc GetDeviceCommand(.bitdrift.public.unary.device_debug.v1.GetDeviceCommandRequest) returns (.bitdrift.public.unary.device_debug.v1.GetDeviceCommandResponse); diff --git a/src/bitdrift/public/unary/entity/v1/api.proto b/src/bitdrift/public/unary/entity/v1/api.proto index d7b6f21b..0a3e841e 100644 --- a/src/bitdrift/public/unary/entity/v1/api.proto +++ b/src/bitdrift/public/unary/entity/v1/api.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.entity.v1; diff --git a/src/bitdrift/public/unary/health/v1/health.proto b/src/bitdrift/public/unary/health/v1/health.proto index a14ffd84..a531ed14 100644 --- a/src/bitdrift/public/unary/health/v1/health.proto +++ b/src/bitdrift/public/unary/health/v1/health.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.health.v1; diff --git a/src/bitdrift/public/unary/issues/v1/api.proto b/src/bitdrift/public/unary/issues/v1/api.proto index d3f339af..13ce5c5d 100644 --- a/src/bitdrift/public/unary/issues/v1/api.proto +++ b/src/bitdrift/public/unary/issues/v1/api.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.issues.v1; diff --git a/src/bitdrift/public/unary/issues/v1/crash.proto b/src/bitdrift/public/unary/issues/v1/crash.proto index c5d75054..09782530 100644 --- a/src/bitdrift/public/unary/issues/v1/crash.proto +++ b/src/bitdrift/public/unary/issues/v1/crash.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.issues.v1; @@ -11,27 +12,38 @@ package bitdrift.public.unary.issues.v1; import "google/protobuf/timestamp.proto"; import "validate/validate.proto"; +// The kind of code a stack frame comes from. enum FrameType { + // The frame type is unknown. UNKNOWN = 0; + // A native frame that is symbolicated with DWARF debug files. DWARF = 1; + // A native frame from an Android app. ANDROID_NDK = 2; + // A frame from a Java or Android virtual machine. JVM = 3; + // A JavaScript frame, such as one from a React Native app. JAVASCRIPT = 4; } +// The source location of a stack frame. message SourceFile { // The path to the source file. string path = 1 [(validate.rules).string = {min_len: 1}]; + // The line number in the source file. int32 lineno = 2; + // The column number in the source file. uint32 column = 3; } +// A single frame of a stack trace. message Frame { - // The result of the symbolication process. + // The kind of code the frame comes from. .bitdrift.public.unary.issues.v1.FrameType frame_type = 1 [(validate.rules).enum = {defined_only: true}]; + // The source location of the frame, when available. .bitdrift.public.unary.issues.v1.SourceFile source_file = 2; // The method or function name of the frame. @@ -49,26 +61,32 @@ message Frame { // The name of the symbol that was resolved during symbolication. optional string symbolicated_name = 7; - // The original index of this frame before symbolication. Some languages may expand - // a single frame into multiple during symbolication, so keeping this field allows - // us to track this. + // The original index of this frame before symbolication. Symbolication can expand a single + // frame into multiple frames, such as inlined functions, which share the same original index. uint64 original_index = 8; // Whether this frame comes from the application or from a library/third party framework. bool in_app = 9; - // The starting address of the image which contains this frame + // The starting address of the image that contains this frame. optional uint64 image_load_address = 10; - // The unique identifier of the image which contains this frame + // The unique identifier of the image that contains this frame. optional string image_id = 11; + // The symbolication status of a frame. enum FrameStatus { + // The symbolication status is unknown or does not apply to this frame type. UNKNOWN = 0; + // The debug file for the frame's image could not be found. MISSING = 1; + // The frame was symbolicated successfully. SYMBOLICATED = 2; + // The debug file was found, but it does not contain a symbol for the frame's address. MISSING_SYMBOL = 3; + // No image is known for the frame's address. UNKNOWN_IMAGE = 4; + // The debug file for the frame's image could not be processed. MALFORMED = 5; } @@ -76,79 +94,118 @@ message Frame { // This can be used to determine if the frame was successfully symbolicated or not. .bitdrift.public.unary.issues.v1.Frame.FrameStatus status = 12 [(validate.rules).enum = {defined_only: true}]; - // contextual info about the frame + // Contextual information about the frame. repeated string state = 13; } +// A crash or error report with its errors, threads, and app and device context. message Report { + // A key-value field attached to the report. message Field { + // The field key. string key = 1 [(validate.rules).string = {min_len: 1}]; + // The field value. string value = 2 [(validate.rules).string = {min_len: 1}]; } + // An error captured in the report. message Error { + // The name of the error, such as an exception class name or signal. string reason = 1 [(validate.rules).string = {min_len: 1}]; + // Additional details about the error, such as the exception message. string details = 2 [(validate.rules).string = {min_len: 1}]; + // The stack trace frames of the error, from the most recently executed frame to the least + // recently executed frame. repeated .bitdrift.public.unary.issues.v1.Frame frames = 3 [(validate.rules).repeated = {min_items: 1}]; } + // Information about the app that generated the report. message AppMetrics { + // The memory pressure level reported by the operating system. enum MemoryPressureLevel { + // The memory pressure level is unknown. MEMORY_PRESSURE_UNKNOWN = 0; + // Memory pressure is normal. MEMORY_PRESSURE_NORMAL = 1; + // Memory pressure is elevated. MEMORY_PRESSURE_WARNING = 2; + // Memory pressure is critical. MEMORY_PRESSURE_CRITICAL = 3; } + // The app identifier, such as the Android application ID or the Apple bundle identifier. string app_id = 1 [(validate.rules).string = {min_len: 1}]; + // The installed app version. string version = 2 [(validate.rules).string = {min_len: 1}]; oneof build_number { + // The Apple bundle version (`CFBundleVersion`). string bundle_version = 3; + // The Android version code. int64 version_code = 4; } + // The memory pressure level at the time of the event, when reported. optional .bitdrift.public.unary.issues.v1.Report.AppMetrics.MemoryPressureLevel memory_pressure_level = 5 [(validate.rules).enum = {defined_only: true}]; } + // Information about the device that generated the report. message DeviceMetrics { + // The CPU architecture of the device. enum Architecture { + // The architecture is unknown. UNKNOWN_ARCH = 0; + // 32-bit ARM. ARM32 = 1; + // 64-bit ARM. ARM64 = 2; + // 32-bit x86. X86 = 3; + // 64-bit x86. X86_64 = 4; } + // The power state of the device. enum PowerState { + // The power state is unknown. UNKNOWN_POWER_STATE = 0; + // The device is running on battery power. RUNNING_ON_BATTERY = 1; + // The device is plugged in and has no battery. PLUGGED_IN_NO_BATTERY = 2; + // The device is plugged in and charging. PLUGGED_IN_CHARGING = 3; + // The device is plugged in and fully charged. PLUGGED_IN_CHARGED = 4; } + // The time at which the event occurred. .google.protobuf.Timestamp time = 1 [(validate.rules).string = {min_len: 1}]; + // The device manufacturer. string manufacturer = 2 [(validate.rules).string = {min_len: 1}]; + // The device model. string model = 3 [(validate.rules).string = {min_len: 1}]; + // The CPU architecture of the device. .bitdrift.public.unary.issues.v1.Report.DeviceMetrics.Architecture architecture = 4 [(validate.rules).enum = {defined_only: true}]; - // OS metrics + // The name of the operating system. string os = 5 [(validate.rules).string = {min_len: 1}]; + // The version of the operating system. string os_version = 6 [(validate.rules).string = {min_len: 1}]; - // Power metrics + // The power state of the device. .bitdrift.public.unary.issues.v1.Report.DeviceMetrics.PowerState power_state = 7 [(validate.rules).enum = {defined_only: true}]; + // The battery level as a percentage from 0 to 100. uint32 battery_level = 8 [(validate.rules).uint32 = { gte: 0 lte: 100 @@ -158,9 +215,11 @@ message Report { string user_id = 9 [(validate.rules).string = {min_len: 1}]; } + // The threads captured in the report. message ThreadDetails { + // A thread captured in the report. message Thread { - // true if this thread is reporting the problem + // Whether this thread reported the problem. bool active = 1; // The name of the thread. @@ -183,37 +242,44 @@ message Report { repeated .bitdrift.public.unary.issues.v1.Frame frames = 7 [(validate.rules).message = {required: true}]; } + // The total number of threads, which can exceed the number of threads captured in `threads`. uint32 total_threads = 1; + // The captured threads, in no guaranteed order. repeated .bitdrift.public.unary.issues.v1.Report.ThreadDetails.Thread threads = 2; } + // A binary image loaded by the app. message BinaryImage { - // globally unique identifier for this image + // The globally unique identifier of the image. string id = 1 [(validate.rules).string = {min_len: 1}]; - // path to the binary on disk or base name if unavailable + // The path to the binary on disk, or its base name when the path is unavailable. string path = 2 [(validate.rules).string = {min_len: 1}]; - // mount point of the image at runtime in bytes + // The address at which the image was loaded at runtime. uint64 load_address = 3; - // size of the image in bytes + // The size of the image in bytes. uint64 length = 4; } + // The errors in the report. The first entry is the reported error; later entries are related + // errors, such as its causes. repeated .bitdrift.public.unary.issues.v1.Report.Error errors = 1; + // Information about the device that generated the report. .bitdrift.public.unary.issues.v1.Report.DeviceMetrics device_metrics = 2; // State of the thread when the event was reported. .bitdrift.public.unary.issues.v1.Report.ThreadDetails thread_details = 3; + // Information about the app that generated the report. .bitdrift.public.unary.issues.v1.Report.AppMetrics app_metrics = 4; // Additional report fields captured from the client report payload. repeated .bitdrift.public.unary.issues.v1.Report.Field fields = 5; - // Binary images present in the thread stack traces of the report + // The binary images referenced by the stack traces in the report. repeated .bitdrift.public.unary.issues.v1.Report.BinaryImage binary_images = 6; } diff --git a/src/bitdrift/public/unary/issues/v1/issues.proto b/src/bitdrift/public/unary/issues/v1/issues.proto index a63ab473..cdf5c794 100644 --- a/src/bitdrift/public/unary/issues/v1/issues.proto +++ b/src/bitdrift/public/unary/issues/v1/issues.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.issues.v1; @@ -39,8 +40,11 @@ import "validate/validate.proto"; // ] // } message AdvancedFilter { + // A single condition that compares a filter key with a value. message Condition { + // The filter keys that a condition can match against. enum LhsTyped { + // No filter key is specified. LHS_TYPED_UNSPECIFIED = 0; // App ID associated with the issue. LHS_TYPED_APP_ID = 1; @@ -91,6 +95,15 @@ message AdvancedFilter { // range older than that matches no reports. // The only supported operators are EQUAL and IN. LHS_TYPED_ENTITY_HASH = 18; + // The linked Android crash-profile category: "anr" or "oom", inferred from the report kind. + // Matches retained completed links, including failed conversions, not current download + // availability. Pending processing counts as absent. EQUAL/IN select categories and + // NOT_EQUAL/NOT_IN exclude them, including reports with no profile. An empty RHS with + // NOT_EQUAL checks presence; EQUAL checks absence. WILDCARD "*" checks presence and + // NOT_WILDCARD "*" or "?*" checks absence; other patterns are not supported. + // In group searches, matches groups containing a matching occurrence. A group can contain + // both profiled and unprofiled occurrences, so it can match both presence and absence. + LHS_TYPED_PROFILE_TYPE = 19; } // The filter key to match against. @@ -98,21 +111,27 @@ message AdvancedFilter { // LHS_TYPED_FUNCTION, LHS_TYPED_FILE, LHS_TYPED_MODULE, and LHS_TYPED_DETAILS support only // SEARCH and NOT_SEARCH. LHS_TYPED_DEVICE_ID and LHS_TYPED_ENTITY_HASH support only EQUAL and - // IN. All other keys support every operator except SEARCH and NOT_SEARCH. + // IN. LHS_TYPED_PROFILE_TYPE supports exact category matching and presence/absence as + // described on that key. All other keys support every operator except SEARCH and NOT_SEARCH. .bitdrift.public.unary.common.v1.Operator operator = 2 [(validate.rules).enum = {defined_only: true}]; + // The value to compare with the filter key. string rhs = 3 [(validate.rules).string = {max_len: 255}]; } + // A group of conditions that matches when any of its conditions matches. message OrCondition { // The conditions that are ORed together. repeated .bitdrift.public.unary.issues.v1.AdvancedFilter.Condition or_conditions = 1 [(validate.rules).repeated = {max_items: 100}]; } + // The condition groups that are ANDed together. repeated .bitdrift.public.unary.issues.v1.AdvancedFilter.OrCondition and_conditions = 1 [(validate.rules).repeated = {max_items: 100}]; } +// Selects issues by a feature flag that was active when they occurred. message FeatureFlagFilter { + // The name of the feature flag to filter by. string name = 1 [(validate.rules).string = { min_len: 1 max_len: 100 @@ -128,6 +147,7 @@ message FeatureFlagFilter { // Limits what issues are being queried for an endpoint. For issue group queries, this limits which issues are considered when listing issue groups. message IssueQuery { + // The time range to query issues for. This is required when querying for issues, but optional when saving a view. .bitdrift.public.unary.common.v1.TimeRange time_range = 7; // The platforms to filter by. @@ -143,6 +163,7 @@ message IssueQuery { repeated .bitdrift.public.unary.issues.v1.FeatureFlagFilter feature_flag_filters = 6 [(validate.rules).repeated = {max_items: 100}]; } +// The triage status of an issue group. enum IssueGroupStatus { // Newly created issue group that has not yet been triaged. NEW = 0; @@ -181,7 +202,9 @@ message Event { uint64 count = 2; } +// A group of related issues that share a grouping key. message IssueGroup { + // Descriptive information that identifies the issue group. message Metadata { // The issue group type, such as Crash, ANR, or Exception. string type = 1; @@ -199,10 +222,11 @@ message IssueGroup { // group and may not represent the entire group. optional string details = 4; - // The platform and app_id associated with the issue group. + // The platform and app ID associated with the issue group. .bitdrift.public.shared.platform.v1.Platform platform = 5 [(validate.rules).message = {required: true}]; } + // Occurrence statistics for the issue group. message Stats { // The first time the issue group was seen within the time range. .google.protobuf.Timestamp first_seen = 1 [(validate.rules).message = {required: true}]; @@ -216,9 +240,10 @@ message IssueGroup { // The number of unique users that have experienced this issue. uint64 user_count = 3; + // Issue occurrence counts for each aggregation interval within the time range. repeated .bitdrift.public.unary.issues.v1.Event events = 4; - // The number of unique sessions in which this issue was reported + // The number of unique sessions in which this issue was reported. uint64 session_count = 5; } @@ -228,9 +253,7 @@ message IssueGroup { // The metadata for the issue group. .bitdrift.public.unary.issues.v1.IssueGroup.Metadata metadata = 2; - // The platform on which the issue group occurred. - // Once we support React Native for issues/crashes, we may encounter issues that span multiple platforms. - // Most of the time we expect this to be a single platform. + // The platforms on which the issue group occurred. This usually contains a single platform. repeated .bitdrift.public.shared.platform.v1.Platform platform = 3; // The stats for the issue group. @@ -242,15 +265,17 @@ message IssueGroup { // The status of the issue group. .bitdrift.public.unary.issues.v1.IssueGroupStatus status = 6; - // The latest version/version code of the application when marked as fixed + // The latest app version or Android version code when the issue group was marked fixed. oneof resolution_version { + // The latest app version when the issue group was marked fixed. string version = 8; - // android-specific version field + // The latest Android version code when the issue group was marked fixed. int64 version_code = 9; } } +// Requests a single issue group. message GetIssueGroupRequest { // The identifier for the issue group. string id = 1 [(validate.rules).string = { @@ -258,23 +283,36 @@ message GetIssueGroupRequest { max_len: 100 }]; + // Selects the issues counted in the issue group's stats. When omitted, the last 7 days of issues + // are used. .bitdrift.public.unary.issues.v1.IssueQuery issue_query = 6; } +// Returns the requested issue group. message GetIssueGroupResponse { // The issue group. .bitdrift.public.unary.issues.v1.IssueGroup issue_group = 1 [(validate.rules).message = {required: true}]; } +// Requests a page of issue groups. message ListIssueGroupsRequest { + // A sort criterion for issue groups. message Sort { + // The issue group attributes that results can be ordered by. enum SortKey { + // No sort key is specified. A sort criterion with this key is rejected. SORT_KEY_UNSPECIFIED = 0; + // Orders results by the most recent occurrence within the queried time range. MOST_RECENT_OCCURRENCE = 1; + // Orders results by the earliest occurrence within the queried time range. EARLIEST_OCCURRENCE = 2; + // Orders results by the first time any report was seen for the issue group. FIRST_REPORTED = 3; + // Orders results by the number of unique users affected. IMPACTED_USERS = 4; + // Orders results by the number of unique sessions affected. IMPACTED_SESSIONS = 5; + // Orders results by issue group reason. ISSUE_REASON = 6; } @@ -300,6 +338,7 @@ message ListIssueGroupsRequest { // with no other criteria. .bitdrift.public.unary.issues.v1.IssueQuery issue_query = 5; + // Limits results to issue groups that match these status and assignee filters. .bitdrift.public.unary.issues.v1.IssueGroupQuery issue_group_query = 6; // Orders issue groups by caller-visible attributes. Apply criteria in the order provided. @@ -315,13 +354,16 @@ message ListIssueGroupsRequest { }]; } +// Returns a page of issue groups. message ListIssueGroupsResponse { // The issue groups. repeated .bitdrift.public.unary.issues.v1.IssueGroup issue_groups = 1; + // The total number of issue groups that match the request across all pages. uint32 total_issue_groups = 2; } +// Requests a single issue. message GetIssueRequest { // The unique identifier for the issue. string id = 1 [(validate.rules).string = { @@ -336,6 +378,7 @@ message GetIssueRequest { }]; } +// A single reported issue, such as a crash or an error, with details about the app and device. message Issue { // The reason for the issue. This should match the reason in the issue group. string reason = 1 [(validate.rules).string = {min_len: 1}]; @@ -352,59 +395,138 @@ message Issue { // Information about the device that the issue occurred on. .bitdrift.public.shared.platform.v1.Platform platform = 5 [(validate.rules).message = {required: true}]; - string app_id = 6 [(validate.rules).message = {required: true}]; + // The app ID of the app that reported the issue. + string app_id = 6; - string app_version = 7 [(validate.rules).message = {required: true}]; + // The app version that reported the issue. + string app_version = 7; - string build_id = 8 [(validate.rules).message = {required: true}]; + // The build identifier of the app: the bundle version on Apple platforms or the version code on + // Android. + string build_id = 8; - string model = 9 [(validate.rules).message = {required: true}]; + // The device model on which the issue occurred. + string model = 9; + // Whether the app was in the foreground when the issue occurred. bool foreground = 15; + // The network type of the device when the issue occurred. string network_type = 16 [(validate.rules).string = {min_len: 1}]; + // The radio type of the device when the issue occurred. string radio_type = 17 [(validate.rules).string = {min_len: 1}]; + // The device locale when the issue occurred. string locale = 18 [(validate.rules).string = {min_len: 1}]; + // The type of report that captured the issue. string report_type = 19 [(validate.rules).string = {min_len: 1}]; + // The processed report for the issue, including its stack traces. .bitdrift.public.unary.issues.v1.Report report = 12 [(validate.rules).message = {required: true}]; // The unique identifier for the issue. string id = 13 [(validate.rules).string = {min_len: 1}]; - // The unique id of the session that this issue occurred within. + // The unique ID of the session that this issue occurred within. optional string session_id = 14 [(validate.rules).string = {min_len: 1}]; // The status of the session associated with this issue. .bitdrift.public.unary.common.v1.SessionStatusInfo session_status_info = 20; } +// Returns the requested issue and its availability. message GetIssueResponse { + // The requested issue, when it is available. .bitdrift.public.unary.issues.v1.Issue issue = 12; + // The availability of the requested issue. enum Status { + // The issue was found and its details are available. FOUND = 0; // No reference to the issue was found. NOT_FOUND = 1; - // The issue is still pending processing (or something went wrong). + // The issue has not finished processing. An issue can stay in this state if processing stalls. PENDING = 2; - // The issue was processed but an error occurred during processing which prevents the stacktrace from being available. - // Note that we don't expose the failure reason as this is not useful to the user. + // The issue was processed, but an error during processing prevents its stack trace from being + // available. The failure reason is not returned. FAILED = 3; } // The status of the issue. If set to FOUND, the issue was found and the details are available. .bitdrift.public.unary.issues.v1.GetIssueResponse.Status status = 13 [(validate.rules).enum = {defined_only: true}]; + + // Completed Android crash profiles for this occurrence. An empty COMPLETE section does not + // distinguish no profile from processing that has not completed. Profile metadata errors never + // remove the issue itself. At most 32 profiles are returned; PARTIAL or UNAVAILABLE must not be + // presented as an empty successful result. This section is revalidated on every request. + .bitdrift.public.unary.issues.v1.IssueProfiles profiles = 14; } +message IssueProfiles { + enum Status { + COMPLETE = 0; + PARTIAL = 1; + UNAVAILABLE = 2; + } + + .bitdrift.public.unary.issues.v1.IssueProfiles.Status status = 1; + + repeated .bitdrift.public.unary.issues.v1.IssueProfile profiles = 2; + + // Additional completed links exceeded the response's 32-profile budget. + bool has_more = 3; +} + +message IssueProfile { + // Profile UUID. Other occurrences linked to a shared profile are never returned. + // With the same organization authorization and `ISSUE_READ` permission, inspect + // `GET /v1/crash-profiles/{id}/status` for raw/processed object availability, or download + // `GET /v1/crash-profiles/{id}?variant=raw` or + // `GET /v1/crash-profiles/{id}?variant=processed`. + // These artifact reads do not depend on the linked occurrence still being present or in + // the same group. Completion status and timestamps are provided by this descriptor. + // The download variant is required. Raw is an original Perfetto trace; processed is a TAR + // containing `trace.perfetto`, `symbols.pb` and `deobfuscation.pb`. Processed never falls back to raw. + string id = 1; + + .google.protobuf.Timestamp captured_at = 2; + + .google.protobuf.Timestamp processed_at = 3; + + enum ProcessingStatus { + SUCCEEDED = 0; + FAILED = 1; + } + + .bitdrift.public.unary.issues.v1.IssueProfile.ProcessingStatus processing_status = 4; + + enum Availability { + UNAVAILABLE = 0; + AVAILABLE = 1; + EXPIRED = 2; + // An expected processed object is missing, corrupt, or could not be checked. Retry rather + // than treating this as ordinary absence. Downloads of a promised object can also fail. + ERROR = 3; + } + + .bitdrift.public.unary.issues.v1.IssueProfile.Availability raw = 5; + + .bitdrift.public.unary.issues.v1.IssueProfile.Availability processed = 6; +} + +// Requests a page of issues in an issue group. message ListIssuesRequest { + // A sort criterion for issues. message Sort { + // The issue attributes that results can be ordered by. enum SortKey { + // No sort key is specified. A sort criterion with this key is rejected. SORT_KEY_UNSPECIFIED = 0; + // Orders results by the time each issue occurred. OCCURRED_AT = 1; + // Orders results by issue reason. ISSUE_REASON = 2; } @@ -415,13 +537,17 @@ message ListIssuesRequest { .bitdrift.public.unary.common.v1.SortDirection direction = 2 [(validate.rules).enum = {defined_only: true}]; } + // A single filter on the issues to list. message ListIssuesFilters { + // Filters issues by platform. message Platform { - // The platform of an issue group to filter by. + // The platforms to filter by. repeated .bitdrift.public.shared.platform.v1.Platform value = 1 [(validate.rules).repeated = {max_items: 100}]; } + // Filters issues by time range. message TimeRange { + // The time range to filter by. .bitdrift.public.unary.common.v1.TimeRange time_range = 3; } @@ -449,9 +575,8 @@ message ListIssuesRequest { // 10th record. The default value is 0. uint32 offset = 2; - // This defines the upper bound of the number of items returned. The maximum - // value supported is 100, meaning that we’ll never return more than - // max(items.count, limit, 100). + // The maximum number of items to return. The server returns at most + // min(items.count, limit, 100) items. Defaults to 100. optional uint32 limit = 3 [(validate.rules).uint32 = { gte: 1 lte: 100 @@ -462,21 +587,27 @@ message ListIssuesRequest { // time range filter is supplied, the server defaults to the last 7 days. repeated .bitdrift.public.unary.issues.v1.ListIssuesRequest.ListIssuesFilters filters = 4 [(validate.rules).repeated = {max_items: 100}]; + // Selects the issues to list. When set, its time range is required and `filters` is ignored. .bitdrift.public.unary.issues.v1.IssueQuery issue_query = 6; // Orders issues by caller-visible attributes. Apply criteria in the order provided. repeated .bitdrift.public.unary.issues.v1.ListIssuesRequest.Sort sort = 7 [(validate.rules).repeated = {max_items: 100}]; } +// Returns a page of issues. message ListIssuesResponse { - // The issue groups. + // The issues. repeated .bitdrift.public.unary.issues.v1.Issue issues = 1; + // The total number of issues that match the request across all pages. uint32 total_issues = 2; } +// Requests a page of issues in an issue group. message ListIssuesV2Request { + // Selects whether results are limited to issues with captured session data. enum SessionCaptureFilter { + // Behaves like `ALL_ISSUES`. SESSION_CAPTURE_FILTER_UNSPECIFIED = 0; // Returns all issues without additional session-capture filtering. ALL_ISSUES = 1; @@ -486,8 +617,11 @@ message ListIssuesV2Request { CAPTURED_SESSIONS_ONLY = 2; } + // A sort criterion for issues. message Sort { + // The issue attributes that results can be ordered by. enum SortKey { + // No sort key is specified. A sort criterion with this key is rejected. SORT_KEY_UNSPECIFIED = 0; // Orders results by the time each issue occurred. OCCURRED_AT = 1; @@ -500,6 +634,7 @@ message ListIssuesV2Request { .bitdrift.public.unary.common.v1.SortDirection direction = 2 [(validate.rules).enum = {defined_only: true}]; } + // Selection criteria for the issues to list. message Query { // Limits results to issues that occurred within the selected time range. .bitdrift.public.unary.common.v1.TimeRange time_range = 1; @@ -535,6 +670,7 @@ message ListIssuesV2Request { .bitdrift.public.unary.issues.v1.ListIssuesV2Request.SessionCaptureFilter session_capture_filter = 5 [(validate.rules).enum = {defined_only: true}]; } +// A summary of a single issue in an issue list. message IssueListItem { // The unique identifier for the issue. string id = 1 [(validate.rules).string = {min_len: 1}]; @@ -573,6 +709,7 @@ message IssueListItem { .bitdrift.public.unary.common.v1.SessionStatusInfo session_status_info = 11; } +// Returns a page of issues. message ListIssuesV2Response { // The issues that match the request. repeated .bitdrift.public.unary.issues.v1.IssueListItem issues = 1; @@ -584,6 +721,7 @@ message ListIssuesV2Response { optional string next_page_token = 3; } +// Requests summary metrics and occurrence events for issues that match a query. message GetAggregateIssueSummaryRequest { // Specifies the issues to summarize. If the query selects multiple issue groups, the result // combines their matching issues and counts each affected user and session once. @@ -603,7 +741,9 @@ message GetAggregateIssueSummaryRequest { .bitdrift.public.unary.issues.v1.IssueGroupQuery issue_group_query = 6; } +// Returns summary metrics and occurrence events for the requested issues. message GetAggregateIssueSummaryResponse { + // Summary metrics and occurrence events for the issues that match the query. message Summary { // The total number of unique users affected by the issues matching the query. // @@ -660,6 +800,7 @@ message GetAggregateIssueEventsResponse { .google.protobuf.Duration aggregation_window = 2; } +// Requests the feature flags that were active when an issue occurred. message GetIssueFeatureFlagsRequest { // The unique identifier for the issue. string issue_id = 1 [(validate.rules).string = { @@ -668,7 +809,9 @@ message GetIssueFeatureFlagsRequest { }]; } +// Returns the feature flags that were active when the issue occurred. message GetIssueFeatureFlagsResponse { + // A feature flag that was active when the issue occurred. message FeatureFlag { // The name of the feature flag. string name = 1 [(validate.rules).string = {min_len: 1}]; @@ -684,6 +827,7 @@ message GetIssueFeatureFlagsResponse { repeated .bitdrift.public.unary.issues.v1.GetIssueFeatureFlagsResponse.FeatureFlag feature_flags = 1; } +// Requests a status change for an issue group. message UpdateIssueGroupStatusRequest { // The unique identifier for the issue group. string id = 1 [(validate.rules).string = { @@ -695,19 +839,22 @@ message UpdateIssueGroupStatusRequest { .bitdrift.public.unary.issues.v1.IssueGroupStatus status = 2 [(validate.rules).enum = {defined_only: true}]; } +// Returns the issue group status after the update. message UpdateIssueGroupStatusResponse { // The resulting status after the update. .bitdrift.public.unary.issues.v1.IssueGroupStatus status = 1 [(validate.rules).enum = {defined_only: true}]; - // The latest version/version code of the application when marked as fixed. + // The latest app version or Android version code when the issue group was marked fixed. oneof resolution_version { + // The latest app version when the issue group was marked fixed. string version = 2; - // Android-specific version field. + // The latest Android version code when the issue group was marked fixed. int64 version_code = 3; } } +// Requests a replacement of the assignees of an issue group. message UpdateIssueGroupAssigneesRequest { // The unique identifier for the issue group. string id = 1 [(validate.rules).string = { @@ -719,11 +866,13 @@ message UpdateIssueGroupAssigneesRequest { repeated .bitdrift.public.unary.common.v1.Owner assignees = 2 [(validate.rules).repeated = {max_items: 100}]; } +// Returns the issue group assignees after the update. message UpdateIssueGroupAssigneesResponse { // The resulting assignees after the update. repeated .bitdrift.public.unary.common.v1.Owner assignees = 1; } +// Requests a page of possible assignees for issue groups. message ListPossibleAssigneesRequest { // Filter assignees by text match. optional string search = 1 [(validate.rules).string = { @@ -751,6 +900,7 @@ message ListPossibleAssigneesRequest { }]; } +// Returns a page of possible assignees for issue groups. message ListPossibleAssigneesResponse { // Possible values for assignees. repeated .bitdrift.public.unary.common.v1.Owner assignees = 1; @@ -759,11 +909,17 @@ message ListPossibleAssigneesResponse { uint32 total = 2; } +// Requests changes to the custom attributes of an issue group. message UpdateIssueGroupAttributesRequest { + // A single change to an issue group attribute. message UpdateAttributeOperation { + // The kind of attribute change. enum OperationType { + // No operation type is specified. This value is rejected. OPERATION_TYPE_UNSPECIFIED = 0; + // Sets the attribute to `value`, adding the attribute if it does not exist. UPSERT = 1; + // Removes the attribute. REMOVE = 2; } @@ -798,8 +954,10 @@ message UpdateIssueGroupAttributesRequest { repeated .bitdrift.public.unary.issues.v1.UpdateIssueGroupAttributesRequest.UpdateAttributeOperation operations = 2 [(validate.rules).repeated = {max_items: 100}]; } +// Confirms that the attribute changes were applied. message UpdateIssueGroupAttributesResponse {} +// Requests the custom attributes of an issue group. message GetIssueGroupAttributesRequest { // The unique identifier for the issue group. string id = 1 [(validate.rules).string = { @@ -808,10 +966,14 @@ message GetIssueGroupAttributesRequest { }]; } +// Returns the custom attributes of an issue group. message GetIssueGroupAttributesResponse { + // A custom attribute of an issue group. message Attribute { + // The attribute key. string key = 1 [(validate.rules).string = {min_len: 1}]; + // The attribute value. string value = 2 [(validate.rules).string = {min_len: 1}]; } diff --git a/src/bitdrift/public/unary/timeline/v1/api.proto b/src/bitdrift/public/unary/timeline/v1/api.proto index 78f3f021..18fcdc6e 100644 --- a/src/bitdrift/public/unary/timeline/v1/api.proto +++ b/src/bitdrift/public/unary/timeline/v1/api.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.timeline.v1; diff --git a/src/bitdrift/public/unary/timeline/v1/feature_flags.proto b/src/bitdrift/public/unary/timeline/v1/feature_flags.proto index 43a69c53..1b4a7054 100644 --- a/src/bitdrift/public/unary/timeline/v1/feature_flags.proto +++ b/src/bitdrift/public/unary/timeline/v1/feature_flags.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.timeline.v1; diff --git a/src/bitdrift/public/unary/timeline/v1/hydration.proto b/src/bitdrift/public/unary/timeline/v1/hydration.proto index 98df06f5..295f69b6 100644 --- a/src/bitdrift/public/unary/timeline/v1/hydration.proto +++ b/src/bitdrift/public/unary/timeline/v1/hydration.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.timeline.v1; diff --git a/src/bitdrift/public/unary/timeline/v1/info.proto b/src/bitdrift/public/unary/timeline/v1/info.proto index 9bcdcacf..de6d384e 100644 --- a/src/bitdrift/public/unary/timeline/v1/info.proto +++ b/src/bitdrift/public/unary/timeline/v1/info.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.timeline.v1; @@ -24,9 +25,8 @@ message GetSessionInfoResponse { // The model of the device. string device_model = 2; - // The user id associated with the session. - // This one is a special case, where we rely on the SDK being configured to return this. - // There may be other special cases like this in the future. + // The user ID associated with the session. Present only when the app reports a user ID + // through the Capture SDK. optional string user_id = 4; // The start time of the session. diff --git a/src/bitdrift/public/unary/timeline/v1/logs.proto b/src/bitdrift/public/unary/timeline/v1/logs.proto index 4bf62eab..8cd6d863 100644 --- a/src/bitdrift/public/unary/timeline/v1/logs.proto +++ b/src/bitdrift/public/unary/timeline/v1/logs.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.timeline.v1; diff --git a/src/bitdrift/public/unary/timeline/v1/search.proto b/src/bitdrift/public/unary/timeline/v1/search.proto index 88546a48..5da5c6d1 100644 --- a/src/bitdrift/public/unary/timeline/v1/search.proto +++ b/src/bitdrift/public/unary/timeline/v1/search.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.timeline.v1; diff --git a/src/bitdrift/public/unary/timeline/v1/spans.proto b/src/bitdrift/public/unary/timeline/v1/spans.proto index ea263958..e7775bc5 100644 --- a/src/bitdrift/public/unary/timeline/v1/spans.proto +++ b/src/bitdrift/public/unary/timeline/v1/spans.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.timeline.v1; @@ -83,8 +84,9 @@ message SessionSearchSpanRequest { // Selects the results page. Defaults to `1` when omitted. optional uint64 page = 4 [(validate.rules).uint64 = {gte: 1}]; - // Limits how many top-level matched spans are returned per page. When omitted, up to `10000` - // top-level spans are returned. Additional matches require pagination. + // Limits how many top-level matched spans are returned per page. Explicit values must be + // between `1` and `500`. When omitted, a page holds up to `10000` top-level spans. Additional + // matches require pagination. // // Child spans included under each returned top-level span do not count toward this page size. optional uint64 per_page = 5 [(validate.rules).uint64 = { diff --git a/src/bitdrift/public/unary/usage/v1/api.proto b/src/bitdrift/public/unary/usage/v1/api.proto index 5b00e0df..092ddfad 100644 --- a/src/bitdrift/public/unary/usage/v1/api.proto +++ b/src/bitdrift/public/unary/usage/v1/api.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.usage.v1; diff --git a/src/bitdrift/public/unary/workflows/v1/api.proto b/src/bitdrift/public/unary/workflows/v1/api.proto index 8d938352..74cf99fb 100644 --- a/src/bitdrift/public/unary/workflows/v1/api.proto +++ b/src/bitdrift/public/unary/workflows/v1/api.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.workflows.v1; @@ -78,7 +79,7 @@ service WorkflowService { // // Chart metadata includes information such as the chart title, description, and // the metric query that the chart is based on. This determines how workflow output - // data is rendered in the UI. + // data is presented as a chart. rpc UpsertWorkflowChartMetadata(.bitdrift.public.unary.charts.v1.UpsertWorkflowChartMetadataRequest) returns (.bitdrift.public.unary.charts.v1.UpsertWorkflowChartMetadataResponse); } diff --git a/src/bitdrift/public/unary/workflows/v1/captured_sessions.proto b/src/bitdrift/public/unary/workflows/v1/captured_sessions.proto index b451a05e..8b9a0571 100644 --- a/src/bitdrift/public/unary/workflows/v1/captured_sessions.proto +++ b/src/bitdrift/public/unary/workflows/v1/captured_sessions.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.workflows.v1; diff --git a/src/bitdrift/public/unary/workflows/v1/workflow.proto b/src/bitdrift/public/unary/workflows/v1/workflow.proto index 7254452d..0cf21759 100644 --- a/src/bitdrift/public/unary/workflows/v1/workflow.proto +++ b/src/bitdrift/public/unary/workflows/v1/workflow.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.workflows.v1; @@ -19,7 +20,9 @@ import "google/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; import "validate/validate.proto"; +// Additional dimensions attached to the metrics emitted for a chart time series. message GroupBy { + // Reads a group-by dimension value from app state. message StateValue { // The scope of the state value to read when producing the group-by dimension. .bitdrift.public.unary.workflows.v1.StateScope scope = 1 [(validate.rules).enum = { @@ -105,7 +108,9 @@ message GroupBy { repeated .bitdrift.public.unary.workflows.v1.GroupBy.Value values = 6 [(validate.rules).repeated = {max_items: 100}]; } +// A workflow definition: its flows, actions, targeting, and deployment state. message Workflow { + // A tag assigned to a workflow. message WorkflowTag { // The raw value of the tag. This is what gets stored and used for filtering. string value = 1 [(validate.rules).string = { @@ -117,6 +122,7 @@ message Workflow { .bitdrift.public.unary.common.v1.Owner created_by = 2; } + // The deployment state of a workflow. enum WorkflowState { // The workflow is not currently running and it has not been deployed. IDLE = 0; @@ -190,8 +196,11 @@ message Workflow { // An individual flow within a workflow. message Flow { + // Runs the flow one run at a time. An event that advances the active run continues that run; + // otherwise, a match on the initial step restarts the flow. message ExclusiveFlow {} + // Allows multiple runs of the flow to be active at the same time. message ParallelFlow { // The maximum number of active "runs" for this flow. Defaults to 10 if not specified. optional uint32 max_active_runs = 1; @@ -204,8 +213,8 @@ message Flow { }]; oneof flow_execution_type { - // Any match on the initial step causes the flow to reset. This is the default if not - // specified. + // Runs one flow run at a time. A match on the initial step restarts the flow only when the + // event does not advance the active run. This is the default if not specified. .bitdrift.public.unary.workflows.v1.Flow.ExclusiveFlow exclusive = 2; // Multiple "runs" of the flow can occur in parallel. Runs are replaced FIFO if the active @@ -222,6 +231,7 @@ message Step { // step. When an exit condition is met, the current run is discarded and the flow waits to match // the first step again. message ExitCondition { + // An exit condition that ends the current run when a timeout elapses. message TimeoutExit { // The ID of this timeout exit. Must be unique within the workflow. This ID can be referenced // by actions that accept timeout IDs. @@ -378,6 +388,7 @@ message MatchRule { // Selects a bookmarked entity using the app's current entity ID. message KnownEntityMatch {} +// Matches issues processed by an issue script. message IssueMatch { oneof script_type { // A valid ripsaw program. The program will be run against the incoming issue and can produce @@ -389,6 +400,7 @@ message IssueMatch { } } +// Matches changes to an app state value, such as a feature flag exposure. message StateChangeMatch { // Match conditions for the previous state. Leave empty to only match on the new value. .bitdrift.public.unary.workflows.v1.StateCondition from = 1; @@ -402,11 +414,12 @@ message StateChangeMatch { // The key of the state value within the given scope. string key = 4 [(validate.rules).string = {max_len: 100}]; - // Additional match conditions for this OOTB event. This is an AND in addition to the - // previously defined event. + // Additional match conditions for this state change. These are combined with the state + // conditions using AND. .bitdrift.public.unary.workflows.v1.GenericMatch generic_match = 5; } +// Matches an out-of-the-box (OOTB) event emitted by the SDK. message OotbMatch { option (shared.annotations.ootb_default_field_metadata) = { fields: { @@ -643,6 +656,7 @@ message OotbMatch { // the same field definitions for values that appear here; only platform-exclusive values add // new fields. message GenericOotbConditionType { + // Cross-platform OOTB event types. enum GenericOotbConditionType { // Invalid placeholder value. Do not use. UNKNOWN = 0; @@ -2681,6 +2695,7 @@ message OotbMatch { example_value: "America/New_York" } }]; + // A WebView document lifecycle event occurs. WEBVIEW_LIFECYCLE = 32 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Lifecycle" @@ -2714,6 +2729,7 @@ message OotbMatch { suitable_for: OOTB_FIELD_AGGREGATION_GROUP } }]; + // A WebView document navigates. WEBVIEW_NAVIGATION = 33 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Navigation" @@ -2815,6 +2831,7 @@ message OotbMatch { suitable_for: OOTB_FIELD_AGGREGATION_GROUP } }]; + // A long task blocks the WebView main thread. WEBVIEW_LONG_TASK = 34 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Long Task" @@ -2903,6 +2920,7 @@ message OotbMatch { supported_operators: OOTB_FIELD_OPERATOR_NOT_SET } }]; + // A JavaScript error occurs in a WebView. WEBVIEW_ERROR = 35 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView JavaScript Error" @@ -2935,6 +2953,7 @@ message OotbMatch { supported_operators: OOTB_FIELD_OPERATOR_NOT_SET } }]; + // An unhandled Promise rejection occurs in a WebView. WEBVIEW_PROMISE_REJECTION = 36 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Promise Rejection" @@ -2953,6 +2972,7 @@ message OotbMatch { supported_operators: OOTB_FIELD_OPERATOR_NOT_SET } }]; + // A WebView resource fails to load. WEBVIEW_RESOURCE_ERROR = 37 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Resource Error" @@ -2973,6 +2993,7 @@ message OotbMatch { well_known_fields: {common_field: OOTB_COMMON_FIELD_HOST} well_known_fields: {common_field: OOTB_COMMON_FIELD_NETWORK_PATH_TEMPLATE} }]; + // A console log is emitted by a WebView. WEBVIEW_CONSOLE = 38 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Console Log" @@ -3018,6 +3039,7 @@ message OotbMatch { supported_operators: OOTB_FIELD_OPERATOR_NOT_SET } }]; + // A user interacts with a WebView element. WEBVIEW_USER_INTERACTION = 39 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView User Interaction" @@ -3102,6 +3124,7 @@ message OotbMatch { supported_operators: OOTB_FIELD_OPERATOR_NOT_SET } }]; + // A WebView Largest Contentful Paint measurement is reported. WEBVIEW_VITAL_LCP = 40 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Core Web Vital - LCP" @@ -3155,6 +3178,7 @@ message OotbMatch { well_known_fields: {common_field: OOTB_COMMON_FIELD_HOST} well_known_fields: {common_field: OOTB_COMMON_FIELD_NETWORK_PATH_TEMPLATE} }]; + // A WebView First Contentful Paint measurement is reported. WEBVIEW_VITAL_FCP = 41 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Core Web Vital - FCP" @@ -3208,6 +3232,7 @@ message OotbMatch { well_known_fields: {common_field: OOTB_COMMON_FIELD_HOST} well_known_fields: {common_field: OOTB_COMMON_FIELD_NETWORK_PATH_TEMPLATE} }]; + // A WebView Time to First Byte measurement is reported. WEBVIEW_VITAL_TTFB = 42 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Core Web Vital - TTFB" @@ -3261,6 +3286,7 @@ message OotbMatch { well_known_fields: {common_field: OOTB_COMMON_FIELD_HOST} well_known_fields: {common_field: OOTB_COMMON_FIELD_NETWORK_PATH_TEMPLATE} }]; + // A WebView Interaction to Next Paint measurement is reported. WEBVIEW_VITAL_INP = 43 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Core Web Vital - INP" @@ -3314,6 +3340,7 @@ message OotbMatch { well_known_fields: {common_field: OOTB_COMMON_FIELD_HOST} well_known_fields: {common_field: OOTB_COMMON_FIELD_NETWORK_PATH_TEMPLATE} }]; + // A WebView Cumulative Layout Shift measurement is reported. WEBVIEW_VITAL_CLS = 44 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Core Web Vital - CLS" @@ -3366,6 +3393,7 @@ message OotbMatch { well_known_fields: {common_field: OOTB_COMMON_FIELD_HOST} well_known_fields: {common_field: OOTB_COMMON_FIELD_NETWORK_PATH_TEMPLATE} }]; + // A WebView page view starts or ends. WEBVIEW_PAGE_VIEW = 45 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_WEBVIEW title: "WebView Page View" @@ -3392,7 +3420,9 @@ message OotbMatch { // Android-specific OOTB condition types. Includes all generic conditions plus Android-exclusive // events. Shared values carry the same well-known fields documented on GenericOotbConditionType. message AndroidOotbConditionType { + // Android OOTB event types. enum AndroidOotbConditionType { + // Invalid placeholder value. Do not use. UNKNOWN = 0; // The SDK's built-in fatal issue handler captures an Android app hang. APP_ANDROID_BUILT_IN_ANR = 1 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { @@ -3510,12 +3540,16 @@ message OotbMatch { } } }]; + // App moves out of the foreground and begins backgrounding. APP_BACKGROUND = 3 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_GENERAL title: "App Moved To Background" }]; + // The SDK's built-in JS error handler captures a fatal JavaScript error. APP_BUILT_IN_JS_FATAL_ERROR = 4; + // The SDK's built-in JS error handler captures a non-fatal JavaScript error. APP_BUILT_IN_JS_NON_FATAL_ERROR = 5; + // App leaves the screen and its foreground UI closes. APP_CLOSE = 6; // Android app crash. Carries crash details when available. Depending on the source, fields // may describe a JVM exception or an OS-reported fatal exit. @@ -3738,21 +3772,28 @@ message OotbMatch { // Deprecated Android-only alias of APP_TERMINATION. Retained for legacy compatibility; // prefer APP_TERMINATION for new workflows. APP_EXIT = 8; + // App moves into the foreground and becomes active. APP_FOREGROUND = 9 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_GENERAL title: "App Moved To Foreground" }]; + // App launch completes for a new process. APP_LAUNCH = 10 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_GENERAL title: "App Launch" }]; + // App reached time-to-interactive after launch. APP_LAUNCH_TTI = 11; + // App opens into the foreground, either on a cold start or when reopened from the background. APP_OPEN = 12; + // An app termination is recorded, including OS-reported exit information. APP_TERMINATION = 13 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { category: OOTB_EVENT_CATEGORY_GENERAL title: "App Exit" }]; + // App updates to a new version. APP_UPDATE = 14; + // Device battery state changes. BATTERY_STATE_CHANGE = 15; // A rendering issue is detected for a UI frame. `_frame_issue_type` distinguishes slow, // frozen, and ANR-classified frames. @@ -3798,36 +3839,64 @@ message OotbMatch { unit: "ms" } }]; + // A GraphQL request starts. Requires supported network instrumentation. GQL_REQUEST = 17; + // A GraphQL response completes. Requires supported network instrumentation. GQL_RESPONSE = 18; + // Device low-power mode toggles. LOW_POWER_MODE = 19; + // App memory usage meets the configured low-memory threshold. MEMORY_PRESSURE = 20; + // An HTTP network request starts. Requires supported network instrumentation. NETWORK_REQUEST = 21; + // An HTTP network response completes. Requires supported network instrumentation. NETWORK_RESPONSE = 22; + // Device orientation changes. ORIENTATION_CHANGE = 23; + // A periodic snapshot of device and process resource metrics. RESOURCE = 24; + // A screen or view is displayed. SCREEN_VIEW = 25; + // SDK configuration is applied during SDK startup. SDK_CONFIGURATION = 26; // A Session Replay frame is captured. Only emitted when Session Replay is enabled for // the app. SESSION_REPLAY = 27; + // A custom span ends. SPAN_END = 28; + // A custom span starts. SPAN_START = 29; + // Device thermal state changes. THERMAL_STATE_CHANGE = 30; + // Device timezone changes. TIMEZONE_CHANGE = 31; + // A WebView document lifecycle event occurs. WEBVIEW_LIFECYCLE = 32; + // A WebView document navigates. WEBVIEW_NAVIGATION = 33; + // A long task blocks the WebView main thread. WEBVIEW_LONG_TASK = 34; + // A JavaScript error occurs in a WebView. WEBVIEW_ERROR = 35; + // An unhandled Promise rejection occurs in a WebView. WEBVIEW_PROMISE_REJECTION = 36; + // A WebView resource fails to load. WEBVIEW_RESOURCE_ERROR = 37; + // A console log is emitted by a WebView. WEBVIEW_CONSOLE = 38; + // A user interacts with a WebView element. WEBVIEW_USER_INTERACTION = 39; + // A WebView Largest Contentful Paint measurement is reported. WEBVIEW_VITAL_LCP = 40; + // A WebView First Contentful Paint measurement is reported. WEBVIEW_VITAL_FCP = 41; + // A WebView Time to First Byte measurement is reported. WEBVIEW_VITAL_TTFB = 42; + // A WebView Interaction to Next Paint measurement is reported. WEBVIEW_VITAL_INP = 43; + // A WebView Cumulative Layout Shift measurement is reported. WEBVIEW_VITAL_CLS = 44; + // A WebView page view starts or ends. WEBVIEW_PAGE_VIEW = 45; } } @@ -3835,7 +3904,9 @@ message OotbMatch { // Apple-specific OOTB condition types. Includes all generic conditions plus Apple-exclusive // events. Shared values carry the same well-known fields documented on GenericOotbConditionType. message AppleOotbConditionType { + // Apple OOTB event types. enum AppleOotbConditionType { + // Invalid placeholder value. Do not use. UNKNOWN = 0; // iOS app hang detected when the app stops responding for longer than the configured threshold. ANR = 1 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { @@ -3863,10 +3934,15 @@ message OotbMatch { example_value: "span-123" } }]; + // App moves out of the foreground and begins backgrounding. APP_BACKGROUND = 2; + // The SDK's built-in JS error handler captures a fatal JavaScript error. APP_BUILT_IN_JS_FATAL_ERROR = 3; + // The SDK's built-in JS error handler captures a non-fatal JavaScript error. APP_BUILT_IN_JS_NON_FATAL_ERROR = 4; + // App leaves the screen and its foreground UI closes. APP_CLOSE = 5; + // App moves into the foreground and becomes active. APP_FOREGROUND = 6; // The SDK's built-in fatal issue handler captures an iOS app hang. APP_IOS_BUILT_IN_ANR = 7 [(.bitdrift.public.shared.annotations.ootb_event_metadata) = { @@ -3886,42 +3962,76 @@ message OotbMatch { well_known_fields: {common_field: OOTB_COMMON_FIELD_APPLE_DEVICE_MODEL} well_known_fields: {common_field: OOTB_COMMON_FIELD_APP_EXIT_INFO_APPLE} }]; + // App launch completes for a new process. APP_LAUNCH = 9; + // App reached time-to-interactive after launch. APP_LAUNCH_TTI = 10; + // App opens into the foreground, either on a cold start or when reopened from the background. APP_OPEN = 11; + // The app receives the termination notification. APP_TERMINATION = 12; + // App updates to a new version. APP_UPDATE = 13; + // Device battery state changes. BATTERY_STATE_CHANGE = 14; + // A GraphQL request starts. Requires supported network instrumentation. GQL_REQUEST = 15; + // A GraphQL response completes. Requires supported network instrumentation. GQL_RESPONSE = 16; + // Device low-power mode toggles. LOW_POWER_MODE = 17; + // The system reports memory pressure to the app. MEMORY_PRESSURE = 18; + // An HTTP network request starts. Requires supported network instrumentation. NETWORK_REQUEST = 19; + // An HTTP network response completes. Requires supported network instrumentation. NETWORK_RESPONSE = 20; + // Device orientation changes. ORIENTATION_CHANGE = 21; + // A periodic snapshot of device and process resource metrics. RESOURCE = 22; + // A screen or view is displayed. SCREEN_VIEW = 23; + // SDK configuration is applied during SDK startup. SDK_CONFIGURATION = 24; // A Session Replay frame is captured. Only emitted when Session Replay is enabled for // the app. SESSION_REPLAY = 25; + // A custom span ends. SPAN_END = 26; + // A custom span starts. SPAN_START = 27; + // Device thermal state changes. THERMAL_STATE_CHANGE = 28; + // Device timezone changes. TIMEZONE_CHANGE = 29; + // A WebView document lifecycle event occurs. WEBVIEW_LIFECYCLE = 30; + // A WebView document navigates. WEBVIEW_NAVIGATION = 31; + // A long task blocks the WebView main thread. WEBVIEW_LONG_TASK = 32; + // A JavaScript error occurs in a WebView. WEBVIEW_ERROR = 33; + // An unhandled Promise rejection occurs in a WebView. WEBVIEW_PROMISE_REJECTION = 34; + // A WebView resource fails to load. WEBVIEW_RESOURCE_ERROR = 35; + // A console log is emitted by a WebView. WEBVIEW_CONSOLE = 36; + // A user interacts with a WebView element. WEBVIEW_USER_INTERACTION = 37; + // A WebView Largest Contentful Paint measurement is reported. WEBVIEW_VITAL_LCP = 38; + // A WebView First Contentful Paint measurement is reported. WEBVIEW_VITAL_FCP = 39; + // A WebView Time to First Byte measurement is reported. WEBVIEW_VITAL_TTFB = 40; + // A WebView Interaction to Next Paint measurement is reported. WEBVIEW_VITAL_INP = 41; + // A WebView Cumulative Layout Shift measurement is reported. WEBVIEW_VITAL_CLS = 42; + // A WebView page view starts or ends. WEBVIEW_PAGE_VIEW = 43; } } @@ -3943,8 +4053,11 @@ message OotbMatch { .bitdrift.public.unary.workflows.v1.GenericMatch generic_match = 4; } +// A predicate tree over log fields, the log body, and app state. message GenericMatch { + // A single comparison between a value from the event and a literal or saved value. message GenericMatchCondition { + // Identifies an app state value by scope and key. message StateKey { // The scope of the state key to look up. .bitdrift.public.unary.workflows.v1.StateScope scope = 1 [(validate.rules).enum = {defined_only: true}]; @@ -4054,7 +4167,9 @@ message RuleStartTracing { }]; } +// Configuration messages for workflow actions and timeout exits. message Rule { + // A session capture action that flushes buffered logs for the current session. message RuleFlushConfiguration { // The server-generated ID for this rule action. This can be used to query // for sessions that arrive at this rule action. @@ -4095,6 +4210,7 @@ message Rule { } } + // A single time series within a metric chart. message TimeSeries { // 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 @@ -4180,10 +4296,12 @@ message Rule { .bitdrift.public.unary.workflows.v1.GroupBy group_by = 5; } + // Selects what to count uniquely within each aggregation interval. message TrackUnique { oneof track_unique_type { option (validate.required) = true; - // This is computed entirely server-side and thus does not require any client emission. + // Counts unique devices that contribute to each aggregation interval. Requires no + // additional data from the app. bool device_id = 1 [(validate.rules).bool.const = true]; } } @@ -4250,13 +4368,11 @@ message Rule { } } - // 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. + // The nodes of the diagram. Workflows can have loops, so a match rule and its corresponding + // node can be visited multiple times; each visit extracts a new value. // - // 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. + // The server stores this list as supplied. Each workflow update replaces it with the nodes in + // the request, so include every node to keep. // // All target nodes must be within the same flow. The loop section is the portion of the flow // covered by a loop back-edge; nodes in that section are treated as extracted dynamic values, @@ -4281,7 +4397,9 @@ message Rule { repeated string match_ids = 4 [(validate.rules).repeated = {max_items: 100}]; } + // A measure time action that records the elapsed time between two matches in a flow. message RuleMeasureTime { + // A duration threshold that a completed time measurement must satisfy. message MeasureTimeCondition { // The operator to use when evaluating the duration threshold. .bitdrift.public.unary.workflows.v1.Operator operator = 2 [(validate.rules).enum.defined_only = true]; @@ -4323,10 +4441,15 @@ message Rule { // exits are terminal and do not advance to another step. A single step can define at most one // timeout exit. message RuleTimeout { + // The unit of a timeout duration. enum DurationUnit { + // Milliseconds. MILLISECONDS = 0; + // Seconds. SECONDS = 1; + // Minutes. MINUTES = 2; + // Hours. HOURS = 3; } @@ -4338,25 +4461,41 @@ message Rule { } } +// The scope of an app state value. enum StateScope { + // Invalid placeholder value. Do not use. UNKNOWN = 0; + // Feature flag exposures, keyed by feature flag name. FEATURE_FLAG_EXPOSURE = 1; } +// How values are interpreted before comparison. enum MatchType { + // Compares values as strings. STRING = 0; + // Compares values as integers. INT = 1; + // Compares values as semantic versions. SEMVER = 2; + // Compares values as floating-point numbers. DOUBLE = 3; } +// A comparison operator. enum Operator { + // Matches when the value equals the comparison value. EQUAL = 0; + // Matches when the value does not equal the comparison value. NOT_EQUAL = 1; + // Matches when the value is greater than the comparison value. GREATER_THAN = 2; + // Matches when the value is greater than or equal to the comparison value. GREATER_THAN_OR_EQUAL = 3; + // Matches when the value is less than the comparison value. LESS_THAN = 4; + // Matches when the value is less than or equal to the comparison value. LESS_THAN_OR_EQUAL = 5; + // Matches when the value matches the regular expression. REGEX = 6; // The operator expects a list of the elements on the right side. // The API supports a single string as the value on the right side of the @@ -4385,6 +4524,7 @@ enum Operator { NOT_SET = 13; } +// A condition on an app state value. message StateCondition { // The type used to interpret both the observed state value and the provided `value` before // comparison. @@ -4405,15 +4545,16 @@ message StateCondition { string value = 3 [(validate.rules).string = {max_len: 255}]; } +// A validation problem found in a workflow. message Violation { // User friendly message that explains the violation. string message = 1; // The match or rule ID that this violation is associated with. - // Only used in v3. string match_or_rule_id = 3; } +// Request for workflow deployment history. message GetWorkflowDeploymentHistoryRequest { // Used to paginate through results. To get the next page result, set this to // the desired starting offset. For example, setting to 10 will start with the @@ -4440,6 +4581,7 @@ message GetWorkflowDeploymentHistoryRequest { }]; } +// Response containing workflow deployment history. message GetWorkflowDeploymentHistoryResponse { // The workflow deployment history entries that match the request. repeated .bitdrift.public.unary.workflows.v1.HistoricalWorkflowDeployment deployments = 1; @@ -4448,6 +4590,7 @@ message GetWorkflowDeploymentHistoryResponse { uint32 total_deployments = 2; } +// A single deployed version of a workflow. message HistoricalWorkflowDeployment { // The deployment version. uint64 version = 1; @@ -4466,6 +4609,7 @@ message HistoricalWorkflowDeployment { .bitdrift.public.unary.common.v1.Owner deployed_by_user_id = 6; } +// Request to retrieve a workflow. message GetWorkflowRequest { // The ID of the workflow to retrieve. string workflow_id = 2 [(validate.rules).string = { @@ -4474,6 +4618,7 @@ message GetWorkflowRequest { }]; } +// Response containing the requested workflow. message GetWorkflowResponse { // The workflow that was retrieved in full. .bitdrift.public.unary.workflows.v1.Workflow workflow = 1; @@ -4485,13 +4630,18 @@ message GetWorkflowResponse { repeated .bitdrift.public.unary.workflows.v1.PerRuleChartMetadata per_rule_chart_metadata = 4; } +// A filter based on the current user's relationship to an entity. message Filter { + // Matches entities owned by the current user. message Owned {} + // Matches entities not owned by the current user. message Unowned {} + // Matches entities favorited by the current user. message Favorites {} + // Matches active entities. message Active {} oneof type { @@ -4559,31 +4709,42 @@ message WorkflowListQuery { START_TRACING = 6; } + // Whether a tag condition requires or excludes the listed tags. enum TagOperator { + // Invalid placeholder value. Do not use. UNSPECIFIED_OPERATOR = 0; + // Matches workflows whose tags satisfy `match`. INCLUDES = 1; + // Matches workflows whose tags do not satisfy `match`. EXCLUDES = 2; } + // How the listed tags are compared to a workflow's tags. enum TagMatch { + // Invalid placeholder value. Do not use. UNSPECIFIED_MATCH = 0; + // The workflow has at least one of the listed tags. ANY_OF = 1; + // The workflow has every listed tag. ALL_OF = 2; } // A single predicate over workflow tags. // Example: "tags INCLUDES ANY_OF [foo, bar]" or "tags EXCLUDES ALL_OF [baz, qux]". message TagCondition { + // Whether to include or exclude workflows with matching tags. .bitdrift.public.unary.workflows.v1.WorkflowListQuery.TagOperator operator = 1 [(validate.rules).enum = { defined_only: true not_in: [0] }]; + // Whether a workflow must have any or all of `tags`. .bitdrift.public.unary.workflows.v1.WorkflowListQuery.TagMatch match = 2 [(validate.rules).enum = { defined_only: true not_in: [0] }]; + // The tags to compare against each workflow's tags. repeated string tags = 3 [(validate.rules).repeated = { min_items: 1 max_items: 20 @@ -4598,6 +4759,7 @@ message WorkflowListQuery { // All tag conditions must be true (logical AND). message TagAllOf { + // The tag conditions that must all be true. repeated .bitdrift.public.unary.workflows.v1.WorkflowListQuery.TagCondition conditions = 1 [(validate.rules).repeated = { min_items: 1 max_items: 20 @@ -4607,6 +4769,7 @@ message WorkflowListQuery { // A filter that matches when at least one TagAllOf group is satisfied (logical OR of ANDs). // Example: (INCLUDES ALL_OF [foo, bar] AND EXCLUDES ANY_OF [baz]) OR (INCLUDES ANY_OF [qux]) message TagFilter { + // The condition groups, at least one of which must be satisfied. repeated .bitdrift.public.unary.workflows.v1.WorkflowListQuery.TagAllOf any_of = 1 [(validate.rules).repeated = { min_items: 1 max_items: 20 @@ -4664,15 +4827,25 @@ message WorkflowListQuery { }]; } +// Request to list workflows. message ListWorkflowsRequest { + // A sort criterion for listed workflows. message Sort { + // The workflow attribute to sort by. enum SortKey { + // Invalid placeholder value. Do not use. SORT_KEY_UNSPECIFIED = 0; + // Sorts by workflow name. DISPLAY_NAME = 1; + // Sorts by creation time. CREATION_TIME = 2; + // Sorts by whether the workflow is deployed. STATUS = 3; + // Sorts by workflow owner. OWNER_NAME = 4; + // Sorts by whether the current user has favorited the workflow. FAVORITED = 5; + // Sorts by when the current user last viewed the workflow. LAST_VIEWED = 6; } @@ -4688,9 +4861,7 @@ message ListWorkflowsRequest { // 10th record. The default value is 0. optional uint32 offset = 1; - // This defines the upper bound of the number of items returned. The maximum - // value supported is 100, meaning that we’ll never return more than - // max(items.count, limit, 100). + // The maximum number of workflows to return, from 1 to 100. optional uint32 limit = 2 [(validate.rules).uint32 = { gte: 1 lte: 100 @@ -4724,11 +4895,14 @@ message ListWorkflowsRequest { }]; } +// Response containing a page of workflows. message ListWorkflowsResponse { + // A workflow and its metadata. message Item { // The workflow returned for this list item. .bitdrift.public.unary.workflows.v1.Workflow workflow = 1; + // The metadata for this workflow. .bitdrift.public.unary.workflows.v1.WorkflowMetadata metadata = 5; } @@ -4745,6 +4919,7 @@ message ListWorkflowsResponse { uint32 total_filtered_workflows = 4; } +// Request to create a workflow. message CreateWorkflowRequest { // The workflow configuration to create. .bitdrift.public.unary.workflows.v1.Workflow workflow = 2 [(validate.rules).message.required = true]; @@ -4757,12 +4932,13 @@ message CreateWorkflowRequest { repeated .bitdrift.public.unary.workflows.v1.PerRuleChartMetadata per_rule_chart_metadata = 5 [(validate.rules).repeated = {max_items: 100}]; } +// Response for a created workflow. message CreateWorkflowResponse { // Unique identifier for the created workflow. - // string id = 1; } +// Request to replace a workflow definition. message UpdateWorkflowRequest { // The ID of the workflow to update. string workflow_id = 2 [(validate.rules).string = { @@ -4783,7 +4959,9 @@ message UpdateWorkflowRequest { repeated .bitdrift.public.unary.workflows.v1.PerRuleChartMetadata per_rule_chart_metadata = 6 [(validate.rules).repeated = {max_items: 100}]; } +// Response for a workflow update. message UpdateWorkflowResponse { + // A violation that prevents the update from being applied. message BlockingViolation { // A chart has been removed or modified in a way that would cause the alert to no longer be // valid (the target aggregated ID has changed). The user must be notified to remove the @@ -4819,6 +4997,7 @@ message UpdateWorkflowResponse { repeated .bitdrift.public.unary.workflows.v1.UpdateWorkflowResponse.BlockingViolation violations = 3; } +// Request to rename a workflow. message RenameWorkflowRequest { // The ID of the workflow to rename. string workflow_id = 2 [(validate.rules).string = {max_len: 100}]; @@ -4827,6 +5006,7 @@ message RenameWorkflowRequest { string name = 3 [(validate.rules).string = {max_len: 255}]; } +// Response for a renamed workflow. message RenameWorkflowResponse { // The renamed workflow with all server-generated fields. .bitdrift.public.unary.workflows.v1.Workflow workflow = 1; @@ -4838,6 +5018,7 @@ message RenameWorkflowResponse { repeated .bitdrift.public.unary.workflows.v1.PerRuleChartMetadata per_rule_chart_metadata = 4; } +// Request to set the tags assigned to a workflow. message UpsertWorkflowTagsRequest { // The ID of the workflow to update. string workflow_id = 1 [(validate.rules).string = {max_len: 100}]; @@ -4854,18 +5035,22 @@ message UpsertWorkflowTagsRequest { }]; } +// Response containing the workflow's tags after the update. message UpsertWorkflowTagsResponse { // The tags that are assigned to the workflow after the update completes. repeated .bitdrift.public.unary.workflows.v1.Workflow.WorkflowTag tags = 1; } +// Request to list workflow tags. message ListTagsRequest {} +// Response containing workflow tags. message ListTagsResponse { // The available workflow tags. repeated .bitdrift.public.unary.workflows.v1.Workflow.WorkflowTag tags = 1; } +// Request to delete a workflow. message DeleteWorkflowRequest { // The ID of the workflow to delete. string workflow_id = 2 [(validate.rules).string = { @@ -4874,7 +5059,9 @@ message DeleteWorkflowRequest { }]; } +// Response for a workflow deletion. message DeleteWorkflowResponse { + // A problem that prevents the workflow from being deleted. message Violation { // User friendly message that explains the violation. string message = 1; @@ -4884,6 +5071,7 @@ message DeleteWorkflowResponse { repeated .bitdrift.public.unary.workflows.v1.DeleteWorkflowResponse.Violation violations = 1; } +// Request to deploy a workflow. message DeployWorkflowRequest { // The ID of the workflow to deploy. string workflow_id = 2 [(validate.rules).string = { @@ -4892,6 +5080,7 @@ message DeployWorkflowRequest { }]; } +// Response for a workflow deployment. message DeployWorkflowResponse { // If non-empty, the deploy failed due to the configuration not being // convertible to a valid client workflow. @@ -4907,6 +5096,7 @@ message DeployWorkflowResponse { repeated .bitdrift.public.unary.workflows.v1.PerRuleChartMetadata per_rule_chart_metadata = 4; } +// Request to stop a deployed workflow. message StopWorkflowRequest { // The ID of the workflow to update. string workflow_id = 2 [(validate.rules).string = { @@ -4915,6 +5105,7 @@ message StopWorkflowRequest { }]; } +// Response for a stopped workflow. message StopWorkflowResponse { // The mutated idle workflow. .bitdrift.public.unary.workflows.v1.Workflow workflow = 1; @@ -4926,6 +5117,7 @@ message StopWorkflowResponse { repeated .bitdrift.public.unary.workflows.v1.PerRuleChartMetadata per_rule_chart_metadata = 3; } +// Request to favorite or unfavorite a workflow for the current user. message FavoriteWorkflowRequest { // The ID of the workflow to favorite. string workflow_id = 2 [(validate.rules).string = {max_len: 100}]; @@ -4934,4 +5126,5 @@ message FavoriteWorkflowRequest { bool favorite = 3; } +// Response for a favorite change. message FavoriteWorkflowResponse {} diff --git a/src/bitdrift/public/unary/workflows/v1/workflow_metadata.proto b/src/bitdrift/public/unary/workflows/v1/workflow_metadata.proto index bd8f301e..a456bbfc 100644 --- a/src/bitdrift/public/unary/workflows/v1/workflow_metadata.proto +++ b/src/bitdrift/public/unary/workflows/v1/workflow_metadata.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.unary.workflows.v1; diff --git a/src/bitdrift/public/webhook/v1/notification.proto b/src/bitdrift/public/webhook/v1/notification.proto index c41bd010..8ead9a61 100644 --- a/src/bitdrift/public/webhook/v1/notification.proto +++ b/src/bitdrift/public/webhook/v1/notification.proto @@ -4,6 +4,7 @@ // Use of this source code and APIs are governed by a source available license that can be found in // the LICENSE file or at: // https://polyformproject.org/wp-content/uploads/2020/06/PolyForm-Shield-1.0.0.txt + syntax = "proto3"; package bitdrift.public.webhook.v1;