1type: google.api.Service
2config_version: 3
3name: clouderrorreporting.googleapis.com
4title: Error Reporting API
5
6apis:
7- name: google.devtools.clouderrorreporting.v1beta1.ErrorGroupService
8- name: google.devtools.clouderrorreporting.v1beta1.ErrorStatsService
9- name: google.devtools.clouderrorreporting.v1beta1.ReportErrorsService
10
11documentation:
12  summary: |-
13    Groups and counts similar errors from cloud services and applications,
14    reports new errors, and provides access to error groups and their
15    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 -->
151
152authentication:
153  rules:
154  - selector: google.devtools.clouderrorreporting.v1beta1.ErrorGroupService.GetGroup
155    oauth:
156      canonical_scopes: |-
157        https://www.googleapis.com/auth/cloud-platform
158  - selector: google.devtools.clouderrorreporting.v1beta1.ErrorGroupService.UpdateGroup
159    oauth:
160      canonical_scopes: |-
161        https://www.googleapis.com/auth/cloud-platform
162  - selector: 'google.devtools.clouderrorreporting.v1beta1.ErrorStatsService.*'
163    oauth:
164      canonical_scopes: |-
165        https://www.googleapis.com/auth/cloud-platform
166  - selector: google.devtools.clouderrorreporting.v1beta1.ReportErrorsService.ReportErrorEvent
167    oauth:
168      canonical_scopes: |-
169        https://www.googleapis.com/auth/cloud-platform
170