sql_audit_events.proto

// Copyright 2020 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";

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

// CommonSQLExecDetails contains the field common to all SQL query logs.
message CommonSQLExecDetails {
  // How the statement was being executed (exec/prepare, etc.)
  string exec_mode = 1 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];
  // Number of rows returned. For mutation statements (INSERT, etc) that
  // do not produce result rows, this field reports the number of rows affected.
  uint64 num_rows = 2 [(gogoproto.jsontag) = ",omitempty"];
  // The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error.
  string sqlstate = 3 [(gogoproto.customname) = "SQLSTATE", (gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];
  // The text of the error if any.
  string error_text = 4 [(gogoproto.jsontag) = ",omitempty"];
  // Age of the query in milliseconds.
  float age = 5 [(gogoproto.jsontag) = ",omitempty"];
  // Number of retries, when the txn was reretried automatically by the server.
  uint32 num_retries = 6 [(gogoproto.jsontag) = ",omitempty"];
  // Whether the query contains a full table scan.
  bool full_table_scan = 7 [(gogoproto.jsontag) = ",omitempty"];
  // Whether the query contains a full secondary index scan.
  bool full_index_scan = 8 [(gogoproto.jsontag) = ",omitempty"];
  // The sequence number of the SQL transaction inside its session.
  uint32 txn_counter = 9 [(gogoproto.jsontag) = ",omitempty"];
}


// Category: SQL Access Audit Events
// Channel: SENSITIVE_ACCESS
//
// Events in this category are generated when a table has been
// marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`.
//
// {% include {{ page.version.version }}/misc/experimental-warning.md %}
//
// Note: These events are not written to `system.eventlog`, even
// when the cluster setting `system.eventlog.enabled` is set. They
// are only emitted via external logging.

// SensitiveTableAccess is recorded when an access is performed to
// a table marked as audited.
message SensitiveTableAccess {
  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];
  // The name of the table being audited.
  string table_name = 4 [(gogoproto.jsontag) = ",omitempty"];
  // How the table was accessed (r=read / rw=read/write).
  string access_mode = 5 [(gogoproto.jsontag) = ",omitempty", (gogoproto.moretags) = "redact:\"nonsensitive\""];
}

// AdminQuery is recorded when a user with admin privileges (the user
// is directly or indirectly a member of the admin role) executes a query.
message AdminQuery {
  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];
}

// Category: SQL Slow Query Log
// Channel: SQL_PERF
//
// Events in this category report slow query execution.
//
// Note: these events are not written to `system.eventlog`, even
// when the cluster setting `system.eventlog.enabled` is set. They
// are only emitted via external logging.
//

// SlowQuery is recorded when a query triggers the "slow query" condition.
//
// As of this writing, the condition requires:
// - the cluster setting `sql.log.slow_query.latency_threshold`
//   set to a non-zero value, AND
// - EITHER of the following conditions:
//   - the actual age of the query exceeds the configured threshold; AND/OR
//   - the query performs a full table/index scan AND the cluster setting
//     `sql.log.slow_query.experimental_full_table_scans.enabled` is set.
message SlowQuery {
  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];
}

// CommonLargeRowDetails contains the fields common to both LargeRow and
// LargeRowInternal events.
message CommonLargeRowDetails {
  uint32 row_size = 1 [(gogoproto.jsontag) = ",omitempty"];
  uint32 table_id = 2 [(gogoproto.customname) = "TableID", (gogoproto.jsontag) = ",omitempty"];
  uint32 family_id = 3 [(gogoproto.customname) = "FamilyID", (gogoproto.jsontag) = ",omitempty"];
  string primary_key = 4 [(gogoproto.jsontag) = ",omitempty"];
  bool violates_max_row_size_err = 5 [(gogoproto.jsontag) = ",omitempty"];
}

// LargeRow is recorded when a statement tries to write a row larger than
// cluster setting `sql.mutations.max_row_size.log` to the database. Multiple
// LargeRow events will be recorded for statements writing multiple large rows.
// LargeRow events are recorded before the transaction commits, so in the case
// of transaction abort there will not be a corresponding row in the database.
message LargeRow {
  CommonEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
  CommonLargeRowDetails row = 2 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
}

