{"id":13408816,"url":"https://github.com/ChrisKujawa/zdb","last_synced_at":"2025-03-14T13:32:06.239Z","repository":{"id":37719454,"uuid":"286702661","full_name":"ChrisKujawa/zdb","owner":"ChrisKujawa","description":"Zeebe debug and inspection tool","archived":false,"fork":false,"pushed_at":"2024-09-20T07:44:04.000Z","size":1906,"stargazers_count":24,"open_issues_count":10,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-21T21:44:49.765Z","etag":null,"topics":["cli","debug","debugging","incident","inspection","zeebe"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChrisKujawa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"licenses/APACHE-2.0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-11T09:30:36.000Z","updated_at":"2024-09-02T12:55:44.000Z","dependencies_parsed_at":"2023-02-10T08:30:33.192Z","dependency_job_id":"f3a8d613-9a07-42ab-b3c8-c90c76c3f0b7","html_url":"https://github.com/ChrisKujawa/zdb","commit_stats":null,"previous_names":["chriskujawa/zdb"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisKujawa%2Fzdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisKujawa%2Fzdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisKujawa%2Fzdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisKujawa%2Fzdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChrisKujawa","download_url":"https://codeload.github.com/ChrisKujawa/zdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243584475,"owners_count":20314770,"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":["cli","debug","debugging","incident","inspection","zeebe"],"created_at":"2024-07-30T20:00:55.459Z","updated_at":"2025-03-14T13:32:06.229Z","avatar_url":"https://github.com/ChrisKujawa.png","language":"Java","funding_links":[],"categories":["Others"],"sub_categories":[],"readme":"# Zeebe Debug and Inspection tool\n\nThis repository contains a cli tool to inspect the internal state and log of a Zeebe partition. It is a Java (21) cli application and can be build via maven.\nIt was kicked off during the Camunda Summer Hackdays in 2020 and has been maintained and developed since then.\n\nThe following Zeebe versions are supported: [8.1,8.2,8.3,8.4,8.5,8.6,SNAPSHOT]\n\n## Table Of Contents\n\n* [What problem does it solve](#what-problem-does-it-solve)\n* [Usage](#usage)\n* [How does it solve it](#how-does-it-solve-it)\n  * [State Inspection](#state-inspection)\n    * [Inspect Zeebe Partition Status](#inspect-zeebe-partition-status)\n    * [Inspect Incidents](#inspect-incidents)\n    * [Inspect Processes](#inspect-processes)\n    * [Inspect Instances](#inspect-instances)\n  * [Log Inspection](#log-inspection)\n    * [Inspect Log Status](#inspect-log-status)\n    * [Inspect Log Consistency](#inspect-log-consistency)\n    * [Inspect Log](#inspect-log)\n    * [Print Log](#print-log)\n * [Autocompletion](#autocompletion)\n\n## What problem does it solve\n\nWhen Zeebe is broken there is currently no possibility to find out the last state of Zeebe.\nIf there was no exporter configured or they haven't exported for a while it gets even worse, since it is not clear what the internal engine state is.\n\nTo shed some more light in the dark we build a tool called zdb - Zeebe Debugger. It should help you along the way during incidents and broken systems.\n\n\n## Usage\n\n\u003e **Note:**\n\u003e To be on the safe side make sure to copy Zeebe data to a separate location, to not mess with a running Zeebe process and mistakingly corrupt any data.\n\n### Docker\n\nIf you have copied data from Zeebe to your local machine you could run the following:\n\n```\n docker run -v \u003cpath\u003e/\u003cpartitionId\u003e/:/\u003cpartitionId\u003e/ ghcr.io/zelldon/zdb log print -p \"/\u003cpartitionId\u003e\"\n```\n\n### Kubernetes\n\n\u003e [!Important]\n\u003e\n\u003e This approach doesn't work anymore with 8.3+ and non-root containers. See related issue https://github.com/Zelldon/zdb/issues/332\n\nIf have Zeebe installed in Kubernetes and want to investigate the Zeebe data you can run `zdb` as an [ephemeral container](https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/)\n\n```\nkubectl debug -it -c zdb --image=ghcr.io/zelldon/zdb:latest --attach=true --target=zeebe zeebe-0 -- /bin/bash\n```\n\n### Local CLI\n\nAlternatively to the strategies above you can download the fat-jar and script and run that locally\n\n```bash\ncd /usr/bin\ncurl -O -L https://github.com/Zelldon/zdb/releases/latest/download/zdb\ncurl -O -L https://github.com/Zelldon/zdb/releases/latest/download/zdb.jar\nsed -i 's/target\\///' zdb\nchmod u+x zdb\nzdb --version\n```\n\n## How does it solve it\n\nUsing `zdb` you can inspect the internal state or the partition log.\n\n### State Inspection\n\nUsing `zdb` you can inspect the internal `runtime` data or a snapshot.\nIt shows some information about the current state, incidents, processes, and so on from a single partition.\nTo inspect the database you should provide the path to the `raft-partition/partitions/../runtime/` folder in a partition or one of the snapshot folders `raft-partition/partitions/../snapshot/\u003csnapshot-folder\u003e`\n\nYou then can run several commands to inspect the given state.\n\n#### Inspect Zeebe Partition Status\n\nShows the general information of a Zeebe partition. It will show you a statistic (counts) for each existing column family in the state.\n\n```sh\nzdb state --path=\u003cpathToDatabase\u003e\n```\n\nFurthermore, the complete state can be printed as json via the `list` sub-command.\n\n\n```sh\nzdb state list --path=\u003cpathToDatabase\u003e\n```\n\nThis can be more fine-tuned and a specific column family can be given, such that only key-value pairs are printed to the console.\n\nFor example, to see all processes\n\n```\n$ zdb state --path=\u003cpathToDatabase\u003e list -cf PROCESS_CACHE\n```\n\n#### Inspect incidents\n\nYou can inspect incidents using the following commands.\n\nList all incidents in this partition:\n\n```sh\nzdb incident list --path=\u003cpathToDatabase\u003e\n```\n\nReturns detail to a specific incident:\n\n```sh\nzdb incident entity \u003cIncidentKey\u003e --path=\u003cpathToDatabase\u003e\n```\n\nFind incidents for a given processInstanceKey\n\n```sh\nzdb incident list --path=\u003cpathToDatabase\u003e | jq '. | map(select(.processInstanceKey==\u003cPI_KEY\u003e))'\n```\n\n#### Inspect Banned Process Instances\n\nYou can check if there are any processes stuck due to banning using the following commands.\n\nList all banned process instances in this partition:\n\n```sh\nzdb banned list --path=\u003cpathToDatabase\u003e\n```\n\nReturns details to a specific banned instance:\n\n```sh\nzdb banned entity \u003cProcessInstanceKey\u003e --path=\u003cpathToDatabase\u003e\n```\n\n#### Inspect Processes\nYou can inspect all deployed processes and get the resources of a specific process.\n\nList all deployed processes in this partition:\n\n```sh\nzdb process list --path=\u003cpathToDatabase\u003e\n```\n\nReturns details to a specific process:\n```sh\nzdb process entity \u003cProcessKey\u003e --path=\u003cpathToDatabase\u003e\n```\n\nList all element instances for the given process:\n\n```sh\nzdb process --path=\u003cpathToDatabase\u003e instances \u003cProcessKey\u003e\n```\n\n#### Inspect Instances\n\nYou can inspect existing element instances and get details viewed of there state.\n\nPrint all information to a given element instance:\n\n```sh\nzdb instance --path=\u003cpathToDatabase\u003e entity \u003celementInstanceKey\u003e\n```\n\n#### Inspect state (generic)\n\nThere is a new (experimental) feature to inspect the state on a generic way with the `state` subcommand. You can either \nprint the complete state as json or specify a specific column family (used in Zeebe).\n\nExample to see all processes\n\n```\n$ zdb state --path=\u003cpathToDatabase\u003e list -cf PROCESS_CACHE\n```\n\n### Log Inspection\n\nYou can also inspect the log stream using the command `zdb log` and his subcommands.\nTo inspect the log you should provide the path to a specific partition `raft-partition/partitions/\u003cpartition-id\u003e/`.\n\n#### Inspect Log Status\n\nShows the general information of a Zeebe partition log, e. g. how many indexes, max. entry size, avg. entry size etc.\n\n```sh\nzdb log status --path=\u003cpathToPartition\u003e\n```\n\n#### Inspect Log\n\nIt is possible to inspect the log in more detail and search for a specific index **OR** position.\n\nTo search for a record position use:\n\n```sh\nzdb log search --path=\u003cpathToPartition\u003e --position=\u003cposition\u003e\n```\nIt will print all related information to the record, when it exists in the log.\n\n\nTo search for an index use:\n\n```sh\nzdb log search --path=\u003cpathToPartition\u003e --index=\u003cposition\u003e\n```\n\nIt will print a details to the specific index, when it exists in the log.\n\n#### Print Log\n\nIt is possible to print the complete log to standard out. This can be quite helpful if you want to track down some records, which might have caused some issues. \n\nTo print the log:\n\n```sh\nzdb log print --path=\u003cpathToPartition\u003e\n```\n\nPer default, the log is printed in JSON format.\nTo pipe it to a file:\n\n```sh\nzdb log print --path=\u003cpathToPartition\u003e \u003e output.log\n```\nThe `output.log` file will contain all records as JSON.\n\n##### Limit\n\nYou can limit the printed log via the options `--to` and `--from`.\n\nI you want to skip the first records or X positions you can use `zdb log print --path=\u003cpathToPartition\u003e --from X` whereas X must be a long.\n\nFor defining a limit of the print (like until which position the log should be printed) you can use `--to` like this `zdb log print --path=\u003cpathToPartition\u003e --to X` whereas X must be a long.\n\n##### Filter\n\nAn interesting use case is to print only certain records, for example for only specific process instances. \n\nYou can filter the printed log via: `--instanceKey`\n\n```sh\n zdb log print -p \u003cpathToPartition\u003e --instanceKey 2251799813686738\n```\n\n##### Format\n\nWe support different formats to print the log, like json, table or dot. The json format is used per default. Can be set via `-f` or `--format`\n\n**Table**\n\n```\nzdb log print --format TABLE --path=\u003cpathToPartition\u003e\n```\n\nThe `table` format will print the complete log as space separated table. This can be consumed by other csv tools.\n\nExample:\n\n```sh\nIndex Term Position SourceRecordPosition Timestamp Key RecordType ValueType Intent ProcessInstanceKey BPMNElementType \n836304301 304 6888891257 6888891180 1692869671126 2251802375814765 COMMAND PROCESS_INSTANCE ACTIVATE_ELEMENT 2251802375814765 PROCESS \n836304301 304 6888891258 6888891180 1692869671126 2251802375814770 EVENT PROCESS_INSTANCE_CREATION CREATED 2251802375814765 \n836304301 304 6888891259 6888891180 1692869671126 2251802375814765 EVENT PROCESS_INSTANCE ELEMENT_ACTIVATING 2251802375814765 PROCESS \n836304301 304 6888891260 6888891180 1692869671126 2251802375814765 EVENT PROCESS_INSTANCE ELEMENT_ACTIVATED 2251802375814765 PROCESS \n```\n\n**Dot**\n\n```\nzdb log print -f dot -p=\u003cpathToPartition\u003e\n```\n\nThe `dot` format will print the complete log as graph in [dot language](https://graphviz.org/doc/info/lang.html). This can be consumed by [graphviz](https://graphviz.org/doc/info/command.html) to generate a visual graph of the log.\n\n\nGenerate dot file via:\n`zdb log print -d -p \u003cpathToPartition\u003e \u003e output.dot`\n\nGenerate svg:\n`dot -Tsvg -o test.svg test.dot`\n\n![test](https://user-images.githubusercontent.com/2758593/156778874-1c1fb44a-e18c-4cac-b226-6052241ebdc8.svg)\n\n\n## Examples\n\n**Details of a specific column family**\n```sh\nzdb state list -p $PATH -cf EXPORTER | jq\n{\n  \"data\": [\n    {\n      \"cf\": \"EXPORTER\",\n      \"key\": \"00 00 00 00 00 00 00 28 00 00 00 0d 65 6c 61 73 74 69 63 73 65 61 72 63 68\",\n      \"value\": {\n        \"exporterPosition\": 619675,\n        \"exporterMetadata\": \"eyJyZWNvcmRDb3VudGVyc0J5VmFsdWVUeXBlIjp7IkRFUExPWU1FTlQiOjE0LCJQUk9DRVNTX0lOU1RBTkNFIjo1ODcsIklOQ0lERU5UIjo1LCJNRVNTQUdFIjo3OSwiTUVTU0FHRV9TVUJTQ1JJUFRJT04iOjM5LCJQUk9DRVNTX01FU1NBR0VfU1VCU0NSSVBUSU9OIjoxNDksIk1FU1NBR0VfU1RBUlRfRVZFTlRfU1VCU0NSSVBUSU9OIjozNywiVkFSSUFCTEUiOjE5NywiUFJPQ0VTU19JTlNUQU5DRV9DUkVBVElPTiI6MSwiUFJPQ0VTUyI6MTMsIkNPTU1BTkRfRElTVFJJQlVUSU9OIjo4NH19\"\n      }\n    },\n    {\n      \"cf\": \"EXPORTER\",\n      \"key\": \"00 00 00 00 00 00 00 28 00 00 00 0f 4d 65 74 72 69 63 73 45 78 70 6f 72 74 65 72\",\n      \"value\": {\n        \"exporterPosition\": 619676,\n        \"exporterMetadata\": \"\"\n      }\n    }\n  ]\n}\n```\n\n**Retrieve a process model**\n\n```\n$ zdb state --path=\u003cpathToDatabase\u003e list -cf PROCESS_CACHE | jq --raw-output '.data[0].value.resource' | base64 -d \u003e model.bpmn\n```\n\n## Autocompletion\n`zdb` comes with autocompletion. Just print it to a file:\n\n```sh\nzdb generate-completion \u003e\u003e ~/.autocompletions/zdb\n```\n\nand source that file in your shell profile (i.e. `.bash_rc`, `.zsh_rc`, `.bash_profile`, etc.):\n```sh\nsource \u003c(cat $HOME/.autocompletions/zdb)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChrisKujawa%2Fzdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FChrisKujawa%2Fzdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChrisKujawa%2Fzdb/lists"}