{"id":14988320,"url":"https://github.com/apache/incubator-seata-ctl","last_synced_at":"2025-10-06T22:04:21.116Z","repository":{"id":207678718,"uuid":"709687448","full_name":"apache/incubator-seata-ctl","owner":"apache","description":"The operational tool for Seata-Server.","archived":false,"fork":false,"pushed_at":"2024-10-28T13:48:28.000Z","size":63,"stargazers_count":5,"open_issues_count":1,"forks_count":4,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-01-30T10:06:47.377Z","etag":null,"topics":["at","db","health","raft","saga","tcc","tool","xa"],"latest_commit_sha":null,"homepage":"https://seata.apache.org/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.png","metadata":{"files":{"readme":"README.md","changelog":"changes/en-us/0.0.1.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-10-25T07:41:52.000Z","updated_at":"2024-10-30T04:43:08.000Z","dependencies_parsed_at":"2023-11-17T03:58:48.145Z","dependency_job_id":"10462e9e-f364-41a8-86d4-a997e7924486","html_url":"https://github.com/apache/incubator-seata-ctl","commit_stats":null,"previous_names":["seata/seata-ctl","apache/incubator-seata-ctl"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fincubator-seata-ctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fincubator-seata-ctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fincubator-seata-ctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fincubator-seata-ctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/incubator-seata-ctl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237133508,"owners_count":19260497,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["at","db","health","raft","saga","tcc","tool","xa"],"created_at":"2024-09-24T14:16:31.727Z","updated_at":"2025-10-06T22:04:21.110Z","avatar_url":"https://github.com/apache.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nLicensed to the Apache Software Foundation (ASF) under one or more\ncontributor license agreements.  See the NOTICE file distributed with\nthis work for additional information regarding copyright ownership.\nThe ASF licenses this file to You under the Apache License, Version 2.0\n(the \"License\"); you may not use this file except in compliance with\nthe License.  You may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n--\u003e\n# Introduction\n\nThis is a CLI tool for [Seata](https://github.com/seata/seata) named `seata-ctl`.\n\n```shell\n$ seata-ctl -h\nseata-ctl is a CLI tool for Seata\n\nUsage:\n  seata-ctl [flags]\n  seata-ctl [command]\n\nAvailable Commands:\n  version     Print the version number of seata-ctl\n\nFlags:\n  -h, --help              help for seata-ctl\n      --ip string         Seata Server IP (constants \"127.0.0.1\")\n      --password string   Password (constants \"seata\")\n      --port int          Seata Server Admin Port (constants 7091)\n      --username string   Username (constants \"seata\")\n\nUse \"seata-ctl [command] --help\" for more information about a command.\n```\n\n# Build\n\nDependency: Go 1.19+\n\n```shell\ngo build .\n```\n\n# How to use\n\n# Seata\n\nSome Seata commands are used to connect to the Seata server for configuration browsing, transaction simulation, and other functions. To use these features, you must first log in using the `Login` command.\n\n## Login\n\nUse this command to log in to the seata section. If the login is successful, the login information will be displayed at the beginning of the command line.\n\n```shell\n$ seata-ctl login --ip=127.0.0.1 --port=7091 --username=seata --password=seata\n127.0.0.1:7091 \u003e # input command here\n```\n\n## Help\n\n```shell\n127.0.0.1:7091 \u003e help\nUsage:\n  [command] [flag] \n\nAvailable Commands:\n  get         Get the resource\n  help        Help about any command\n  quit        Quit the session\n  reload      Reload the configuration\n  set         Set the resource\n  try         Try example transactions\n```\n\n## Get\n\n### Usage\n\n```shell\n127.0.0.1:7091 \u003e get -h    \nGet the resource\n\nUsage:\n   get [flags]\n   get [command]\n\nAvailable Commands:\n  config        Get the configuration\n  status        Get the status\n\nFlags:\n  -h, --help   help for get\n\nUse \"get [command] --help\" for more information about a command.\n```\n\n### Example\n\n1. Get the status of the Seata server cluster:\n\n```shell\n127.0.0.1:7091 \u003e get status\n+-------+--------------------+--------+\n| TYPE  | ADDRESS            | STATUS |\n+-------+--------------------+--------+\n| nacos | 192.168.163.1:7091 | ok     |\n+-------+--------------------+--------+\n| nacos | 192.168.163.2:7091 | ok     |\n+-------+--------------------+--------+\n```\n\n2. Get the configuration `server.servicePort`:\n\n```shell\n127.0.0.1:7091 \u003e get config --key '[\"server.servicePort\"]'\n+--------------------+-------+\n| KEY                | VALUE |\n+--------------------+-------+\n| server.servicePort | 8091  |\n+--------------------+-------+\n```\n\n3. Get multiple configuration (which could be written in multiple lines by ending with '\\\\'):\n\n```shell\n127.0.0.1:7091 \u003e get config --key '[ \\\n    \"server.servicePort\", \\\n    \"server.recovery.timeoutRetryPeriod\", \\\n    \"server.undo.logDeletePeriod\" \\\n]'\n+------------------------------------+----------+\n| KEY                                | VALUE    |\n+------------------------------------+----------+\n| server.recovery.timeoutRetryPeriod | 1000     |\n| server.servicePort                 | 8091     |\n| server.undo.logDeletePeriod        | 86400000 |\n+------------------------------------+----------+\n```\n\n4. Get all configurations\n\n```shell\n127.0.0.1:7091 \u003e get config\n+------------------------------------+----------+\n| KEY                                | VALUE    |\n+------------------------------------+----------+\n...\n```\n\n## Set\n\n### Usage\n\n```shell\n127.0.0.1:7091 \u003e set -h                    \nSet the resource\n\nUsage:\n   set [flags]\n   set [command]\n\nAvailable Commands:\n  config        Set the configuration\n\nFlags:\n  -h, --help   help for set\n\nUse \"set [command] --help\" for more information about a command.\n```\n\n```shell\n127.0.0.1:7091 \u003e set config -h\nSet the configuration\n\nUsage:\n   set config [flags]\n\nFlags:\n      --config-center   If set configuration center conf\n      --data string     Configuration map (constants \"{}\")\n  -h, --help            help for config\n      --registry        If set registry conf\n```\n\n### Example\n\n1. Set the registry config, such as setting type to `eureka`:\n\n```shell\n127.0.0.1:7091 \u003e set config --registry --data '{\"registry.type\": \"eureka\"}'\n+---------------+------+--------+\n| KEY           | FROM | TO     |\n+---------------+------+--------+\n| registry.type | file | eureka |\n+---------------+------+--------+\n```\n\nYou can found that the Seata server is registered at `eureka` registry.\n\n2. Set the configuration center config, such as setting type to `nacos`\n\n```shell\n127.0.0.1:7091 \u003e set config --config-center --data '{\"config.type\": \"nacos\"}'\n+-------------+------+-------+\n| KEY         | FROM | TO    |\n+-------------+------+-------+\n| config.type | file | nacos |\n+-------------+------+-------+\n```\n\nYou can found that the configuration in `nacos` is loaded.\n\n3. Set a configuration item which can be dynamically configured (such as `server.undo.logSaveDays`):\n\n```shell\n127.0.0.1:7091 \u003e set config --data '{\"server.undo.logSaveDays\": \"5\"}'\n+-------------------------+------+----+\n| KEY                     | FROM | TO |\n+-------------------------+------+----+\n| server.undo.logSaveDays | 6    | 5  |\n+-------------------------+------+----+\n```\n\n4. Set multiple configurations at the same time:\n\n```shell\n127.0.0.1:7091 \u003e set config --data '{ \\\n    \"server.maxCommitRetryTimeout\": \"3000\", \\\n    \"server.maxRollbackRetryTimeout\": \"3000\", \\\n    \"server.undo.logSaveDays\": \"14\" \\\n}'\n+--------------------------------+------+------+\n| KEY                            | FROM | TO   |\n+--------------------------------+------+------+\n| server.maxCommitRetryTimeout   | -1   | 3000 |\n| server.maxRollbackRetryTimeout | -1   | 3000 |\n| server.undo.logSaveDays        | 5    | 14   |\n+--------------------------------+------+------+\n```\n\n## Try\n\n### Usage\n\n```shell\n127.0.0.1:7091 \u003e try -h\nTry if this node is ready\n\nUsage:\n   try [flags]\n   try [command]\n\nAvailable Commands:\n  begin       begin a txn\n  commit      commit a txn\n  rollback    rollback a txn\n\nFlags:\n  -h, --help   help for try\n\nUse \"try [command] --help\" for more information about a command.\n```\n\n### Example\n\n1. Try to begin an example transaction:\n\n```shell\n127.0.0.1:7091 \u003e try begin --timeout 300000\nTry an example txn successfully, xid=192.168.163.1:8091:8755443813836259333\n```\n\n2. Commit a transaction by xid:\n\n```shell\n127.0.0.1:7091 \u003e try commit --xid 192.168.163.1:8091:8755443813836259333\nCommit txn successfully, xid=192.168.163.1:8091:8755443813836259333\n```\n\n3. Rollback a transaction by xid:\n\n```shell\n127.0.0.1:7091 \u003e try rollback --xid 192.168.163.1:8091:8755443813836259333\nRollback txn successfully, xid=192.168.163.1:8091:8755443813836259333\n```\n\nLifecycle of the transactions could be checked in Web console UI. (exposed at `7091` by default).\n\n## Reload\n\n### Usage\n\n```shell\nreload -h\nReload the configuration\n\nUsage:\n   reload [flags]\n\nFlags:\n  -h, --help   help for reload\n```\n\n### Example\n\n```shell\n127.0.0.1:7091 \u003e reload\nReload Successful!\n```\n\n## Quit\n\nQuit the session:\n\n```shell\n127.0.0.1:7091 \u003e quit\nQuit the session\n```\n\n# Config\n\nSeata-ctl uses a YAML configuration file to set up various cluster addresses and connection details. Since manually creating this file can be complex for users, Seata-ctl provides a template for the configuration file.\n\n## Config\n\n### Describe\n\nUsed to initialize the configuration file with no parameters required.\n\nAfter execution, a file named `config.yaml` will be created in the same directory as the terminal. If the file already exists, a message will indicate this. Currently, selecting a different location is not supported.\n\n### Usage\n\n```\nseata-ctl\nconfig\n```\n\nAfter use, a file named 'config. yaml' will be created in the same directory as the terminal. If the file already exists, it will prompt that it already exists. We currently do not support selecting other locations.\n\nEach cluster can fill in multiple instances, using a context mechanism similar to kubeconfig to select which cluster and service to use.\n\nThe format of the file and the meanings of each field are as follows:(The parameters of the log section will be explained in detail later in the log section)\n\n```\nkubernetes:\n    clusters:\n        - name: \"\"\t//kubernetes cluster name\n          kubeconfigpath: \"\"\t//kubeconfig path\n          ymlpath: \"\"\t\t//yml config path,not currently supported\nprometheus:\n    servers:\n        - name: \"\"\t//prometheus name\n          address: \"\"\t//prometheus address\n          auth: \"\"\t//prometheus auth info,not currently supported\nlog:\n    clusters:\n        - name: \"\"\t//log name\n          types: \"\"\t//log type:ElasticSearch,Loki,Local\n          address: \"\"\t//log server address\n          source: \"\"\t//index name\n          username: \"\"\t//auth username\n          password: \"\"\t//auth password\n          index: \"\"\t\t\t//index name\ncontext:\n    kubernetes: \"\"  //choose which clusters to use,depend on name\n    prometheus: \"\" \t//choose which clusters to use,depend on name\n    log: \"\"\t\t\t\t\t//choose which clusters to use,depend on name\n```\n\n### Example\n\nIf everything is normal, it will output:\n\n```\nseata-ctl\nconfig\n\nConfig created successfully!\n```\n\nIf the file already exists, it will be output as follows:\n\n```\nseata-ctl\nconfig\n\nConfig file already exists!\n```\n\nThe example of writing a configuration file is as follows：\n\n```\nkubernetes:\n  clusters:\n    - name: \"cluster1\"\n      kubeconfigpath: \"/Users/wpy/.kube/config\"\n      ymlpath: \"\"\n    - name: \"seata\"\n      kubeconfigpath: \"/Users/wpy/Documents/Kubernetes/remotekube.txt\"\n      ymlpath: \"\"\nprometheus:\n  servers:\n    - name: \"prometheus\"\n      address: \"http://localhost:9092\"\n      auth: \"\"\nlog:\n  clusters:\n    - name: \"es\"\n      types: \"ElasticSearch\"\n      address: \"https://localhost:9200\"\n      source: \"logstash-2024.10.24\"\n      username: \"elastic\"\n      password: \"bu4AC50REtt_7rUqddMe\"\n      index: \"log\"\n    - name: \"loki\"\n      types: \"Loki\"\n      address: \"http://localhost:3100\"\n      source: \"\"\n      username: \"\"\n      password: \"\"\n      index: \"\"\n    - name: \"local\"\n      types: \"Local\"\n      address: \"http://localhost:8080\"\n      source: \"seata\"\n      username: \"\"\n      password: \"\"\n      index: \"\"\ncontext:\n  kubernetes: \"cluster1\"\n  prometheus: \"prometheus\"\n  log: \"es\"\n```\n\n# Kubernetes\n\nSeata ctl provides various commands to operate Seata servers on Kubernetes clusters.\n\n## Install\n\n### Describe\n\nUse this command to apply CRD (Custom Resource Definition) and deploy controllers on a Kubernetes cluster` Seata tl 'will use these definitions to complete the deployment of Seata.\n\n### Usage\n\n```\nseata-ctl\ninstall --namespace=default --image=apache/seata-controller:latest --name=seata-k8s-controller-manager\n```\n\n#### Arguments\n\n- `namespace`: Specifies the namespace to use (optional). If not specified, it defaults to `default`.\n- `image`: Specifies the name of the image to use (optional). If not specified, it defaults to `apache/seata-controller:latest`.\n- `name`: Specifies the name of the deployed controller (optional). If not specified, it defaults to `seata-k8s-controller-manager`.\n\n### Example\n\nIf the CRD is deployed successfully, a message will display: `create seata crd success`, indicating that a CRD named `seataservers.operator.seata.apache.org` has been deployed in the specified namespace.\n\nIf the Deployment is successful, a message will display: `Deployment created successfully`, indicating that a Deployment named `seata-k8s-controller-manager` has been created in the specified namespace, containing a single Pod.\n\n```\ninstall --namespace=default --image=apache/seata-controller:latest --name=seata-k8s-controller-manager\n\nINFO[0007] Create seata crd success                     \nINFO[0007] Deployment created successfully  \n```\n\nIf the CRD already exists, a message will display: `seata crd already exists`.\n\nIf the Deployment already exists, a message will display: `Deployment 'seata-k8s-controller-manager' already exists in the 'default' namespace`.\n\n```\ninstall --namespace=default --image=apache/seata-controller:latest --name=seata-k8s-controller-manager\n\nERRO[0001] install CRD err: failed to send post request: seata crd already exists \nERRO[0001] install Controller err: Deployment 'seata-k8s-controller-manager' already exists in the 'default' namespace \n```\n\n## Uninstall\n\n### Describe\n\nUse this command to uninstall the CRD and the controller.\n\n### Usage\n\n```\nseata-ctl\nuninstall --namespace=default --name=seata-k8s-controller-manager\n```\n\n#### Arguments\n\n- `namespace`: Specifies the namespace to use (optional). If not specified, it defaults to `default`.\n- `name`: Specifies the name of the deployed controller (optional). If not specified, it defaults to `seata-k8s-controller-manager`.\n\n### Example\n\nIf the CRD is deleted successfully, a message will display: `CRD seataservers.operator.seata.apache.org deleted successfully`. If the Deployment is deleted successfully, a message will display: `Deployment 'seata-k8s-controller-manager' deleted successfully from namespace 'default'`.\n\n```\nuninstall --namespace=default --name=seata-k8s-controller-manager\n\nINFO[0017] delete CRD seataservers.operator.seata.apache.org successfully. \nINFO[0017] deleted Controller seata-k8s-controller-manager successfully  \n```\n\nIf the CRD does not exist, a message will display: `CRD seataservers.operator.seata.apache.org does not exist, no action taken`. If the Deployment does not exist, a message will display: `Deployment 'seata-k8s-controller-manager' does not exist in namespace 'default', no action taken`.\n\n```\nuninstall --namespace=default --name=seata-k8s-controller-manager\n\nERRO[0005] CRD seataservers.operator.seata.apache.org does not exist, no action taken. \nERRO[0005] Deployment 'seata-k8s-controller-manager' does not exist in namespace 'default', no action taken. \n```\n\n## Deploy\n\n### Describe\n\nUse this command to deploy the Seata server on the Kubernetes cluster.\n\n### Usage\n\n```\nseata-ctl\ndeploy --name=test --replicas=1 --namespace=default --image=apache/seata-server:latest\n```\n\nAfter the CR is successfully deployed, the controller will automatically deploy the Seata server instance.\n\n\u003e **Note**: Since the specific namespace where the CRD and controller are installed is uncertain, the Deployment command will not check whether the CRD and controller have been successfully deployed. Before using this command, please ensure that the Seata CRD and controller have been successfully deployed in your cluster.\n\n#### Arguments\n\n- `namespace`: Specifies the namespace. If not specified, it defaults to `default`.\n- `replicas`: Number of deployment replicas. If not specified, it defaults to `1`.\n- `name`: Name of the CR. If not specified, it defaults to `example-seataserver`.\n- `image`: Specifies the name of the image to use (optional). If not specified, it defaults to `apache/seata-server:latest`.\n\n### Example\n\nIf the deployment is successful, a message will display: `CR install success, name: example-seataserver`.\n\n```\ndeploy --name=test --replicas=1 --namespace=default --image=apache/seata-server:latest\n\nINFO[0013] CR install success，name: test\n```\n\nIf the deployment already exists, a message will display: `This seata server already exists!`.\n\n```\ndeploy --name=test --replicas=1 --namespace=default --image=apache/seata-server:latest\n\nERRO[0007] deploy err:seata server already exist! name:test \n```\n\nIf the deployment fails, a message displaying the relevant error information will appear.\n\n```\ndeploy --name=test --replicas=1 --namespace=default --image=apache/seata-server:latest\n\nERRO[0065] deploy err:the server could not find the requested resource \n```\n\nIf this error occurs, it indicates that the CRD and controller were not successfully deployed. Please check your deployment status.\n\n## UnDeploy\n\n### Describe\n\nUse this command to uninstall the deployed Seata server.\n\n### Usage\n\n```\nseata-ctl\nundeploy --name=test --namespace=default\n```\n\nAfter deletion, the controller will automatically remove the Seata server instance.\n\n#### Arguments\n\n- `namespace`: Specifies the namespace. If not specified, it defaults to `default`.\n- `name`: Name of the CR. If not specified, it defaults to `example-seataserver`.\n\n### Example\n\nIf the uninstallation is successful, a message will display: `CR delete success, name: example-seataserver`, indicating that the CR has been successfully uninstalled, and the controller will automatically delete the Seata server from the cluster.\n\n```\nundeploy --name=test --namespace=default\n\nINFO[0308] CR delete success，name: test \n```\n\nIf the CR is not found, a message will display: `seataservers.operator.seata.apache.org \"example-seataserver\" not found`.\n\n```\nundeploy --name=test --namespace=default\n\nERRO[0290] undeploy error: seataservers.operator.seata.apache.org \"test\" not found \n```\n\nIf an exception occurs, the relevant error information will be displayed.\n\n```\nundeploy --name=test --namespace=default\n\nERRO[0284] undeploy error: the server could not find the requested resource \n```\n\nIf this error occurs, it indicates that the CRD and controller were not successfully deployed. Please check your deployment status.\n\n## Scale\n\n### Describe\n\nUse this command to modify the number of replicas for the deployed Seata server.\n\n### Usage\n\n```\nseata-ctl\n\nscale --name=test --replicas=2 --namespace=default\n```\n\nAfter the operation, the controller will automatically adjust the replica count, which may take some time.\n\n#### Arguments\n\n- `namespace`: Specifies the namespace. If not specified, it defaults to `default`.\n- `name`: Name of the CR. If not specified, it defaults to `example-seataserver`.\n- `replicas`: Number of deployment replicas. If not specified, it defaults to `1`.\n\n### Example\n\nIf the modification is successful, a message will display: `CR scale success, name: example-seataserver`, indicating that the CR has been successfully updated, and the controller will automatically adjust the number of Seata server replicas in the cluster.\n\n```\nscale --name=test --replicas=2 --namespace=default\n\nINFO[0070] CR scale success，name: test  \n```\n\nIf the CR is not found, a message will display: `This seata server does not exist!`.\n\n```\nscale --name=test --replicas=2 --namespace=default\n\nERRO[0058] scale err:This seata server does not exits！test \n```\n\n## Status\n\n### Describe\n\nUse this command to view the status of the deployed Seata server on the cluster.\n\n### Usage\n\n```\nseata-ctl\nstatus --name=example-seataserver --namespace=default\n```\n\n\u003e **Note**: This command essentially filters and displays Pods based on their labels. If Seata server Pods were created using other methods (for example, outside of the controller), the relevant Pods may not be found.\n\n#### Arguments\n\n`namespace`: Specifies the namespace. If not specified, it defaults to `default`.\n\n`name`: The name of the CR created when deploying the Seata server. If not specified, it defaults to `example-seataserver`.\n\n### Example\n\nIf everything is functioning correctly, a list of `seata-pods` will be displayed.\n\n```\nstatus --name=example-seataserver --namespace=default\n\nINFO[0319] status: POD NAME                  STATUS     \nINFO[0319] status: ------------------------------------------- \nINFO[0319] status: example-seataserver-0     Running    \n```\n\nIf no pods are found, an error message will be displayed.\n\n```\nstatus --name=example-seataserver1 --namespace=default\n\nERRO[0002] get k8s status error: no matching pods found \n```\n\n# Prometheus\n\nUse this command to display data retrieved from Prometheus.\n\nBefore using this command, you need to ensure that Prometheus is properly set up and is correctly collecting metrics from Seata.\n\n## Metrics\n\n### Describe\n\nUse this command to show the data retrieved from Prometheus.\n\n### Usage\n\n```\nseata-ctl\nmetrics --target=seata_transaction_summary  \n```\n\n#### Arguments\n\n- `target`: Specify the metric entry to query. This may vary depending on the system and version, so make sure it aligns with the metrics in Prometheus.\n\n### Example\n\nIf everything is functioning correctly, the relevant Prometheus metrics will be displayed in the form of a line chart.\n\n```\nmetrics --target=seata_transaction_summary\n\nINFO[0095]  10.00 ┼─────────╮\n  9.01 ┤         │\n  8.02 ┤         ╰╮\n  7.03 ┤          │\n  6.04 ┤          ╰╮\n  5.05 ┤           │\n  4.06 ┤           ╰╮\n  3.07 ┤            ╰╮\n  2.08 ┤             ╰─────────╮\n  1.09 ┤                       ╰───────────╮\n  0.10 ┤                                   ╰─────────────\n                    seata_transaction_summary \n```\n\nIf an error occurs, an error message will be displayed.\n\n```\nmetrics --target=seata_transaction_summary\n\nERRO[0093] Failed to show metrics: no data found for metric: seata_transaction_summary \n```\n\nThis error may indicate that the metric was not found. Please check your Prometheus metrics.\n\n# Log\n\nUse this command to view logs on Kubernetes, currently supporting ElasticSearch, Loki, and a custom-developed logging platform. Configuration files and query parameters vary between platforms.\n\n## Log\n\n### Describe\n\nUse this command to retrieve Seata logs from different logging platforms.\n\nBefore using this command, please ensure that your logging system is fully deployed and functioning properly.\n\n### Usage\n\n#### ElasticSearch\n\n```\nseata-ctl\n\nlog --label={stream=stderr}  --number=3\n```\n\nBefore using ES, you need to make the following configurations in the global configuration file. The meanings of the related parameters are as follows,An example of the configuration is as follows:\n\n```\n    - name: \"es\"  //name\n      types: \"ElasticSearch\"  //es type\n      address: \"https://localhost:9200\"   //es address\n      source: \"logstash-2024.10.24\"    //es index name\n      username: \"elastic\"   // es auth username\n      password: \"bu4AC50REtt_7rUqddMe\"  //es auth password\n      index: \"log\"\t//doc type\n```\n\n\u003e Note: Currently, only login with a username and password is supported for ES. If your ES has TLS encryption enabled, it is not supported at this time.\n\nNote: Currently, only login with a username and password is supported for ES. If your ES has TLS encryption enabled, it is not supported at this time.\n\nn the chart, the `index` field represents the output field for the final log display, which may vary across different index structures in ES.The source contains our index structure and the returned document content, but most of the fields are unnecessary for us. We use the index entry to select among these, and only the matching logs will be outputted.\n\nFor example, if the returned structure of our query is this:\n\n```\n{\n  \"took\": 2,\n  \"timed_out\": false,\n  \"_shards\": {\n    \"total\": 1,\n    \"successful\": 1,\n    \"skipped\": 0,\n    \"failed\": 0\n  },\n  \"hits\": {\n    \"total\": {\n      \"value\": 38,\n      \"relation\": \"eq\"\n    },\n    \"max_score\": 1.0,\n    \"hits\": [\n      {\n        \"_index\": \"logstash-2024.10.24\",\n        \"_id\": \"KyvwyJIB5EKHPP6lI9Os\",\n        \"_score\": 1.0,\n        \"_ignored\": [\"log.keyword\"],\n        \"_source\": {\n          \"@timestamp\": \"2024-10-24T17:39:45.771Z\",\n          \"log\": \"2024-10-24T17:39:45Z\\tINFO\\tCreating a new SeataServer Service {default:seata-server-cluster}\\t{\\\"controller\\\": \\\"seataserver\\\", \\\"controllerGroup\\\": \\\"operator.seata.apache.org\\\", \\\"controllerKind\\\": \\\"SeataServer\\\", \\\"SeataServer\\\": {\\\"name\\\":\\\"example-seataserver\\\",\\\"namespace\\\":\\\"default\\\"}, \\\"namespace\\\": \\\"default\\\", \\\"name\\\": \\\"example-seataserver\\\", \\\"reconcileID\\\": \\\"5912d1c4-6afd-4d66-8f11-eea6c54a1e4c\\\"}\\n\",\n          \"stream\": \"stderr\",\n          \"time\": \"2024-10-24T17:39:45.771071Z\",\n          \"kubernetes\": {\n            \"pod_name\": \"seata-k8s-controller-manager-6448b86796-6l46n\",\n            \"namespace_name\": \"default\",\n            \"pod_id\": \"966edd0e-bc15-4276-9e6a-e255e84859ce\",\n            \"labels\": {\n              \"app\": \"seata-k8s-controller-manager\",\n              \"pod-template-hash\": \"6448b86796\"\n            },\n            \"host\": \"minikube\",\n            \"container_name\": \"seata-k8s-controller-manager\",\n            \"docker_id\": \"b87df4627de30b0aab402aef4621fa46f45b3a1976dd6f466ab4a42bb8265455\",\n            \"container_hash\": \"bearslyricattack/seata-controller@sha256:84ddedd9fa63c4a3ab8aa3a5017065014826dc3a9cac8c8fff328fbf9c600f11\",\n            \"container_image\": \"bearslyricattack/seata-controller:latest\"\n          }\n        }\n      }\n    ]\n  }\n}\n\n```\n\nWe only need the logs related to the `log` field, so you can set `index` to `log`.\n\n##### Arguments\n\n- `label`: Specify the query entries in the format `{key1=value1, key2=value2, ...}`, where `key` is the name of the index in ES and `value` is the index's value. Neither the key nor the value requires quotation marks in the query.The default value is `{}`.\n- `number`: The number of log entries returned, with a default value of 10.\n\n\u003e Note: To accommodate different ES index structures, a preliminary index structure check will be conducted during log queries. If the index does not contain this structure, the query will not proceed and an error will be returned.\n\n#### Loki\n\n```\nseata-ctl\n\nlog --label={job=\"seata-transaction\"} --start=2025-10-18-14:21:21 --end=2025-10-18-22:16:14 --number=3\n```\n\nBefore using Loki, you also need to configure it in the configuration file.\n\n```\n    - name: \"loki\"  //loki name\n      types: \"Loki\"\t//type name\n      address: \"http://localhost:3100\"  //loki address\n      source: \"\"\n      username: \"\"\n      password: \"\"\n```\n\n##### Arguments\n\n- **query**: The label for the query, following the native format, e.g., `{job=\"seata-transaction\"}`, depending on the overall log format created.\n- **start**: Start time in UTC timezone, formatted as `2024-10-18-12:32:54`.\n- **end**: End time in UTC timezone, formatted as `2024-10-18-12:32:54`.\n- **number**: The number of log entries returned.\n\n#### Local\n\n```\nseata-ctl\n\nlog --level=INFO --number=5\n```\n\nSimilarly, to meet more diverse needs, we have developed a custom logging system for Seata applications on Kubernetes. This system will continue to evolve along with the Seata-K8s project.\n\nAt first,configure it in the configuration file.\n\n```\n    - name: \"local\" //name\n      types: \"Local\"  //type\n      address: \"http://localhost:8080\"  //address\n      source: \"seata\" //application\n      username: \"\"\n      password: \"\"\n      index: \"\"\n```\n\n### Example\n\n#### ElasticSearch\n\nIf everything is functioning correctly, the specified log entries will be returned.\n\n```\nlog --label={stream=stderr}  --number=3\n\nINFO[0015] 2024-10-24T17:39:45Z INFO    Creating a new SeataServer Service {default:seata-server-cluster}       {\"controller\": \"seataserver\", \"controllerGroup\": \"operator.seata.apache.org\", \"controllerKind\": \"SeataServer\", \"SeataServer\": {\"name\":\"example-seataserver\",\"namespace\":\"default\"}, \"namespace\": \"default\", \"name\": \"example-seataserver\", \"reconcileID\": \"5912d1c4-6afd-4d66-8f11-eea6c54a1e4c\"} \nINFO[0015] 2024-10-24T17:39:45Z INFO    Creating a new SeataServer StatefulSet {default:example-seataserver}    {\"controller\": \"seataserver\", \"controllerGroup\": \"operator.seata.apache.org\", \"controllerKind\": \"SeataServer\", \"SeataServer\": {\"name\":\"example-seataserver\",\"namespace\":\"default\"}, \"namespace\": \"default\", \"name\": \"example-seataserver\", \"reconcileID\": \"5912d1c4-6afd-4d66-8f11-eea6c54a1e4c\"} \nINFO[0015] 2024-10-24T17:39:45Z INFO    SeataServer(default/example-seataserver) has not been synchronized yet, requeue in 10 seconds   {\"controller\": \"seataserver\", \"controllerGroup\": \"operator.seata.apache.org\", \"controllerKind\": \"SeataServer\", \"SeataServer\": {\"name\":\"example-seataserver\",\"namespace\":\"default\"}, \"namespace\": \"default\", \"name\": \"example-seataserver\", \"reconcileID\": \"5912d1c4-6afd-4d66-8f11-eea6c54a1e4c\"} \n```\n\nIf the index does not exist, an error message will be displayed.\n\n```\nlog --label={stream1111=stderr}  --number=3\n\nERRO[0001] get log error: invalid index key: stream1111 \n```\n\nIf no documents are found, an error indicating \"no results found\" will be returned.\n\n```\nlog --label={stream=stderr11}  --number=3\n\nERRO[0060] get log error: no documents found     \n```\n\nIf any other errors occur, an error message will be displayed.\n\n#### Loki\n\nIf everything is functioning correctly, the specified log entries will be returned.\n\n```\nlog --label={job=\"seata-transaction\"} --start=2024-10-18-14:21:21 --end=2024-10-18-22:16:14 --number=2\n\nINFO[0098] 2023-10-17 14:15:23.363 INFO  [TransactionManager] --- Transaction [XID: 172.16.20.1:8091:123456789] ends with SUCCESS. \nINFO[0098] 2023-10-17 14:15:23.360 INFO  [RMHandler] --- Transaction resource committed successfully: ResourceId: jdbc:mysql://localhost:3306/seata_test, XID: 172.16.20.1:8091:123456789 \n```\n\nIf no documents are found, an error indicating \"no results found\" will be returned.\n\n```\nlog --label={job=\"seata-transaction\"} --start=2025-10-18-14:21:21 --end=2025-10-18-22:16:14 --number=3\n\nERRO[0058] get log error: loki query returned no results \n```\n\nIf any other errors occur, an error message will be displayed.\n\n#### Local\n\nIf everything is functioning correctly, the specified log entries will be returned.\n\n```\nlog --level=INFO --number=5\n\nPeer example-seataserver-2.seata-server-cluster:9091 is connected\nPeer example-seataserver-1.seata-server-cluster:9091 is connected\nNode \u003cdefault/example-seataserver-0.seata-server-cluster:9091\u003e term 4 start preVote.\nPeer example-seataserver-2.seata-server-cluster:9091 is connected\nPeer example-seataserver-1.seata-server-cluster:9091 is connected\n```\n\nIf any other errors occur, an error message will be displayed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fincubator-seata-ctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Fincubator-seata-ctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fincubator-seata-ctl/lists"}