telemetry.proto

// Copyright 2021 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.log.eventpb;
option go_package = "eventpb";

import "gogoproto/gogo.proto";
import "util/log/eventpb/events.proto";
import "util/log/eventpb/sql_audit_events.proto";

// Category: Telemetry events
// Channel: TELEMETRY

// Notes to CockroachDB maintainers: refer to doc.go at the package
// level for more details. Beware that JSON compatibility rules apply
// here, not protobuf.
// The comment at the top has a specific format for the doc generator.
// *Really look at doc.go before modifying this file.*

// SampledQuery is the SQL query event logged to the telemetry channel. It
// contains common SQL event/execution details.
message SampledQuery {
  CommonEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
  CommonSQLEventDetails sql = 2 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
  CommonSQLExecDetails exec = 3 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];

  // skipped_queries indicate how many SQL statements were not
  // considered for sampling prior to this one. If the field is
  // omitted, or its value is zero, this indicates that no statement
  // was omitted since the last event.
  uint64 skipped_queries = 4 [(gogoproto.jsontag) = ",omitempty"];

  // Cost of the query as estimated by the optimizer.
  double cost_estimate = 5 [(gogoproto.jsontag) = ",omitempty"];

  // The distribution of the DistSQL query plan (local, full, or partial).
  string distribution = 6 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // The query's plan gist bytes as a base64 encoded string.
  string plan_gist = 7 [(gogoproto.jsontag) = ',omitempty', (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // SessionID is the ID of the session that initiated the query.
  string session_id = 8 [(gogoproto.customname) = "SessionID", (gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // Name of the database that initiated the query.
  string database = 9 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // Statement ID of the query.
  string statement_id = 10 [(gogoproto.customname) = "StatementID", (gogoproto.jsontag) = ',omitempty', (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // Transaction ID of the query.
  string transaction_id = 11 [(gogoproto.customname) = "TransactionID", (gogoproto.jsontag) = ',omitempty', (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // Statement fingerprint ID of the query.
  uint64 statement_fingerprint_id = 12 [(gogoproto.customname) = "StatementFingerprintID", (gogoproto.jsontag) = ',omitempty'];
}

// CapturedIndexUsageStats
message CapturedIndexUsageStats {
  CommonEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];

  // Couldn't use roachpb.CollectedIndexUsageStatistics due to circular dependency.

  // TotalReadCount is the number of times this index has been read from.
  uint64 total_read_count = 2;

  // LastRead is the timestamp that this index was last being read from.
  string last_read = 3 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // TableID is the ID of the table this index is created on. This is same as
  // descpb.TableID and is unique within the cluster.
  uint32 table_id = 4 [(gogoproto.customname) = "TableID"];

  // IndexID is the ID of the index within the scope of the given table.
  uint32 index_id = 5 [(gogoproto.customname) = "IndexID"];

  string database_name = 6 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];
  string table_name = 7 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];
  string index_name = 8 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];
  string index_type = 9 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];
  bool is_unique = 10 [(gogoproto.jsontag) = ",omitempty"];
  bool is_inverted = 11 [(gogoproto.jsontag) = ",omitempty"];
}

// CreateChangefeed is an event for any CREATE CHANGEFEED query that
// successfully starts running.  Failed CREATE statements will show up as
// ChangefeedFailed events.
message CreateChangefeed {
  CommonChangefeedEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
}

// ChangefeedFailed is an event for any Changefeed failure since the plan hook
// was triggered.
message ChangefeedFailed {
  CommonChangefeedEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];

  // The reason / environment with which the changefeed failed (ex:
  // connection_closed, changefeed_behind)
  string failure_type = 2 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) =  "redact:\"nonsensitive\""];
}