// CommonTxnRowsLimitReachedDetails contains the fields common to all messages
// related to reaching the limits on the number of rows written/read by a
// transaction.
message CommonTxnRowsLimitReachedDetails {
  string txn_id = 1 [(gogoproto.customname) = "TxnID", (gogoproto.jsontag) = ",omitempty"];
  string session_id = 2 [(gogoproto.customname) = "SessionID", (gogoproto.jsontag) = ",omitempty"];
  bool violates_txn_rows_limit_err = 3 [(gogoproto.jsontag) = ",omitempty"];
  // ReadKind indicates that the "rows read" limit is reached if true and
  // the "rows written" limit otherwise.
  bool read_kind = 4 [(gogoproto.jsontag) = ",omitempty"];
}

// TxnRowsWrittenLimitReached is recorded when a transaction tries to write more
// rows than cluster setting `sql.defaults.transaction_rows_written_log`. There
// will only be a single record for a single transaction (unless it is retried)
// even if there are more mutation statement within the transaction that haven't
// been executed yet.
message TxnRowsWrittenLimitReached {
  CommonEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
  CommonTxnRowsLimitReachedDetails info = 2 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
}

// TxnRowsReadLimitReached is recorded when a transaction tries to read more
// rows than cluster setting `sql.defaults.transaction_rows_read_log`. There
// will only be a single record for a single transaction (unless it is retried)
// even if there are more statement within the transaction that haven't been
// executed yet.
message TxnRowsReadLimitReached {
  CommonEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
  CommonTxnRowsLimitReachedDetails info = 2 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
}

// Category: SQL Slow Query Log (Internal)
// Channel: SQL_INTERNAL_PERF
//
// Events in this category report slow query execution by
// internal executors, i.e., when CockroachDB internally issues
// SQL statements.
//
// Note: these events are not written to `system.eventlog`, even
// when the cluster setting `system.eventlog.enabled` is set. They
// are only emitted via external logging.

// SlowQueryInternal is recorded when a query triggers the "slow query" condition,
// and the cluster setting `sql.log.slow_query.internal_queries.enabled` is
// set.
// See the documentation for the event type `slow_query` for details about
// the "slow query" condition.
message SlowQueryInternal {
  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];
}

// LargeRowInternal is recorded when an internal query tries to write a row
// larger than cluster settings `sql.mutations.max_row_size.log` or
// `sql.mutations.max_row_size.err` to the database.
message LargeRowInternal {
  CommonEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
  CommonLargeRowDetails row = 2 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
}

// TxnRowsWrittenLimitReachedInternal is recorded when an internal transaction
// tries to write more rows than cluster setting
// `sql.defaults.transaction_rows_written_log` or
// `sql.defaults.transaction_rows_written_err`. There will only be a single
// record for a single transaction (unless it is retried) even if there are more
// mutation statement within the transaction that haven't been executed yet.
message TxnRowsWrittenLimitReachedInternal {
  CommonEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
  CommonTxnRowsLimitReachedDetails info = 2 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
}

// TxnRowsReadLimitReachedInternal is recorded when an internal transaction
// tries to read more rows than cluster setting
// `sql.defaults.transaction_rows_read_log` or
// `sql.defaults.transaction_rows_read_err`. There will only be a single
// record for a single transaction (unless it is retried) even if there are more
// mutation statement within the transaction that haven't been executed yet.
message TxnRowsReadLimitReachedInternal {
  CommonEventDetails common = 1 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
  CommonTxnRowsLimitReachedDetails info = 2 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "", (gogoproto.embed) = true];
}

// Category: SQL Execution Log
// Channel: SQL_EXEC
//
// Events in this category report executed queries.
//
// Note: These events are not written to `system.eventlog`, even
// when the cluster setting `system.eventlog.enabled` is set. They
// are only emitted via external logging.

// QueryExecute is recorded when a query is executed,
// and the cluster setting `sql.trace.log_statement_execute` is set.
message QueryExecute {
  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];
}