Skip to content

Commit c1e5970

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: Make resolution status field available for error groups. Now callers can set the status of an error group by passing this to UpdateGroup. When not specified, it's treated like OPEN.
feat: Make source location available for error groups created from GAE. PiperOrigin-RevId: 356330876
1 parent 78e0057 commit c1e5970

5 files changed

Lines changed: 195 additions & 22 deletions

File tree

‎google/devtools/clouderrorreporting/v1beta1/clouderrorreporting_v1beta1.yaml‎

Lines changed: 136 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
type: google.api.Service
22
config_version: 3
33
name: clouderrorreporting.googleapis.com
4-
title: Cloud Error Reporting API
4+
title: Error Reporting API
55

66
apis:
77
- name: google.devtools.clouderrorreporting.v1beta1.ErrorGroupService
@@ -13,6 +13,141 @@ documentation:
1313
Groups and counts similar errors from cloud services and applications,
1414
reports new errors, and provides access to error groups and their
1515
associated errors.
16+
overview: |-
17+
<!-- mdlint off(URL_BAD_G3DOC_PATH) -->
18+
19+
{% include "_shared/apis/console/_local_variables.html" %}
20+
{% include "cloud/_shared/_cloud_shared_files.html" %}
21+
22+
{% dynamic setvar launch_stage %}beta{% dynamic endsetvar %}
23+
{% dynamic include /docs/includes/___info_launch_stage_disclaimer %}
24+
25+
The {{error_reporting_api}} provides:
26+
27+
* A simple
28+
[endpoint](/error-reporting/reference/rest/v1beta1/projects.events/report)
29+
to **report** errors from your running service.
30+
* Read access to error groups and their associated errors.
31+
32+
## Getting started
33+
34+
{% dynamic setvar api_list %}clouderrorreporting.googleapis.com{% dynamic
35+
endsetvar %} {% dynamic setvar api_names %}{{error_reporting_name}}{%
36+
dynamic endsetvar %} {% dynamic setvar task_params %}no_steps{% dynamic
37+
endsetvar %} {% dynamic include /docs/includes/___enable_api %}
38+
39+
## Authorizing use of the API
40+
41+
Access to the {{error_reporting_api_short}} is controlled by {{iam_name}}
42+
roles and permissions. You can find out more about authentication and
43+
authorization for {{gcp_name}} APIs in the [Authentication
44+
guide](/docs/authentication/getting-started).
45+
46+
<aside class="note"><b>Note:</b> API keys are associated with a project
47+
for API quota and billing purposes, but they shouldn't be used as an
48+
<a href="/docs/authentication/#authentication_strategies">authentication
49+
mechanism</a> Instead, use <a
50+
href="/docs/authentication/getting-started#creating_a_service_account">service
51+
accounts</a> whenever possible. </aside>
52+
53+
## Data model
54+
55+
The {{error_reporting_api_short}} defines three entities: error events,
56+
error groups, and error group stats. The [error group
57+
stats](#error-group-stats)
58+
object is the object that most users will interact with most frequently.
59+
60+
### Error events
61+
62+
An [`ErrorEvent`](/error-reporting/reference/rest/v1beta1/ErrorEvent)
63+
represents a single occurrence of an error in your application. The
64+
object
65+
contains information about the error, such as the time at which it
66+
occurred, the context in which it occurred, and the error message that was
67+
returned.
68+
An error event is guaranteed to be available for at least 30 days after
69+
being generated.
70+
71+
### Error groups
72+
73+
[`ErrorGroup`](/error-reporting/reference/rest/v1beta1/projects.groups#ErrorGroup) objects
74+
are logically-grouped collections of error events. Grouping is
75+
based on information in the error event's stack trace. An error group is a
76+
simple object containing only the name, group ID, and any associated
77+
tracking issues for the group.
78+
79+
To update tracking issues URLs, use this resource's `update` method.
80+
81+
### Error group stats
82+
83+
[`ErrorGroupStats`](/error-reporting/reference/rest/v1beta1/projects.groupStats/list#ErrorGroupStats) objects
84+
contain detailed information about an error group,
85+
and are the API objects that you will interact with most frequently.
86+
Information in the `groupStats` object includes the first and last time an
87+
error event in this group occurred, the count, the number of affected
88+
users, and more. This object is useful when building widgets and custom
89+
dashboards.
90+
91+
## Operations
92+
93+
The {{error_reporting_api_short}} supports the following operations:
94+
95+
* Report a new error event
96+
* List error group stats
97+
* List error events
98+
* Get error groups
99+
* Update an error group's tracking issues
100+
101+
### Report error events
102+
103+
You can report error events from your running services by writing them to
104+
[`ReportedErrorEvent`](/error-reporting/reference/rest/v1beta1/projects.events/report#ReportedErrorEvent). Doing
105+
this generates
106+
[properly formatted error
107+
messages](/error-reporting/docs/formatting-error-messages) in
108+
{{logging_name}}. The resulting log name is formatted as
109+
`projects/<PROJECT_ID>/clouderrorreporting.googleapis.com%2Freported_errors`. You
110+
might incur minor {{logging_name}} ingestion costs using this method;
111+
to control these costs, review [Logs
112+
exclusions](/logging/docs/exclusions).
113+
114+
You can also report new error events to {{error_reporting_name}} by
115+
assembling [error event
116+
entities](/error-reporting/reference/rest/v1beta1/projects.events/report#ReportedErrorEvent) from
117+
your running service and sending them to the `events.report` method.
118+
119+
### List error group stats
120+
121+
To get a list of error group stats, send a request to the
122+
[`groupStats.list`](/error-reporting/reference/rest/v1beta1/projects.groupStats/list) method.
123+
You can pass one or more
124+
[query
125+
parameters](/error-reporting/reference/rest/v1beta1/projects.groupStats/list#body.QUERY_PARAMETERS) to
126+
filter the group stats that are returned.
127+
128+
### List error events
129+
130+
To get a list of error events belonging to a specific error group, send a
131+
request to the
132+
[`events.list`](/error-reporting/reference/rest/v1beta1/projects.events/list) method.
133+
You can pass a filter condition to these requests to retrieve only
134+
those error events that occurred between a specific start and end time, or
135+
those that match specific [service
136+
contexts](/error-reporting/reference/rest/v1beta1/ServiceContextFilter).
137+
138+
### Get error groups
139+
140+
To retrieve a specific error group resource, send a request to the
141+
[`groups.get`](/error-reporting/reference/rest/v1beta1/projects.groups/get) method. ###
142+
Update error groups
143+
144+
To update the tracking issue URLs associated with an error group, send an
145+
updated
146+
[`ErrorGroup`
147+
resource](/error-reporting/reference/rest/v1beta1/projects.groups#ErrorGroup) to
148+
the
149+
[`groups.update`](/error-reporting/reference/rest/v1beta1/projects.groups/update) method. <!--
150+
mdlint on -->
16151
17152
authentication:
18153
rules:

‎google/devtools/clouderrorreporting/v1beta1/common.proto‎

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2019 Google LLC.
1+
// Copyright 2021 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -16,9 +16,10 @@ syntax = "proto3";
1616

1717
package google.devtools.clouderrorreporting.v1beta1;
1818

19-
import "google/api/annotations.proto";
2019
import "google/api/resource.proto";
20+
import "google/appengine/logging/v1/request_log.proto";
2121
import "google/protobuf/timestamp.proto";
22+
import "google/api/annotations.proto";
2223

2324
option cc_enable_arenas = true;
2425
option csharp_namespace = "Google.Cloud.ErrorReporting.V1Beta1";
@@ -37,7 +38,7 @@ message ErrorGroup {
3738
};
3839

3940
// The group resource name.
40-
// Example: <code>projects/my-project-123/groups/my-groupid</code>
41+
// Example: <code>projects/my-project-123/groups/CNSgkpnppqKCUw</code>
4142
string name = 1;
4243

4344
// Group IDs are unique for a given project. If the same kind of error
@@ -46,6 +47,10 @@ message ErrorGroup {
4647

4748
// Associated tracking issues.
4849
repeated TrackingIssue tracking_issues = 3;
50+
51+
// Error group's resolution status.
52+
// An unspecified resolution status will be interpreted as OPEN
53+
ResolutionStatus resolution_status = 5;
4954
}
5055

5156
// Information related to tracking the progress on resolving the error.
@@ -123,6 +128,10 @@ message ErrorContext {
123128
// exception is logged, usually close to the place where it was
124129
// caught.
125130
SourceLocation report_location = 3;
131+
132+
// Source code that was used to build the executable which has
133+
// caused the given error message.
134+
repeated google.appengine.logging.v1.SourceReference source_references = 4;
126135
}
127136

128137
// HTTP request data that is related to a reported error.
@@ -169,3 +178,24 @@ message SourceLocation {
169178
// For example, `my.package.MyClass.method` in case of Java.
170179
string function_name = 4;
171180
}
181+
182+
// Resolution status of an error group.
183+
enum ResolutionStatus {
184+
// Status is unknown. When left unspecified in requests, it is treated like
185+
// OPEN.
186+
RESOLUTION_STATUS_UNSPECIFIED = 0;
187+
188+
// The error group is not being addressed. This is the default for
189+
// new groups. It is also used for errors re-occurring after marked RESOLVED.
190+
OPEN = 1;
191+
192+
// Error Group manually acknowledged, it can have an issue link attached.
193+
ACKNOWLEDGED = 2;
194+
195+
// Error Group manually resolved, more events for this group are not expected
196+
// to occur.
197+
RESOLVED = 3;
198+
199+
// The error group is muted and excluded by default on group stats requests.
200+
MUTED = 4;
201+
}

‎google/devtools/clouderrorreporting/v1beta1/error_group_service.proto‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2019 Google LLC.
1+
// Copyright 2021 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
1111
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1212
// See the License for the specific language governing permissions and
1313
// limitations under the License.
14-
//
1514

1615
syntax = "proto3";
1716

@@ -58,7 +57,7 @@ service ErrorGroupService {
5857

5958
// A request to return an individual group.
6059
message GetGroupRequest {
61-
// The group resource name. Written as
60+
// Required. The group resource name. Written as
6261
// `projects/{projectID}/groups/{group_name}`. Call
6362
// [`groupStats.list`](https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.groupStats/list)
6463
// to return a list of groups belonging to this project.

‎google/devtools/clouderrorreporting/v1beta1/error_stats_service.proto‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2019 Google LLC.
1+
// Copyright 2021 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
1111
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1212
// See the License for the specific language governing permissions and
1313
// limitations under the License.
14-
//
1514

1615
syntax = "proto3";
1716

@@ -68,11 +67,11 @@ service ErrorStatsService {
6867
// Specifies a set of `ErrorGroupStats` to return.
6968
message ListGroupStatsRequest {
7069
// Required. The resource name of the Google Cloud Platform project. Written
71-
// as <code>projects/</code> plus the
72-
// <a href="https://support.google.com/cloud/answer/6158840">Google Cloud
73-
// Platform project ID</a>.
70+
// as `projects/{projectID}` or `projects/{projectNumber}`, where `{projectID}`
71+
// and `{projectNumber}` can be found in the
72+
// [Google Cloud Console](https://support.google.com/cloud/answer/6158840).
7473
//
75-
// Example: <code>projects/my-project-123</code>.
74+
// Examples: `projects/my-project-123`, `projects/5551234`.
7675
string project_name = 1 [
7776
(google.api.field_behavior) = REQUIRED,
7877
(google.api.resource_reference) = {
@@ -258,9 +257,10 @@ enum ErrorGroupOrder {
258257
// Specifies a set of error events to return.
259258
message ListEventsRequest {
260259
// Required. The resource name of the Google Cloud Platform project. Written
261-
// as `projects/` plus the
260+
// as `projects/{projectID}`, where `{projectID}` is the
262261
// [Google Cloud Platform project
263262
// ID](https://support.google.com/cloud/answer/6158840).
263+
//
264264
// Example: `projects/my-project-123`.
265265
string project_name = 1 [
266266
(google.api.field_behavior) = REQUIRED,
@@ -357,9 +357,10 @@ message ServiceContextFilter {
357357
// Deletes all events in the project.
358358
message DeleteEventsRequest {
359359
// Required. The resource name of the Google Cloud Platform project. Written
360-
// as `projects/` plus the
360+
// as `projects/{projectID}`, where `{projectID}` is the
361361
// [Google Cloud Platform project
362362
// ID](https://support.google.com/cloud/answer/6158840).
363+
//
363364
// Example: `projects/my-project-123`.
364365
string project_name = 1 [
365366
(google.api.field_behavior) = REQUIRED,

‎google/devtools/clouderrorreporting/v1beta1/report_errors_service.proto‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2019 Google LLC.
1+
// Copyright 2021 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
1111
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1212
// See the License for the specific language governing permissions and
1313
// limitations under the License.
14-
//
1514

1615
syntax = "proto3";
1716

@@ -38,15 +37,23 @@ service ReportErrorsService {
3837
option (google.api.default_host) = "clouderrorreporting.googleapis.com";
3938
option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
4039

41-
// Report an individual error event.
40+
// Report an individual error event and record the event to a log.
4241
//
4342
// This endpoint accepts **either** an OAuth token,
4443
// **or** an [API key](https://support.google.com/cloud/answer/6158862)
4544
// for authentication. To use an API key, append it to the URL as the value of
4645
// a `key` parameter. For example:
4746
//
4847
// `POST
49-
// https://clouderrorreporting.googleapis.com/v1beta1/projects/example-project/events:report?key=123ABC456`
48+
// https://clouderrorreporting.googleapis.com/v1beta1/{projectName}/events:report?key=123ABC456`
49+
//
50+
// **Note:** [Error Reporting](/error-reporting) is a global service built
51+
// on Cloud Logging and doesn't analyze logs stored
52+
// in regional log buckets or logs routed to other Google Cloud projects.
53+
//
54+
// For more information, see
55+
// [Using Error Reporting with regionalized
56+
// logs](/error-reporting/docs/regionalization).
5057
rpc ReportErrorEvent(ReportErrorEventRequest) returns (ReportErrorEventResponse) {
5158
option (google.api.http) = {
5259
post: "/v1beta1/{project_name=projects/*}/events:report"
@@ -59,10 +66,11 @@ service ReportErrorsService {
5966
// A request for reporting an individual error event.
6067
message ReportErrorEventRequest {
6168
// Required. The resource name of the Google Cloud Platform project. Written
62-
// as `projects/` plus the
69+
// as `projects/{projectId}`, where `{projectId}` is the
6370
// [Google Cloud Platform project
64-
// ID](https://support.google.com/cloud/answer/6158840). Example:
65-
// `projects/my-project-123`.
71+
// ID](https://support.google.com/cloud/answer/6158840).
72+
//
73+
// Example: // `projects/my-project-123`.
6674
string project_name = 1 [
6775
(google.api.field_behavior) = REQUIRED,
6876
(google.api.resource_reference) = {

0 commit comments

Comments
 (0)