googleapis
diff --git a/‎protos/google/logging/v2/log_entry.proto
Lines changed: 69 additions & 30 deletions b/‎protos/google/logging/v2/log_entry.proto
Lines changed: 69 additions & 30 deletions
@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -75,7 +75,8 @@ message LogEntry {
   // Example: a log entry that reports a database error would be associated with
   // the monitored resource designating the particular database that reported
   // the error.
-  google.api.MonitoredResource resource = 8 [(google.api.field_behavior) = REQUIRED];
+  google.api.MonitoredResource resource = 8
+      [(google.api.field_behavior) = REQUIRED];
 
   // The log entry payload, which can be one of multiple types.
   oneof payload {
@@ -97,27 +98,32 @@ message LogEntry {
     google.protobuf.Struct json_payload = 6;
   }
 
-  // Optional. The time the event described by the log entry occurred. This time is used
-  // to compute the log entry's age and to enforce the logs retention period.
-  // If this field is omitted in a new log entry, then Logging assigns it the
-  // current time. Timestamps have nanosecond accuracy, but trailing zeros in
-  // the fractional seconds might be omitted when the timestamp is displayed.
+  // Optional. The time the event described by the log entry occurred. This time
+  // is used to compute the log entry's age and to enforce the logs retention
+  // period. If this field is omitted in a new log entry, then Logging assigns
+  // it the current time. Timestamps have nanosecond accuracy, but trailing
+  // zeros in the fractional seconds might be omitted when the timestamp is
+  // displayed.
   //
   // Incoming log entries must have timestamps that don't exceed the
   // [logs retention
   // period](https://cloud.google.com/logging/quotas#logs_retention_periods) in
   // the past, and that don't exceed 24 hours in the future. Log entries outside
   // those time boundaries aren't ingested by Logging.
-  google.protobuf.Timestamp timestamp = 9 [(google.api.field_behavior) = OPTIONAL];
+  google.protobuf.Timestamp timestamp = 9
+      [(google.api.field_behavior) = OPTIONAL];
 
   // Output only. The time the log entry was received by Logging.
-  google.protobuf.Timestamp receive_timestamp = 24 [(google.api.field_behavior) = OUTPUT_ONLY];
+  google.protobuf.Timestamp receive_timestamp = 24
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Optional. The severity of the log entry. The default value is `LogSeverity.DEFAULT`.
-  google.logging.type.LogSeverity severity = 10 [(google.api.field_behavior) = OPTIONAL];
+  // Optional. The severity of the log entry. The default value is
+  // `LogSeverity.DEFAULT`.
+  google.logging.type.LogSeverity severity = 10
+      [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. A unique identifier for the log entry. If you provide a value, then
-  // Logging considers other log entries in the same project, with the same
+  // Optional. A unique identifier for the log entry. If you provide a value,
+  // then Logging considers other log entries in the same project, with the same
   // `timestamp`, and with the same `insert_id` to be duplicates which are
   // removed in a single query result. However, there are no guarantees of
   // de-duplication in the export of logs.
@@ -129,12 +135,13 @@ message LogEntry {
   // the same `log_name` and `timestamp` values.
   string insert_id = 4 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. Information about the HTTP request associated with this log entry, if
-  // applicable.
-  google.logging.type.HttpRequest http_request = 7 [(google.api.field_behavior) = OPTIONAL];
+  // Optional. Information about the HTTP request associated with this log
+  // entry, if applicable.
+  google.logging.type.HttpRequest http_request = 7
+      [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. A map of key, value pairs that provides additional information about the
-  // log entry. The labels can be user-defined or system-defined.
+  // Optional. A map of key, value pairs that provides additional information
+  // about the log entry. The labels can be user-defined or system-defined.
   //
   // User-defined labels are arbitrary key, value pairs that you can use to
   // classify logs.
@@ -153,17 +160,47 @@ message LogEntry {
   // applicable.
   LogEntryOperation operation = 15 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. Resource name of the trace associated with the log entry, if any. If it
-  // contains a relative resource name, the name is assumed to be relative to
-  // `//tracing.googleapis.com`. Example:
-  // `projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824`
+  // Optional. The REST resource name of the trace being written to
+  // [Cloud Trace](https://cloud.google.com/trace) in
+  // association with this log entry. For example, if your trace data is stored
+  // in the Cloud project "my-trace-project" and if the service that is creating
+  // the log entry receives a trace header that includes the trace ID "12345",
+  // then the service should use "projects/my-tracing-project/traces/12345".
+  //
+  // The `trace` field provides the link between logs and traces. By using
+  // this field, you can navigate from a log entry to a trace.
   string trace = 22 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. The span ID within the trace associated with the log entry.
+  // Optional. The ID of the [Cloud Trace](https://cloud.google.com/trace) span
+  // associated with the current operation in which the log is being written.
+  // For example, if a span has the REST resource name of
+  // "projects/some-project/traces/some-trace/spans/some-span-id", then the
+  // `span_id` field is "some-span-id".
+  //
+  // A
+  // [Span](https://cloud.google.com/trace/docs/reference/v2/rest/v2/projects.traces/batchWrite#Span)
+  // represents a single operation within a trace. Whereas a trace may involve
+  // multiple different microservices running on multiple different machines,
+  // a span generally corresponds to a single logical operation being performed
+  // in a single instance of a microservice on one specific machine. Spans
+  // are the nodes within the tree that is a trace.
+  //
+  // Applications that are [instrumented for
+  // tracing](https://cloud.google.com/trace/docs/setup) will generally assign a
+  // new, unique span ID on each incoming request. It is also common to create
+  // and record additional spans corresponding to internal processing elements
+  // as well as issuing requests to dependencies.
+  //
+  // The span ID is expected to be a 16-character, hexadecimal encoding of an
+  // 8-byte array and should not be zero. It should be unique within the trace
+  // and should, ideally, be generated in a manner that is uniformly random.
+  //
+  // Example values:
   //
-  // For Trace spans, this is the same format that the Trace API v2 uses: a
-  // 16-character hexadecimal encoding of an 8-byte array, such as
-  // `000000000000004a`.
+  //   - `000000000000004a`
+  //   - `7a2190356c3fc94b`
+  //   - `0000f00300090021`
+  //   - `d39223e101960076`
   string span_id = 27 [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. The sampling decision of the trace associated with the log entry.
@@ -175,11 +212,13 @@ message LogEntry {
   // request correlation identifier. The default is False.
   bool trace_sampled = 30 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. Source code location information associated with the log entry, if any.
-  LogEntrySourceLocation source_location = 23 [(google.api.field_behavior) = OPTIONAL];
+  // Optional. Source code location information associated with the log entry,
+  // if any.
+  LogEntrySourceLocation source_location = 23
+      [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. Information indicating this LogEntry is part of a sequence of multiple log
-  // entries split from a single LogEntry.
+  // Optional. Information indicating this LogEntry is part of a sequence of
+  // multiple log entries split from a single LogEntry.
   LogSplit split = 35 [(google.api.field_behavior) = OPTIONAL];
 }