diff --git a/Makefile b/Makefile index a0eb46f77..70a607296 100644 --- a/Makefile +++ b/Makefile @@ -41,10 +41,14 @@ check-internal-links: clean build link-checker-setup run-link-checker check-all-links: clean build link-checker-setup bin/htmltest --conf .htmltest.external.yml -ifndef VTCTLDCLIENT_VERSION_PAIRS -export VTCTLDCLIENT_VERSION_PAIRS="main:16.0,v15.0.2:15.0" +ifndef COBRADOC_VERSION_PAIRS +export COBRADOC_VERSION_PAIRS="main:16.0,v15.0.2:15.0" endif # Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtctldclient-docs vtctldclient-docs: - go run ./tools/vtctldclientdocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${VTCTLDCLIENT_VERSION_PAIRS}" + go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtctldclient + +# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtorc-docs +vtorc-docs: + go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtorc diff --git a/content/en/docs/18.0/reference/programs/vtorc/_index.md b/content/en/docs/18.0/reference/programs/vtorc/_index.md new file mode 100644 index 000000000..e1794ab51 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtorc/_index.md @@ -0,0 +1,105 @@ +--- +title: vtorc +series: vtorc +--- +## vtorc + + + +``` +vtorc [flags] +``` + +### Options + +``` + --allow-emergency-reparent Whether VTOrc should be allowed to run emergency reparent operation when it detects a dead primary (default true) + --alsologtostderr log to standard error as well as files + --audit-file-location string File location where the audit logs are to be stored + --audit-purge-duration duration Duration for which audit logs are held before being purged. Should be in multiples of days (default 168h0m0s) + --audit-to-backend Whether to store the audit log in the VTOrc database + --audit-to-syslog Whether to store the audit log in the syslog + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --clusters_to_watch strings Comma-separated list of keyspaces or keyspace/shards that this instance will monitor and repair. Defaults to all clusters in the topology. Example: "ks1,ks2/-80" + --config string config file name + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --consul_auth_static_file string JSON File to read the topos/tokens from. + --emit_stats If set, emit stats to push-based monitoring and stats backends + --grpc_auth_static_client_creds string When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server. + --grpc_compression string Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy + --grpc_enable_tracing Enable gRPC tracing. + --grpc_initial_conn_window_size int gRPC initial connection window size + --grpc_initial_window_size int gRPC initial window size + --grpc_keepalive_time duration After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s) + --grpc_keepalive_timeout duration After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_prometheus Enable gRPC monitoring with Prometheus. + -h, --help help for vtorc + --instance-poll-time duration Timer duration on which VTOrc refreshes MySQL information (default 5s) + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --lock-timeout duration Maximum time for which a shard/keyspace lock can be acquired for (default 45s) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --port int port for the server + --pprof strings enable profiling + --prevent-cross-cell-failover Prevent VTOrc from promoting a primary in a different cell than the current primary in case of a failover + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --reasonable-replication-lag duration Maximum replication lag on replicas which is deemed to be acceptable (default 10s) + --recovery-period-block-duration duration Duration for which a new recovery is blocked on an instance after running a recovery (default 30s) + --recovery-poll-duration duration Timer duration on which VTOrc polls its database to run a recovery (default 1s) + --remote_operation_timeout duration time to wait for a remote operation (default 15s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --shutdown_wait_time duration Maximum time to wait for VTOrc to release all the locks that it is holding before shutting down on SIGTERM (default 30s) + --snapshot-topology-interval duration Timer duration on which VTOrc takes a snapshot of the current MySQL information it has in the database. Should be in multiple of hours + --sqlite-data-file string SQLite Datafile to use as VTOrc's database (default "file::memory:?mode=memory&cache=shared") + --stats_backend string The name of the registered push-based monitoring/stats backend to use + --stats_combine_dimensions string List of dimensions to be combined into a single "all" value in exported stats vars + --stats_common_tags strings Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2 + --stats_drop_variables string Variables to be dropped from the list of exported variables. + --stats_emit_period duration Interval between emitting stats to all registered backends (default 1m0s) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_manager_grpc_ca string the server ca to use to validate servers when connecting + --tablet_manager_grpc_cert string the cert to use to connect + --tablet_manager_grpc_concurrency int concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8) + --tablet_manager_grpc_connpool_size int number of tablets to keep tmclient connections open to (default 100) + --tablet_manager_grpc_crl string the server crl to use to validate server certificates when connecting + --tablet_manager_grpc_key string the key to use to connect + --tablet_manager_grpc_server_name string the server name to use to validate server certificate + --tablet_manager_protocol string Protocol to use to make tabletmanager RPCs to vttablets. (default "grpc") + --topo-information-refresh-duration duration Timer duration on which VTOrc refreshes the keyspace and vttablet records from the topology server (default 15s) + --topo_consul_lock_delay duration LockDelay for consul session. (default 15s) + --topo_consul_lock_session_checks string List of checks for consul session. (default "serfHealth") + --topo_consul_lock_session_ttl string TTL for consul session. + --topo_consul_watch_poll_duration duration time of the long poll for watch queries. (default 30s) + --topo_etcd_lease_ttl int Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) + --topo_etcd_tls_ca string path to the ca to use to validate the server cert when connecting to the etcd topo server + --topo_etcd_tls_cert string path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS + --topo_etcd_tls_key string path to the client key to use to connect to the etcd topo server, enables TLS + --topo_global_root string the path of the global topology data in the global topology server + --topo_global_server_address string the address of the global topology server + --topo_implementation string the topology implementation to use + --topo_zk_auth_file string auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass + --topo_zk_base_timeout duration zk base timeout (see zk.Connect) (default 30s) + --topo_zk_max_concurrency int maximum number of pending requests to send to a Zookeeper server. (default 64) + --topo_zk_tls_ca string the server ca to use to validate servers when connecting to the zk topo server + --topo_zk_tls_cert string the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS + --topo_zk_tls_key string the key to use to connect to the zk topo server, enables TLS + --v Level log level for V logs + -v, --version print binary version + --wait-replicas-timeout duration Duration for which to wait for replica's to respond when issuing RPCs (default 30s) +``` + diff --git a/tools/vtctldclientdocs/fsutil.go b/tools/cobradocs/fsutil.go similarity index 100% rename from tools/vtctldclientdocs/fsutil.go rename to tools/cobradocs/fsutil.go diff --git a/tools/vtctldclientdocs/main.go b/tools/cobradocs/main.go similarity index 79% rename from tools/vtctldclientdocs/main.go rename to tools/cobradocs/main.go index dab2cfeb5..a048997a3 100644 --- a/tools/vtctldclientdocs/main.go +++ b/tools/cobradocs/main.go @@ -26,11 +26,13 @@ import ( ) var ( - usage = "Generates website documentation for the `vtctldclient` binary for a given set of : pairs." + usage = "Generates website documentation for the given binary for a given set of : pairs." debug = flag.Bool("debug", false, "log debug info") vitessDir = flag.String("vitess-dir", "", "path to vitess checkout") - docGenPath = flag.String("vtctldclientdocgen-path", "./go/cmd/vtctldclient/docgen", "path to the vtctldclient doc generator, **relative to** --vitess-dir") - versionStrs = flag.String("version-pairs", "main:16.0", "CSV of : pairs to generate docs for; for example, 'v15.0.2:15.0' will generate docs from the v15.0.2 tag into the content/en/15.0 subtree. ensure your vitess checkout is up-to-date (git fetch --all) before running.") + docGenPath = flag.String("docgen-path", "", "path to the binary docs generator, **relative to** --vitess-dir. if blank, defaults to ./go/cmd/`binary`/docgen") + versionStrs = flag.String("version-pairs", "main:17.0", "CSV of : pairs to generate docs for; for example, 'v15.0.2:15.0' will generate docs from the v15.0.2 tag into the content/en/15.0 subtree. ensure your vitess checkout is up-to-date (git fetch --all) before running.") + + binaryName string ) func getValidWorkdir() (string, error) { @@ -70,11 +72,17 @@ func unwrap[T any](t T, err error) T { func main() { flag.Usage = func() { fmt.Fprintf(flag.CommandLine.Output(), "Usage of %s:\n", os.Args[0]) + fmt.Fprintf(flag.CommandLine.Output(), "%s \n", os.Args[0]) fmt.Fprintf(flag.CommandLine.Output(), "\n%s\n\n", usage) flag.PrintDefaults() } flag.Parse() + binaryName = flag.Arg(0) + if binaryName == "" { + log.Fatalf("binary name is required") + } + wd := unwrap(getValidWorkdir()) if *vitessDir == "" { @@ -103,6 +111,10 @@ func main() { versions = append(versions, version) } + if *docGenPath == "" { + *docGenPath = fmt.Sprintf("./go/cmd/%s/docgen", binaryName) + } + for _, version := range versions { must(version.GenerateDocs(wd, *vitessDir, *docGenPath)) } diff --git a/tools/vtctldclientdocs/version.go b/tools/cobradocs/version.go similarity index 97% rename from tools/vtctldclientdocs/version.go rename to tools/cobradocs/version.go index 3302529ba..038e5de65 100644 --- a/tools/vtctldclientdocs/version.go +++ b/tools/cobradocs/version.go @@ -29,7 +29,7 @@ type version struct { } func (v version) Dir(root string) string { - return filepath.Join(root, "content", "en", "docs", v.DocVersion, "reference", "programs", "vtctldclient") + return filepath.Join(root, "content", "en", "docs", v.DocVersion, "reference", "programs", binaryName) } func (v version) GenerateDocs(workdir string, vitessDir string, docgenPath string) (err error) {