seamia / protodot Goto Github PK

View Code? Open in Web Editor NEW

386.0 8.0 39.0 48.33 MB

transforming your .proto files into .dot files (and .svg, .png if you happen to have graphviz installed)

License: BSD 3-Clause "New" or "Revised" License

Go 100.00%

visualization protobuf protocol-buffers protoc proto3 grpc graphviz-dot-language dot graphviz graph

protodot's Introduction

protodot

transforming your .proto files into .dot files (and .svg, .png if you happen to have graphviz installed)

online demo

you can find an online demo of this tool here

data pipeline

installation

you can download the sources (from this page) and build protodot yourself, or you can download pre-built binaries for a few selected environments (or from here):

Darwin (x86, arm)
Linux
Wasm
Windows

protodot output is highly customizable through its configuration file and a set of templates files. if you installed protodot from the binary distribution - you may want to extract aforementioned files by running:

   ./protodot -install

command line arguments

-src what.proto - location and name of the source file, required
-config config.json - location and name of the configuration file, optional
-select .one.two;three.four - name(s) of the selected elements to show, optional, explained later in this document
-output save-it-here - name of the output file, optional
-inc /abc/def;/xyz - (semicolon separated) list of the include directories, optional

configuration file

tbd

selected output

sometimes the resulting diagram can be overwhelming. you have an option to limit the output to the elements that interest you the most, hence -select args command line option. so far, args in -select args can take one of the three available forms:

list of the elements (and their dependencies) that you want to see included (separated by ;). the elements can be enums, messages, rpc methods and services.
if you specify * as an argument - this will result in the inclusion of the elements declared in the main .proto file (specified in -src argument) and their dependencies. in other words: all the unused elements declared in all the included .proto files will not be shown.
if you specify imports as an argument - protodot will generate import dependency graph (see an example below)

an example of output

an illustration of effects of different `-select` options

using https://github.com/googleapis/googleapis/blob/master/google/privacy/dlp/v2/dlp.proto as the source

not using `-select`

everything declared in the root .proto file and all the imports will be produced:

using `-select *`

only elements declared in the root .proto file and their dependencies will be produced:

using `-select imports`

only imports dependency graph will be produced:

using `-select .ListDlpJobs`

in this particular case, the name of the rpc method was specified: this will result in production of the requested rpc method, it's encompasing service element and all the dependencied of the method:

using `-select .AnalyzeDataSourceRiskDetails`

same as above, but instead of rpc method, name of the message was specified:

how to (automatically) generate `.svg` and/or `.png` images from produced `.dot` file

