Mule flow call graphs and diagrams
MIT License
= Mule Flow Diagrams [mulefd] ifndef::env-github[:icons: font] ifdef::env-github[] :caution-caption: 🔥 :important-caption: ❗ :note-caption: 📎 :tip-caption: 💡 :warning-caption: ⚠️ endif::[] :toc: macro
image:https://img.shields.io/github/downloads/manikmagar/mulefd/total[GitHub all releases] image:https://img.shields.io/github/release/manikmagar/mulefd.svg[Release,link=https://github.com/manikmagar/mulefd/releases] image:https://github.com/manikmagar/mulefd/workflows/ci-build/badge.svg[Build Status,link=https://github.com/manikmagar/mulefd/actions] image:https://sonarcloud.io/api/project_badges/measure?project=manikmagar_mulefd&metric=vulnerabilities[SonarCloud Vulnerability] image:https://sonarcloud.io/api/project_badges/measure?project=manikmagar_mulefd&metric=alert_status[SonarCloud Quality] image:https://img.shields.io/docker/v/manikmagar/mulefd?color=blue&label=docker%20image&sort=semver[Docker Image Version (latest semver)] image:https://img.shields.io/github/license/manikmagar/mulefd[GitHub]
toc::[]
== Introduction Mule application can contain multiple flows and sub-flows. All these can reference each other for processing messages. Data can also be exchanged synchronously or asynchronously using connectors.
A project can easily have multiple configuration files with flows/sub-flows that are spread across those files. When analyzing mule application, it could be difficult to see the complete data processing flow and their dependencies.
Have you ever wished to visualize your flow dependencies? How does message flows through your application?
If so, then try this mulefd
application. It can read your configuration files and generate a diagrams that can easily tell you how your flows are connected.
$ mulefd mulefd is a tool to generate beautiful diagrams for your mule application flows. Usage: mulefd [-hV] [COMMAND]
Some command examples:
-h, --help display this help message -V, --version display version info Commands: help Displays help information about the specified command version Display version info graph Create beautiful graph diagrams for mule flows config Manage MuleFD Global configuration
For an example mule configuration link:./itests/test-hello-app.xml[./itests/test-hello-app.xml], run following command to generate a flow diagram -
image::./itests/output/mule-diagram.png[Mule flow diagrams]
== Features
== Requirements At the minimum, Java 8 is required. The build pipeline also tests it against JDK 11+.
Tested and verified to use on OSX, Linux and Windows.
=== Graphviz Engine This tool uses Graphviz Engine to generate Graph diagrams. It will use the first available engine, in following order -
== Installation
=== SDKMan icon:linux[] icon:apple[]
Recommended way to install both java and Mule flow diagrams is https://sdkman.io[sdkman] for Linux and OSX.
curl -s "https://get.sdkman.io" | bash source "$HOME/.sdkman/bin/sdkman-init.sh"
Once Java is installed and ready, you install Mule Flow Diagrams -
To test your installation run:
This should print out usage information.
For upgrading existing installations via SDKMAN,run:
=== Homebrew icon:apple[]
On OSX you can install 'java' and mulefd
with https://brew.sh[Homebrew] using custom taps.
To install Java 8:
Once Java is installed you can use brew with https://github.com/manikmagar/homebrew-tap/[manikmagar/tap] to get mulefd
:
brew install manikmagar/tap/mulefd
To upgrade to the latest version:
brew upgrade manikmagar/tap/mulefd
Test running mulefd help
in CLI.
=== Docker icon:docker[]
If you don't want to install mulefd
, you can run it via docker.
pwd
:/app manikmagar/mulefd /appThis will generate diagrams in pwd
or mounted directory.
Docker container resources are limited. Based on the size of your application, you may see outofmemory errors when executing with docker. You can allocate more memory with -m
option to docker run command, Eg. -m 512m
.
=== Scoop icon:windows[]
On Windows, you can install mulefd
using https://scoop.sh[Scoop] - A command-line installer for Windows.
Once you have Scoop installed and JDK configured, you can run following commands to get mulefd
-
To upgrade, you can run -
=== Manual install icon:apple[] icon:windows[] icon:linux[]
. Unzip the https://github.com/manikmagar/mulefd/releases/latest[latest binary release].
. Add mulefd-<version>/bin
folder in to your $PATH
. Test running mulefd help
in CLI.
=== Running with JBang
You can run MuleFD using https://jbang.dev[JBang]. If you have jbang installed, you can run jbang mulefd@manikmagar/mulefd
to run latest release of MuleFD.
To install the distribution -
. Clone the project
. Run ./gradlew installDist
. This will explode the generated zip file to ./build/install
directory.
. You can verify binaries by executing -
.. icon:apple[] icon:linux[] : sh build/install/mulefd/bin/mulefd help
.. icon:windows[] : ./build/install/mulefd/bin/mulefd.bat help
== Configuration [[configuration, Configuration]]
mulefd
supports external properties configuration to change the behavior of the tool. You can create a file ${user.home}/.mulefd/mulefd.properties
and provide configuration properties.
To see the current properties, including the defaults of the tool, run following command -
=== Supported Properties
Following properties are supported in the config properties:
diagram.font.name
: To change the font used for graph text, set this to the name of the font available on target system. Eg. Arial or Courier.mule.components.csv
: Path of the file containing list of <>.NOTE: If generated diagram has node label's going out of the shape, try changing the font to the one available on the systm.
== Usage
mulefd
support various arguments for generating diagrams.
Example:
mulefd graph ~/AnypointStudio/studio-workspace/mulefd-demo
Out of memory errors?
If your application is large and contains too many flows, process could fail with Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
error.
Try increasing the JVM allocated memory using -Xmx
flag.
For windows, you may need to set it at environment level -
=== Source directory Source directory is a required argument. This argument specifies where mule xml configuration files be searched.
This argument value can be one of the following:
~/Downloads/test-app-config.xml
. In this case, diagram for just this file is generated.~/AnypointStudio/studio-workspace/mulefd-demo
.src/main/app/
are scanned to generate a diagram.src/main/mule/
are scanned to generate a diagram.=== Generate Individual flow diagrams
When running against a large mule application, the generated mule-diagram.png
can contain too many flows. To simplify understanding each flow, it can be helpful to generate diagrams per flow (not sub-flows).
You can specify -gs
or --genSingles
option to generate individual flow diagrams, in addition to the consolidated one.
These diagrams are generated at {targetPath}/single-flow-diagrams/{currentDateTime}
directory. Each generated diagram has the same name as flow it represents.
NOTE: Some flow names, especially the APIKit generated flows can contain characters not valid for some OS. Names are thus sanitized. Any character not in a-zA-Z0-9.-
is replaced with _
.
=== Flowname
If you just want to generate diagram for a single flow then specify it with -fl
or --flowname
option. This will exclude all flows and subflows that are not related to this target flow.
=== Diagram Types
Current release supports generating Graph
diagram only.
=== Output arguments
Target directory to output generated diagram can be specified with -t {directoryPath}
option. This is an optional argument and defaults to the source directory (or parent directory if source is a file).
The file name for diagram defaults to mule-diagram.png
. This can be changed by specifying -o {filename}
argument.
== Known modules/connectors [[known-components, Known modules/connectors]] Mule has many connectors/modules that can be used for building flows and sub-flows, and list keeps growing. This tool maintains a list of known components with their supported operations for including in the generated diagram.
You can find this list in source code link:src/main/resources/default-mule-components.csv[].
Each record in this file has following columns -
prefix, operation, sourceFlag, path, configName, async
vm
, http
etc.listener
, consume
in vm
etc. This supports wildcard entries (values defined as *
) for non-source (sourceFlag=false
) entries.true
if operation
is an input source withing that namespace. Eg. listener
in vm
.queueName
for vm:listener
or path
for http:request
. This value will be visible on source nodes in the diagram.xpath:
prefix must be added to the expression when providing relative xpath.//
config-ref
attribute name for vm:listener
. For sources, this is visible on source nodes in diagram. This can help identify source uniquely when multiple configuration exists.true
if this is an asynchronous operation. Defaults to false
.The generated diagram will represent these known components using the Component share.
image::./docs/images/known-component-shape-example.png[title="Known Component rendering for s3:create-object to test2 bucket"]
=== Registering custom modules If any module is missing in the default list - either being a new module or a custom module, then it is possible for users to register their modules.
If mulefd-components.csv
named CSV file exists in sourcePath
, then all modules/connectors within that file are registered as known components. Structure of this file must be same as default components file explained above.
See example file at link:src/test/resources/mulefd-components.csv[].
MuleFD will load components file from predefined locations in the given order as below -
mule.components.csv
== Troubleshooting
=== Getting None of the provided engines could be initialized This tool uses Graphviz-Java library to generate diagrams. Graphviz-Java https://github.com/nidi3/graphviz-java#how-it-works[describes] how the engines are leveraged. To execute the graphviz layout engine, one of these options is used:
. If the machine has graphviz installed and a dot
command is available, spawn a new process running dot.
. Use this https://github.com/mdaines/viz.js[javascript version] of graphviz and execute it on the V8 javascript engine. This is done with the bundled https://github.com/eclipsesource/J2V8[J2V8] library.
. Alternatively, the javascript can be executed on Java's own Nashorn or GraalVM engine (preferring Graal if both are available).
This tool bundles the J2V8 library but it https://github.com/manikmagar/mulefd/issues/244[does not support] Apple M1. The Java's Nashorn engine was deprecated starting JDK 9 and removed in JDK 15.
So, if your diagram generation is failing with that error then check one of the following -
dot
is installed. It is a part of Graphviz, so check https://graphviz.org/download/#mac[here] for installing graphviz with brew install graphviz
.== Copyright & License
Licensed under the MIT License, see the link:LICENSE[LICENSE] file for details.