kpt-grpc-demo/google/devtools/clouderrorreporting/v1beta1/clouderrorreporting_v1beta1.yaml

type: google.api.Service
config_version: 3
name: clouderrorreporting.googleapis.com
title: Error Reporting API

apis:
- name: google.devtools.clouderrorreporting.v1beta1.ErrorGroupService
- name: google.devtools.clouderrorreporting.v1beta1.ErrorStatsService
- name: google.devtools.clouderrorreporting.v1beta1.ReportErrorsService

documentation:
  summary: |-
    Groups and counts similar errors from cloud services and applications,
    reports new errors, and provides access to error groups and their
    associated errors.
  overview: |-
    <!-- mdlint off(URL_BAD_G3DOC_PATH) -->

    {% include "_shared/apis/console/_local_variables.html" %}
    {% include "cloud/_shared/_cloud_shared_files.html" %}

    {% dynamic setvar launch_stage %}beta{% dynamic endsetvar %}
    {% dynamic include /docs/includes/___info_launch_stage_disclaimer %}

    The {{error_reporting_api}} provides:

    * A simple
    [endpoint](/error-reporting/reference/rest/v1beta1/projects.events/report)
    to **report** errors from your running service.
    * Read access to error groups and their associated errors.

    ## Getting started

    {% dynamic setvar api_list %}clouderrorreporting.googleapis.com{% dynamic
    endsetvar %} {% dynamic setvar api_names %}{{error_reporting_name}}{%
    dynamic endsetvar %} {% dynamic setvar task_params %}no_steps{% dynamic
    endsetvar %} {% dynamic include /docs/includes/___enable_api %}

    ## Authorizing use of the API

    Access to the {{error_reporting_api_short}} is controlled by {{iam_name}}
    roles and permissions. You can find out more about authentication and
    authorization for {{gcp_name}} APIs in the [Authentication
    guide](/docs/authentication/getting-started).

    <aside class="note"><b>Note:</b> API keys are associated with a project
    for API   quota and billing purposes, but they shouldn't be used as an
    <a href="/docs/authentication/#authentication_strategies">authentication
    mechanism</a>   Instead, use <a
    href="/docs/authentication/getting-started#creating_a_service_account">service
    accounts</a>   whenever possible. </aside>

    ## Data model

    The {{error_reporting_api_short}} defines three entities: error events,
    error groups, and error group stats. The [error group
    stats](#error-group-stats)
    object is the object that most users will interact with most frequently.

    ### Error events

    An [`ErrorEvent`](/error-reporting/reference/rest/v1beta1/ErrorEvent)
    represents a single occurrence of an error in your application. The
    object
    contains information about the error, such as the time at which it
    occurred, the context in which it occurred, and the error message that was
    returned.
    An error event is guaranteed to be available for at least 30 days after
    being generated.

    ### Error groups

    [`ErrorGroup`](/error-reporting/reference/rest/v1beta1/projects.groups#ErrorGroup) objects
    are logically-grouped collections of error events. Grouping is
    based on information in the error event's stack trace. An error group is a
    simple object containing only the name, group ID, and any associated
    tracking issues for the group.

    To update tracking issues URLs, use this resource's `update` method.

    ### Error group stats

    [`ErrorGroupStats`](/error-reporting/reference/rest/v1beta1/projects.groupStats/list#ErrorGroupStats) objects
    contain detailed information about an error group,
    and are the API objects that you will interact with most frequently.
    Information in the `groupStats` object includes the first and last time an
    error event in this group occurred, the count, the number of affected
    users, and more. This object is useful when building widgets and custom
    dashboards.

    ## Operations

    The {{error_reporting_api_short}} supports the following operations:

    *   Report a new error event
    *   List error group stats
    *   List error events
    *   Get error groups
    *   Update an error group's tracking issues

    ### Report error events

    You can report error events from your running services by writing them to
    [`ReportedErrorEvent`](/error-reporting/reference/rest/v1beta1/projects.events/report#ReportedErrorEvent). Doing
    this generates
    [properly formatted error
    messages](/error-reporting/docs/formatting-error-messages) in
    {{logging_name}}. The resulting log name is formatted as
    `projects/<PROJECT_ID>/clouderrorreporting.googleapis.com%2Freported_errors`. You
    might incur minor {{logging_name}} ingestion costs using this method;
    to control these costs, review [Logs
    exclusions](/logging/docs/exclusions).

    You can also report new error events to {{error_reporting_name}} by
    assembling [error event
    entities](/error-reporting/reference/rest/v1beta1/projects.events/report#ReportedErrorEvent) from
    your running service and sending them to the `events.report` method.

    ### List error group stats

    To get a list of error group stats, send a request to the
    [`groupStats.list`](/error-reporting/reference/rest/v1beta1/projects.groupStats/list) method.
    You can pass one or more
    [query
    parameters](/error-reporting/reference/rest/v1beta1/projects.groupStats/list#body.QUERY_PARAMETERS) to
    filter the group stats that are returned.

    ### List error events

    To get a list of error events belonging to a specific error group, send a
    request to the
    [`events.list`](/error-reporting/reference/rest/v1beta1/projects.events/list) method.
    You can pass a filter condition to these requests to retrieve only
    those error events that occurred between a specific start and end time, or
    those that match specific [service
    contexts](/error-reporting/reference/rest/v1beta1/ServiceContextFilter).

    ### Get error groups

    To retrieve a specific error group resource, send a request to the
    [`groups.get`](/error-reporting/reference/rest/v1beta1/projects.groups/get) method. ###
    Update error groups

    To update the tracking issue URLs associated with an error group, send an
    updated
    [`ErrorGroup`
    resource](/error-reporting/reference/rest/v1beta1/projects.groups#ErrorGroup) to
    the
    [`groups.update`](/error-reporting/reference/rest/v1beta1/projects.groups/update) method. <!--
    mdlint on -->

authentication:
  rules:
  - selector: google.devtools.clouderrorreporting.v1beta1.ErrorGroupService.GetGroup
    oauth:
      canonical_scopes: |-
        https://www.googleapis.com/auth/cloud-platform
  - selector: google.devtools.clouderrorreporting.v1beta1.ErrorGroupService.UpdateGroup
    oauth:
      canonical_scopes: |-
        https://www.googleapis.com/auth/cloud-platform
  - selector: 'google.devtools.clouderrorreporting.v1beta1.ErrorStatsService.*'
    oauth:
      canonical_scopes: |-
        https://www.googleapis.com/auth/cloud-platform
  - selector: google.devtools.clouderrorreporting.v1beta1.ReportErrorsService.ReportErrorEvent
    oauth:
      canonical_scopes: |-
        https://www.googleapis.com/auth/cloud-platform