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 = 13 [(gogoproto.customname) = "StatementFingerprintID", (gogoproto.jsontag) = ',omitempty'];

  // Maximum number of rows scanned by a full scan, as estimated by the
  // optimizer.
  double max_full_scan_rows_estimate = 14 [(gogoproto.jsontag) = ",omitempty"];

  // Total number of rows read by all scans in the query, as estimated by the
  // optimizer.
  double total_scan_rows_estimate = 15 [(gogoproto.jsontag) = ",omitempty"];

  // The number of rows output by the query, as estimated by the optimizer.
  double output_rows_estimate = 16 [(gogoproto.jsontag) = ",omitempty"];

  // Whether table statistics were available to the optimizer when planning the
  // query.
  bool stats_available = 17 [(gogoproto.jsontag) = ",omitempty"];

  // The maximum number of nanoseconds that have passed since stats were
  // collected on any table scanned by this query.
  int64 nanos_since_stats_collected = 18 [(gogoproto.jsontag) = ",omitempty"];

  // The number of bytes read from disk.
  int64 bytes_read = 19 [(gogoproto.jsontag) = ",omitempty"];

  // The number of rows read from disk.
  int64 rows_read = 20 [(gogoproto.jsontag) = ",omitempty"];

  // The number of rows written.
  int64 rows_written = 21 [(gogoproto.jsontag) = ",omitempty"];

  // The duration of time in nanoseconds that the query experienced contention.
  int64 contention_time = 22 [(gogoproto.jsontag) = ',omitempty'];

  reserved 12;
}

// 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\""];
}

// RecoveryEvent is an event that is logged on every invocation of BACKUP,
// RESTORE, and on every BACKUP schedule creation, with the appropriate subset
// of fields populated depending on the type of event. This event is is also
// logged whenever a BACKUP and RESTORE job completes or fails.
message RecoveryEvent {
  // Common fields for all events.
  CommonEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];

  // RecoveryType is the type of recovery described by this event, which is one of
  // - backup
  // - scheduled_backup
  // - create_schedule
  // - restore
  //
  // It can also be a job event corresponding to the recovery, which is one of
  // - backup_job
  // - scheduled_backup_job
  // - restore_job
  string recovery_type = 2 [(gogoproto.jsontag) = ",omitempty", (gogoproto.customtype) = "RecoveryEventType", (gogoproto.nullable) = false, (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // Fields that are common to BACKUP and RESTORE statements.

  // TargetScope is the largest scope of the targets that the user is backing up
  // or restoring based on the following order:
  // table < schema < database < full cluster.
  string target_scope = 3 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // IsMultiregionTarget is true if any of the targets contain objects with
  // multi-region primitives.
  bool is_multiregion_target = 4 [(gogoproto.jsontag) = ",omitempty"];

  // TargetCount is the number of targets the in the BACKUP/RESTORE.
  uint32 target_count = 5 [(gogoproto.jsontag) = ",omitempty"];

  // DestinationSubdirType is
  // - latest: if using the latest subdir
  // - standard: if using a date-based subdir
  // - custom: if using a custom subdir that's not date-based
  string destination_subdir_type = 6 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // DestinationStorageTypes are the types of storage that the user is backing
  // up to or restoring from.
  repeated string destination_storage_types = 7 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // DestinationAuthTypes are the types of authentication methods that the user
  // is using to access the destination storage.
  repeated string destination_auth_types = 8 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // IsLocalityAware indicates if the BACKUP or RESTORE is locality aware.
  bool is_locality_aware = 9 [(gogoproto.jsontag) = ",omitempty"];

  // AsOfInterval is the time interval in nanoseconds between the statement
  // timestamp and the timestamp resolved by the AS OF SYSTEM TIME expression.
  // The interval is expressed in nanoseconds.
  int64 as_of_interval = 10 [(gogoproto.jsontag) = ",omitempty"];

  // WithRevisionHistory is true if the BACKUP includes revision history.
  bool with_revision_history = 11 [(gogoproto.jsontag) = ",omitempty"];

  // HasEncryptionPassphrase is true if the user provided an encryption
  // passphrase to encrypt/decrypt their backup.
  bool has_encryption_passphrase = 13 [(gogoproto.jsontag) = ",omitempty"];

  // KMSType is the type of KMS the user is using to encrypt/decrypt their
  // backup.
  string kms_type = 14 [(gogoproto.jsontag) = ",omitempty", (gogoproto.customname) = "KMSType", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // KMSCount is the number of KMS the user is using.
  uint32 kms_count = 15 [(gogoproto.jsontag) = ",omitempty", (gogoproto.customname) = "KMSCount"];

  // Options contain all the names of the options specified by the user in the
  // BACKUP or RESTORE statement. For options that are accompanied by a value,
  // only those with non-empty values will be present.
  //
  // It's important to note that there are no option values anywhere in the
  // event payload. Future changes to telemetry should refrain from adding
  // values to the payload unless they are properly redacted.
  repeated string options = 16 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // DebugPauseOn is the type of event that the restore should pause on for
  // debugging purposes. Currently only "error" is supported.
  string debug_pause_on = 17 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // Fields that are common to BACKUP and RESTORE jobs.

  // JobID is the ID of the BACKUP/RESTORE job.
  uint64 job_id = 18 [(gogoproto.jsontag) = ",omitempty", (gogoproto.customname) = "JobID"];
  // ResultStatus indicates whether the job succeeded or failed.
  string result_status = 20 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];
  // ErrorText is the text of the error that caused the job to fail.
  string error_text = 21 [(gogoproto.jsontag) = ",omitempty", (gogoproto.customtype) = "github.com/cockroachdb/redact.RedactableString", (gogoproto.nullable) = false, (gogoproto.moretags) = "redact:\"mixed\""];

  // Fields only for BACKUP schedules.

  // RecurringCron is the crontab for the incremental backup.
  string recurring_cron = 24 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // FullBackupCron is the crontab for the full backup.
  string full_backup_cron = 25 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // CustomFirstRunTime is the timestamp for the user configured first run time.
  // Expressed as nanoseconds since the Unix epoch.
  int64 custom_first_run_time = 26 [(gogoproto.jsontag) = ",omitempty"];

  // OnExecutionFailure describes the desired behavior if the schedule fails to
  // execute.
  string on_execution_failure = 27 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // OnPreviousRunning describes the desired behavior if the previously
  // scheduled BACKUP is still running.
  string on_previous_running = 28 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];

  // IgnoreExistingBackup is true iff the BACKUP schedule should still be
  // created even if a backup is already present in its destination.
  bool ignore_existing_backup = 29 [(gogoproto.jsontag) = ",omitempty"];

}