OTLP log ingestion overview

This document introduces the use of the Telemetry (OTLP) API , telemetry.googleapis.com , for the ingestion of OTLP-formatted logs into Cloud Logging, where they are stored as log entries . For an example, see Write OTLP-formatted logs to the Telemetry API .

You can also send logs to the Telemetry API from applications that use SDKs or by using an OpenTelemetry Collector.

For information about the Telemetry API for logs, metrics, and traces, see Telemetry (OTLP) API reference .

Protocol support

The OTLP endpoint supports all of the OTLP protocols, including http/protobuf , http/json , and grpc . When exporting from an OpenTelemetry Collector, you can use any of the protocols. However, due to the lack of support for dynamic token refreshing in most SDK exporters, if you are exporting directly from SDKs, then we recommend using only the gRPC OTLP exporter, not the HTTP exporters,

Billing

You might see a change in your Cloud Logging storage and billing values when you use the Telemetry API to ingestion logs. An OTLP-formatted log request in JSON has the following general structure:

 "resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "scope": { ...}
          "logRecords": [...]
        }
      ]
    }
] 

Each item in each logRecords array becomes a single Cloud Logging log entry. The largest changes to storage and billing for your Google Cloud project occur when both of the following are true:

• The resource field contains a large number of required attributes for keys and values. These resource attributes are used to determine the monitored resource in the resulting LogEntry .

  The monitored resource consists of a Cloud Logging monitored-resource type and values for its associated labels. Some monitored-resource types have very few labels, but some resource types have many labels. For more information about which attributes are required for ingestion of OTLP-formatted logs, see OTLP attributes to resource-type mapping .

• The scopeLogs field contains a large number of items in the logRecords arrays.

To support ingestion of OTLP-formatted logs, the Cloud Logging LogEntry structure contains an additional field, otel . The OTLP and Cloud Logging data models are not a perfect match, so the otel field contains a copy of the OTLP Resource, Scope, and Entities from the incoming OTLP request.

For example, if you send an OTLP resourceLog like the following to the Telemetry API, then each resulting log entry contains a resource field (for the monitored resource) and an otel field, as shown on the other tabs:

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": " PROJECT_ID 
" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

{
    ...
    "resource": {
      "labels": {
        "project_id": " PROJECT_ID 
"
      },
      "type": "global"
    },
    ...
}

{
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": " PROJECT_ID 
",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

Cloud Logging has no way to link other resources to a log entry, so all the information about OTLP resources, scopes, and entities must be copied to each log entry.

This duplication preserves as much information as possible from the original request in the resulting log entry. But the duplication also means the otel field repeats resource information also used in the monitored-resource ( resource ) field of the log entry. The resource field of the log entry is chargeable, but the resource information duplicated in the otel field is not.

When you include a large number log records in the OTLP request, the OTLP information must be copied to each resulting log entry, into both the resource and otel fields. And although the storage for the copies of the otel field is not chargeable, storage for the additional copies of the resource field is. When you include a large number of OTLP logRecords in a request, the number of chargeable resource fields in your log entries increases in proportion to the number of OTLP logRecords per resource per request.

To minimize the additional information stored, we recommend sending one logRecord item per request.

Limits and quotas

For information about limits and quotas associated with the using the Telemetry API for logging, see Limits and quotas for ingestion of logs .

The Cloud Logging quotas and limits also apply when using the Telemetry API for log ingestion.