install graphviz (see https://graphviz.gitlab.io/download/ for the instructions)
specify the location of the dot utility (which is a part of graphviz) in your version of configuration file, e.g.

{
	"locations": {
		"graphviz":	"/path/to/dot",

set approptiate options in your version of configuration file, e.g.

{
	"options" : {
		"generate .png file":		false,
		"generate .svg file":		true,

protodot's People

Contributors

Stargazers

Watchers

protodot's Issues

How to change colors?

This project is really awesome, but I'd like to change the colors to something a bit easier to read. In config.json there are a bunch of colors listed, but I have no idea where the listed colors come from or how to specify new colors by hex value. I tried "#8888ff" and "8888ff", but neither way worked. Any documentation or advice would be appreciated. Thanks!

Website is down

https://protodot.seamia.net/ is down, when I tried to download this "looking some awesome" project. Can you bring it up?

Default config should be search in protodot/config.json

There should be a default path list for the config present, such as in config.hson and if not found then protodot/config.json, etc. Specifying it each time does not make sense.

Adding annotations to the dot/svg files

Hi, many thanks for this superb project.
I feel that people might benefit from having the option to also include proto annotations in generated dot/svg files.
I would like to work on that and contribute back, but I am not a Go programmer and finding it a challenge to unravel where to start inspecting the code to add the same functionality.

Is it possible for you to point me to where the functionality for adding name/datatype of the field lives in the code base, so I can start experimenting?

So much better if a feature like this is already in the works.

Thanks!

Failed to load template file(s)

After the last change/commit, we get an error message that it cannot find the template files.

Error msg for proto file 1:
failed to load templates file [templates/oneof_entry_suffix.tmpl] not found

Error msg for proto file 2:
failed to load templates file [templates/enum_suffix.tmpl] not found

Command used:
protodot -config ../protodot.json -inc /usr/include -src *.proto -select AnyService -output AnyService

Broken image links in README.md

It looks like https://camo.githubusercontent.com/ is gone, so all the image links are broken. However, the images could be served from the repo itself.

Specify output directory from command line

Great tool, I really like it.
The only thing missing I think is to overwrite the output directory from command line.
I am a developer myself, but I have zero experience with GO, or else I would simply put in a pull request.
Regards, Reinhard.

How to add a target path for output file?

Hello, I tried with -output option with "home/put/it/here/target", but I got an error.

How to do this? Thanks!

consistent output

Is there a way to get consistent (or nearly consistent) comparable output?

My specific use case is that we have protobufs, and expect to have the graph files checked into the repo as part of the commit. The simplest way to do this (we do it for generated language bindings) is to run protodot, and check if the file is different from what is checked in.

Except the output isn't consistent.

From my checks, I found several things:

date for generated by comment at the end; we can ignore that
subgraph cluster_<id>: the ID appears to be generated using some data about the content. As far as I can tell, this is consistent
node names, e.g. Node_Ja_<number>: the numbers appear to be consistent with the content in them
subgraph sort order: this appears to be one major source of discontinuity
node sort order within a subgraph: this appears to be another major source of discontinuity

I don't know the internals of protodot well enough, but it looks like consistent sorting of the subgraphs and nodes within subgraph might go a long way?

Assert: *** Failed to process file json data, error: invalid character '}' looking for beginning of object key string

I just downloaded the program and created a basic config file. I also installed Graphviz. Following are the details:

Command:
protodot.exe -src protoFileName.proto

config.json:

{
	"locations": {
		"graphviz": "C:\\Program Files\\Graphviz 2.44.1\\bin"
	},
	"options": {
		"generate .png file": true,
		"generate .svg file": false,
	}
}

Error message:

Assert: *** Failed to process file json data, error: invalid character '}' looking for beginning of object key string
Error: failed to load config file

Misleading error about includes

In a run I found this which was fixed once I downloaded the google apis and stored then in the includes list then it started working:

*** failed to find file [ google/api/annotations.proto ] with root [ /Users/...REMOVED... ]
*** failed to find file [ google/protobuf/struct.proto ] with root [ /Users/...REMOVED... ]
*** failed to find file [ google/protobuf/any.proto ] with root [ /Users/...REMOVED... ]
ASSERT: Unresolved type:  google.protobuf.Any ; source:  our.own.Dependency

The default config.json includes does not work, the folder "${HOME}/protodot/protoc-3.6.0/include" was not in that location, even not after running protodot -install. The README.md should be updated to give some instructions to put the base proto files there.

Built the executable from code on MacOS.

Add comments from the .proto files to the output graph

Hi!
It would be super-useful for me if comments I leave above fields in protobuf will carry over to the .dot (and .svg) file. Any way to make this happen? Would love to help with guidance

Feature Request: Exclude missing nodes

I have a repository of protobuf files that use some basic types from another repo which is not available at the time when I am generating graphs. StringUtf8Value, BoolValue, ResourceName, that kind of thing. I really don't need them graphed.

I would like to exclude the diagramming of missing nodes as it clutters the output just pointing to a Node that says "this type is missing"

Thanks for your consideration, I love this tool it really helps to map things out in my mind.

seamia / protodot Goto Github PK

protodot's Introduction

protodot

online demo

data pipeline

installation

command line arguments

configuration file

selected output

an example of output

an illustration of effects of different -select options

not using -select

using -select *

using -select imports

using -select .ListDlpJobs

using -select .AnalyzeDataSourceRiskDetails

how to (automatically) generate .svg and/or .png images from produced .dot file