API overview

This page provides a brief overview of the Observability API and the Telemetry (OTLP) API.

About the Observability API

The Observability API lets you do the following:

  • Configure default settings for observability buckets for projects, folders, and organizations. These settings help you meet your compliance and regulatory requirements. You can configure the following:

    • A default storage location for new observability buckets.
    • For each location, a default Cloud Key Management Service key. That key is used to encrypt new observability buckets.

    For more information, see Set defaults for observability buckets.

  • Configure the observability scope for your project. This scope controls which resources are searched by the explorer pages for log, metric, and trace data. For more information, see Configure observability scopes.

  • List information about the observability buckets in your Google Cloud project. Your trace data is stored in an observability bucket. For information about the data model, see Storage overview.

  • Create a link on a dataset, which lets BigQuery have read access to the dataset. To learn how to create a linked dataset, see Manage storage.

Service endpoints

A service endpoint is a base URL that specifies the network address of an API service. The Observability API supports a global endpoint and regional endpoints:

  • Global endpoint: observability.googleapis.com.

    You can use the global service endpoint to perform any operations supported by the Observability API. Additionally, for this endpoint, the list observability buckets command lets you replace the location field in the path parameter with the wildcard (-).

  • Regional endpoints: observability.REGION.rep.googleapis.com, where REGION is a supported region. For a list of endpoints, see Regional service endpoint.

    You can use a regional service endpoint only when the location provided in the path parameter matches the endpoint's region. Commands sent to these service endpoints fail if they include a wildcard or if the location differs from the endpoint's region.

API reference

About the Telemetry API

The Telemetry (OTLP) API is an implementation of the OpenTelemetry OTLP Protocol. The Telemetry API provides compatibility and support for the open source OpenTelemetry ecosystem:

  • Logs: The Telemetry API lets you ingest OTLP-formatted log records to your project. For more information, see Write OTLP logs to the Telemetry API.

  • Metrics: The Telemetry API lets you ingest OTLP-formatted metrics into Cloud Monitoring by using the otlphttp exporter and an OpenTelemetry Collector or an OpenTelemetry SDK. For more information, see OTLP metric ingestion overview.

  • Traces: The Telemetry API lets you send OTLP-formatted trace data to your project. Also, the trace limits for the Telemetry API are often more generous than the limits for the Cloud Trace API.

Service endpoints

A service endpoint is a base URL that specifies the network address of an API service. The Telemetry API supports a global endpoint and regional endpoints:

  • Global endpoint: telemetry.googleapis.com. For this endpoint, after Google Cloud Observability successfully completes all validation steps, it sends the data to a backend service for storage.

  • Regional endpoints: telemetry.REGION.rep.googleapis.com, where REGION is a supported region. For these endpoints, after Google Cloud Observability successfully completes all validation steps, it sends the data to a backend service. This service either stores or discards the data:

    • Log and trace data is stored. The backend service automatically moves data between regions when necessary.
    • Metric data is stored only when the location label attached to the data matches the endpoint's region or a zone within that region.

    For a list of supported regional endpoints, see the API reference pages.

The ingestion of trace data can trigger the creation of an observability bucket. However, the use of a regional endpoint doesn't affect where the system creates the observability bucket. The system determines the location of an observability bucket using default settings, organization policies, and the set of supported bucket locations.

API reference

For more information about the Telemetry API, see the following documents: