sift
A tool to model and analyze the design of systems from java class files.
Features
- CLI tool for building, querying and diff-ing "system models" from parsed .class files.
- System models consist of Entities and are produced by Instrumenter Pipelines.
- Instrumenter Pipelines provide knowledge about technology stacks for (static) bytecode analysis.
- Declarative DSL for additional, user-defined pipelines.
- JSON serialization of pipelines for simpler reuse and sharing.
Spring-Boot with Axon Framework instrumenter in action.
CLI options
Usage: sift [OPTIONS] [PATHS]...
Usage: sift [OPTIONS]
A tool to model and analyze the design of systems from bytecode.
Options:
-f, --class-dir PATH jar or directory with classes
-l, --list-instrumenters print all instrumenters detected on the current classpath
-i, --instrumenter INSTRUMENTER the instrumenter pipeline performing the scan
--profile print execution times and input/output for the executed
pipeline
-T, --tree-root ENTITY-TYPE tree built around requested entity type
-t, --list-entity-types lists entity types defined by instrumenter
-L, --max-depth INT Max display depth of the tree
-F, --filter REGEX filters nodes by label. can occur multiple times
-S, --filter-context REGEX filters nodes by label, while also including sibling nodes.
can occur multiple times
-e, --exclude REGEX excludes nodes when label matches REGEX; can occur multiple
times
-E, --exclude-type ENTITY-TYPE excludes entity types from tree; can occur multiple times
-s, --save FILE_JSON save the resulting system model as json; for later use by
--diff or --load
--load FILE_JSON load a previously saved system model
-d, --diff FILE_JSON load a previously saved system model
-a, --ansi [none|ansi16|ansi256|truecolor] override automatically detected ANSI support
--version print version and release date
--debug prints log/logCount statements from the executed pipeline
--generate-completion [bash|zsh|fish]
-h, --help Show this message and exit
Entity and Entity Type
The system model is described by its constituent entities and their relationships. Each entity is uniquely identified by either a class, method, field or parameter element; an element can not be associated with more than one entity.
All entities are mapped to a type. A type represents any notable part of the system, e.g. REST controllers, HTTP endpoints, inbound/outbound messages, RDS etc.
$ sift --instrumenter spring-axon --list-entity-types target/classes
entity types of spring-axon
1 aggregate
2 aggregate-ctor
1 aggregate-member
6 command
6 command-handler
1 controller
13 endpoint
7 event
7 event-handler
7 event-sourcing-handler
1 projection
3 query
4 query-handler
Instrumenter pipelines
Instrumenter Pipelines provide knowledge about a technology stack and/or project-specific constructs. The pipeline produces the system model from the input classes.
Pipelines are written in a declarative DSL, which provides high-level abstractions for identifying and interrelating entities from class structure or usage.
val controller = Entity.Type("controller")
val endpoint = Entity.Type("endpoint")
instrumenter {
// iterate over all input classes
classes {
annotatedBy<RestController>() // filter classes
entity(controller) // mark remaining as 'controller'
methods { // iterate all controller methods
annotatedBy<Endpoint>() // filter @Endpoint methods
entity(endpoint)
// associate controllers with their endpoints
controller["endpoints"] = endpoint
}
}
}
Input elements - classes, methods, parameters and fields - are processed in batch, line-by-line.
A Instrumenter Pipeline can be expressed in about 100LOC. Some are notably shorter, e.g. jpa and jdbi. User-defined pipelines may choose to include() multiple existing pipelines, e.g. spring-axon and jpa, to better describe the underlying system while also keeping the resulting pipeline DSL concise.
The execution of an Instrumenter Pipeline can be visualized with --profile:
Caveats and limitations
- no flow analysis making precise entity identification difficult for e.g. dispatcher-like methods dealing with multiple entity types.
2 Nov 1, 2022
8 Dec 17, 2022
0 Apr 30, 2022
1.2k Dec 29, 2022
0 Nov 11, 2021
2 Dec 1, 2021
0 Dec 24, 2021
0 Jan 3, 2022
1 Dec 26, 2021
2 Nov 21, 2021
3 Mar 23, 2022
5 Jul 30, 2022
2 May 26, 2022
14 Sep 8, 2022
2 Dec 15, 2021
2 Oct 23, 2022
6 Nov 11, 2022
4 Jul 28, 2022
2 Jun 5, 2022
