README

Dot

The dot module generates a DOT file representation of a dependency graph.

Interpreting the graph

The graph should be read from left to right. The leftmost node in the graph (the root node) depends on its dependency tree to the right. An arrow from node_a to node_b in the graph means that node_b is consumed by node_a and that node_b is a parameter of node_a. The rendered graph holds the following kinds of nodes,

Nodes:

  • Constructors [Rectangles]: Takes parameters and produces results.
  • Results [Ovals]: Results inside a constructor are produced by that constructor. Results are consumed directly by other constructors and/or part of a group of results.
  • Groups [Diamonds]: Represent value groups in fx. Multiple results can form a group. Any result linked to a group by an edge are members of that group. A group is a collection of results. Groups can also be parameters of constructors.

Edges:

  • Solid Arrows: An arrow from node_a to node_b means that node_b is a parameter of node_a and that node_a depends on node_b.
  • Dashed Arrows: A dashed arrow from node_a to node_b represents an optional dependency that node_a has on node_b.

Graph Colors:

  • Red: Graph nodes are the root cause failures.
  • Orange: Graph nodes are the transitive failures.

Testing and verifying changes

Unit tests and visualize golden tests are run with

$ make test

You can visualize the effect of your code changes by visualizing generated test graphs as pngs.

In the dig root directory, generate the graph DOT files with respect to your latest code changes.

$ go test -generate

Assuming that you have graphviz installed and are in the testdata directory, generate a png image representation of a graph for viewing.

$ dot -Tpng ${name_of_dot_file_in_testdata}.dot -o ${name_of_dot_file_in_testdata}.png
$ open ${name_of_dot_file_in_testdata}.png

Graph Pruning

If dot.Visualize is used to visualize an error graph, non-failing nodes are pruned out of the graph to make the error graph more readable to the user. Pruning increases readability since successful nodes clutter the graph and do not help the user debug errors.

Expand ▾ Collapse ▴

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Ctor

type Ctor struct {
	Name        string
	Package     string
	File        string
	Line        int
	ID          CtorID
	Params      []*Param
	GroupParams []*Group
	Results     []*Result
	ErrorType   ErrorType
}

    Ctor encodes a constructor provided to the container for the DOT graph.

    type CtorID

    type CtorID uintptr

      CtorID is a unique numeric identifier for constructors.

      type ErrorType

      type ErrorType int

        ErrorType of a constructor or group is updated when they fail to build.

        func (ErrorType) Color

        func (s ErrorType) Color() string

          Color returns the color representation of each ErrorType.

          type FailedNodes

          type FailedNodes struct {
          	// RootCauses is a list of the point of failures. They are the root causes
          	// of failed invokes and can be either missing types (not provided) or
          	// error types (error providing).
          	RootCauses []*Result
          
          	// TransitiveFailures is the list of nodes that failed to build due to
          	// missing/failed dependencies.
          	TransitiveFailures []*Result
          	// contains filtered or unexported fields
          }

            FailedNodes is the nodes that failed in the graph.

            type Graph

            type Graph struct {
            	Ctors []*Ctor
            
            	Groups []*Group
            
            	Failed *FailedNodes
            	// contains filtered or unexported fields
            }

              Graph is the DOT-format graph in a Container.

              func NewGraph

              func NewGraph() *Graph

                NewGraph creates an empty graph.

                func (*Graph) AddCtor

                func (dg *Graph) AddCtor(c *Ctor, paramList []*Param, resultList []*Result)

                  AddCtor adds the constructor with paramList and resultList into the graph.

                  func (*Graph) AddMissingNodes

                  func (dg *Graph) AddMissingNodes(results []*Result)

                    AddMissingNodes adds missing nodes to the list of failed Results in the graph.

                    func (*Graph) FailGroupNodes

                    func (dg *Graph) FailGroupNodes(name string, t reflect.Type, id CtorID)

                      FailGroupNodes finds and adds the failed grouped nodes to the list of failed Results in the graph, and updates the state of the group and constructor with the given id accordingly.

                      func (*Graph) FailNodes

                      func (dg *Graph) FailNodes(results []*Result, id CtorID)

                        FailNodes adds results to the list of failed Results in the graph, and updates the state of the constructor with the given id accordingly.

                        func (*Graph) PruneSuccess

                        func (dg *Graph) PruneSuccess()

                          PruneSuccess removes elements from the graph that do not have failed results. Removing elements that do not have failing results makes the graph easier to debug, since non-failing nodes and edges can clutter the graph and don't help the user debug.

                          type Group

                          type Group struct {
                          	// Type is the type of values in the group.
                          	Type      reflect.Type
                          	Name      string
                          	Results   []*Result
                          	ErrorType ErrorType
                          }

                            Group is a group node in the graph. Group represents an fx value group.

                            func NewGroup

                            func NewGroup(k nodeKey) *Group

                              NewGroup creates a new group with information in the groupKey.

                              func (*Group) Attributes

                              func (g *Group) Attributes() string

                                Attributes composes and returns a string of the Group node's attributes.

                                func (*Group) String

                                func (g *Group) String() string

                                  String implements fmt.Stringer for Group.

                                  type Node

                                  type Node struct {
                                  	Type  reflect.Type
                                  	Name  string
                                  	Group string
                                  }

                                    Node is a single node in a graph and is embedded into Params and Results.

                                    type Param

                                    type Param struct {
                                    	*Node
                                    
                                    	Optional bool
                                    }

                                      Param is a parameter node in the graph. Parameters are the input to constructors.

                                      func (*Param) String

                                      func (p *Param) String() string

                                        String implements fmt.Stringer for Param.

                                        type Result

                                        type Result struct {
                                        	*Node
                                        
                                        	// GroupIndex is added to differentiate grouped values from one another.
                                        	// Since grouped values have the same type and group, their Node / string
                                        	// representations are the same so we need indices to uniquely identify
                                        	// the values.
                                        	GroupIndex int
                                        }

                                          Result is a result node in the graph. Results are the output of constructors.

                                          func (*Result) Attributes

                                          func (r *Result) Attributes() string

                                            Attributes composes and returns a string of the Result node's attributes.

                                            func (*Result) String

                                            func (r *Result) String() string

                                              String implements fmt.Stringer for Result.

                                              Source Files