recorded_span.proto

// Copyright 2017 The Cockroach Authors.
//
// Use of this software is governed by the Business Source License
// included in the file licenses/BSL.txt.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0, included in the file
// licenses/APL.txt.

syntax = "proto3";
package cockroach.util.tracing.tracingpb;
option go_package = "tracingpb";

import "gogoproto/gogo.proto";
import "google/protobuf/any.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

// LogRecord is a log message recorded in a traced span.
message LogRecord {
  // Time of the log record.
  google.protobuf.Timestamp time = 1 [(gogoproto.nullable) = false,
                                     (gogoproto.stdtime) = true];
  message Field {
    string key = 1;
    string value = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "github.com/cockroachdb/redact.RedactableString"];
  }
  // Fields with values converted to strings. In 22.1, the `message` field
  // contains the log message, and this field is only used for compatibility
  // with 21.2 nodes.
  repeated Field deprecated_fields = 2 [(gogoproto.nullable) = false];
  // The log message.
  string message = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "github.com/cockroachdb/redact.RedactableString"];
}

// StructuredRecord is a structured message recorded in a traced span.
message StructuredRecord {
  // Time of the structured record.
  google.protobuf.Timestamp time = 1 [(gogoproto.nullable) = false,
                                     (gogoproto.stdtime) = true];
  google.protobuf.Any payload = 2;
}

// RecordedSpan is the data recorded by a trace span. It
// needs to be able to cross RPC boundaries so that the
// complete recording of the trace can be constructed.
message RecordedSpan {
  option (gogoproto.goproto_stringer) = false;

  // ID of the trace; spans that are part of the same hierarchy share
  // the same trace ID.
  uint64 trace_id = 1 [(gogoproto.nullable) = false, (gogoproto.customname) = "TraceID", (gogoproto.customtype) = "TraceID"];
  // ID of the span.
  uint64 span_id = 2 [(gogoproto.nullable) = false, (gogoproto.customname) = "SpanID", (gogoproto.customtype) = "SpanID"];
  // ID of the parent span.
  uint64 parent_span_id = 3 [(gogoproto.nullable) = false, (gogoproto.customname) = "ParentSpanID", (gogoproto.customtype) = "SpanID"];
  // Operation name.
  string operation = 4;
  // Tags associated with the span.
  map<string, string> tags = 6;
  // Time when the span was started.
  google.protobuf.Timestamp start_time = 7 [(gogoproto.nullable) = false,
                                            (gogoproto.stdtime) = true];
  // The span's duration, measured from start to Finish().
  //
  // A span whose recording is collected before it's finished will have the
  // duration set as the "time of collection - start time". Such a span will
  // have an "unfinished" tag and a `finished` boolean value of false in this
  // recording.
  google.protobuf.Duration duration = 8 [(gogoproto.nullable) = false,
                                         (gogoproto.stdduration) = true];

  // RedactableLogs determines whether the verbose log messages are redactable.
  // This field was introduced in the 22.1 cycle. It can be removed in the 22.2
  // cycle. On 22.1 this is always set to `true`.
  bool redactable_logs = 15;
  // Events logged in the span.
  repeated LogRecord logs = 9 [(gogoproto.nullable) = false];
  // verbose indicates whether the span was recording in verbose mode at the
  // time the recording was produced.
  bool verbose = 16;

  // The ID of the goroutine on which the span was created.
  uint64 goroutine_id = 12 [(gogoproto.customname) = "GoroutineID"];

  // True if the span has been Finish()ed, false otherwise.
  bool finished = 13;

  // StructuredRecords contains StructuredRecord events recorded either in this
  // span, or in children spans that have finished while our span was not
  // recording verbosely.
  //
  // A StructuredRecord wraps the Payload with a RecordedAt timestamp to expose
  // information about when this event occurred.
  // DeprecatedInternalStructured only stores the Payloads.
  repeated StructuredRecord structured_records = 14 [(gogoproto.nullable) = false];

  reserved 5,10,11;
}

// NormalizedSpan is a representation of a RecordedSpan from a trace with all
// its children embedded, recursively. This JSON serialization of this proto is
// used in the system.statement_diagnostics.trace column.
//
// See RecordedSpan for the description of the fields.
message NormalizedSpan {
  string operation = 1;
  map<string, string> tags = 2;
  google.protobuf.Timestamp start_time = 3 [(gogoproto.nullable) = false,
                                           (gogoproto.stdtime) = true];
  google.protobuf.Duration duration = 4 [(gogoproto.nullable) = false,
                                        (gogoproto.stdduration) = true];
  repeated LogRecord logs = 5 [(gogoproto.nullable) = false];
  repeated StructuredRecord structured_records = 7 [(gogoproto.nullable) = false];
  repeated NormalizedSpan children = 6 [(gogoproto.nullable) = false];
}