= Inugami Project analysis maven plugin :toc: :source-highlighter: pygments
Inugami project analysis maven plugin have for target to generate a release note on your project. Detect hidden dependencies on microservices is not easy. This plugin use Neo4J to resolve them. You can find a generated release note example here : link:doc/release-note-example.adoc[release-note]
== Last Release:
== Quick start :
This maven plugin use Neo4J database to store information and resolve them. If you don't have Neo4J you can test on your local environment or run a Neo4J with docker.
version: "3" services: neo4j: image: neo4j:4.1.1 ports:
In your project pom.xml (or settings) we need to add some properties :
You can also define Neo4J configuration into your maven settings :
In this case, your maven settings will override your pom.xml properties.
In your project build definition :
First you need to analyse your project to send data into NEO4J:
image::doc/analyze-01.png[] image::doc/analyze-02.png[]
After this analyse you can see in Neo4j your project information or just execute maven phase info
image::doc/info.png[]
This phase requires to specify an action to display information
== Neo4j data structure :
image::doc/nodes.png[]
== Retrieve information :
After analyze, all information is present into Neo4J. We can now query Neo4J to retrieve information. Attention : in some commons use cases it's easier to invoke the plugin to display result.
All additional properties can be defined in properties section of pom.xml or via command line invocation (with -D prefix).
=== restServices
One of common problems in microservice architecture is to known interconnections between services. What's happen if I change my service ? Who consume a service and which version is currently in use ? To address this issue, the inugami analysis plugin will analyze all Springboot Rest endpoint and feign clients to detect interdependencies between projects.
REST endpoints can be defined in current project or as a transitive dependency. The plugin retrieve transitive dependencies over 10 sub levels.
The color code is the same as Swagger, all GET endpoints are blue, green for POST, and red for DELETE.
image::doc/restServices-01.png[]
In case where some projects consume an endpoint these will be described in the result :
image::doc/restServices-02.png[]
=== queryDisplay
Query display allows the generation of a Neo4J cypher query from the current projet.
image::doc/queryDisplay-01.png[]
Different queries are available, so it's required to specify the one in use.
image::doc/queryDisplay-02.png[]
=== properties
Properties action displays project properties. This action retrieves also dependencies properties. At this moment these properties are extracted from Spring properties (@Value, bean properties, conditionals beans, properties usages on JMS or RabbitMQ listeners)
If a property has no default value, it will be displayed in red. In yellow, we have properties who enable some beans. If a property have bean validator constraints, these will be displayed too.
image::doc/properties.png[]
=== queueInfo
Queue information have the same approach as restServices but for JMS and RabbitMQ. It's able to detect producers and listeners, tracing event payload and all information on queue binding.
Like restServices, the queueInfo retrieves information over 10 levels of transitive dependencies.
image::doc/queue.png[]
To track all JMS senders and RabbitMQ sender it's required to add annotations in your source code.
For JMS :
For RabbitMQ :
If you use multi-handler on RabbitLister you need to add an annotation specifying which routing key is in use :
All specific annotations are contained into an inugami artifact :
This artifact contains only annotations, nothing else.
=== errorDisplay
Error management is essential to make better applications. Interteam communication is a must. Writing wiki is not our way, it's time-consuming and quickly outdate. Inugami generates errors directly from code.
Per default Inugami plugin use the Inugami error interface to detect error code :
package io.inugami.api.exceptions; import java.util.function.BiConsumer;
public interface ErrorCode { public ErrorCode getCurrentErrorCode();
default int getStatusCode() {
return getCurrentErrorCode() == null ? 500 : getCurrentErrorCode().getStatusCode();
}
default String getErrorCode() {
return getCurrentErrorCode() == null ? "undefine" : getCurrentErrorCode().getErrorCode();
}
default String getMessage() {
return getCurrentErrorCode() == null ? "error" : getCurrentErrorCode().getMessage();
}
default String getMessageDetail() {
return getCurrentErrorCode() == null ? null : getCurrentErrorCode().getMessageDetail();
}
default String getErrorType() {
return getCurrentErrorCode() == null ? "technical" : getCurrentErrorCode().getErrorType();
}
default String getPayload() {
return getCurrentErrorCode() == null ? null : getCurrentErrorCode().getPayload();
}
default BiConsumer<String, Exception> getErrorHandler() {
return getCurrentErrorCode() == null ? null : getCurrentErrorCode().getErrorHandler();
}This interface is present in inugami_api artifact :
This interface can be used over enum types or on static class fields.
public enum IssuesError implements ErrorCode {
ISSUES_1(newBuilder()
.setStatusCode(400)
.setMessage("issues request invalid")
.setErrorType("input")),
ISSUES_1_1(newBuilder()
.setStatusCode(400)
.setMessage("issue uid is mandatory")
.setFonctionnalError());
private final ErrorCode errorCode;
private IssuesError(final ErrorCodeBuilder errorBuilder) {
errorCode = errorBuilder.setErrorCode(this.name()).build();
}
@Override
public ErrorCode getCurrentErrorCode() {
return errorCode;
}You can define your error code interface, to do so just add a property in your pom.xml
In this case the plugin will retrieve all values defined in your interface.
image::doc/errorCode.png[]
.Additional configuration |=== |Property | type | default value | description
|-Dinugami.maven.plugin.analysis.analyzer.errorCode.interface |String |io.inugami.api.exceptions.ErrorCode |The error code interface to use
|-Dexport | boolean | false | allow exporting results as CSV files |===
=== specificsQuery
The plugin is able to retrieve information from Neo4J and display them. If you need to execute a specific cypher query is possible to use this plugin to do that.
image::doc/specificQuery.png[]
.Additional configuration |=== |Property | type | default value | description
|-Dinugami.query.path |String |null |Path to cypher query, if isn't define the plugin will ask for this one in prompt.
|-Dinugami.skip.properties |String (Regex Pattern) |null |for not display some nodes properties
|-Dexport |boolean |false |Allow to export result as CSV file
|===
=== importData
To import some data into Neo4J it's possible to call the importData action. This action is able to execute a cypher query or to import a JSON model.
For both it's required to specify the property inugami.query.path to define the import script path
For cypher query is just a basic .cql script. This one must juste have for extension .cql. Neo4j has great documentation on cypher language : https://neo4j.com/docs/cypher-manual/current/
For the JSON model, is the internal plugin model as JSON :
.Additional configuration |=== |Property | type | default value | description
|-Dinugami.query.path |String |null |Path to cypher or JSON import script query, if it's not defined the plugin will prompt for a value.
|===
=== Deployment management
Microservices complicate the deployment process. It's very important to know which microservice is on which environment.
==== publish
You need to pass some additional information to Neo4J to detect which artifact is on wich environment. The easiest way is to use the "publish action".
image::doc/publish-01.png[]
image::doc/publish-02.png[]
On DEPLOY we can see that the plugin has added the deployment date (on ISO date and timestamp, both are on system time zone and on UTC) .Additional configuration
|=== |Property | type | default value | description
|-DuseMavenProject |Boolean | null |Allow using current project GAV, if null the plugin will prompt for a value.
|-Denv |String | null |Destination environment, if null the plugin will prompt for a value.
|-DenvLevel |int | 0 |To sort environments it's necessary to add weight, if null the plugin will prompt for a value.
|-DenvType |String | null |The environment type (like DEV, INT, PREP, PROD..), if null the plugin will prompt for a value.
|-DautoUnpublish |boolean |false |Allow remove relationship between an artifact and an environment node
|-DjustThisVersion |boolean |false |If you want to clean all version relationship between an artifact and an environment node
|-DpreviousEnv |boolean |false |For cleaning previous staging environment, this value will be prompted if not defined on an enabled autoPublish. |===
==== unpublish
It's very closer than publish but in this action we will remove deployments relationship on a specific version and an environment.
.Additional configuration |=== |Property | type | default value | description
|-DuseMavenProject |boolean |false |Allow using current project GAV and not ask for this information
|-Denv |String | null |Destination environment, if null the plugin will prompt for a value.
|-DenvLevel |int | 0 |To sort environments it's necessary to add weight, if null the plugin will prompt for a value.
|-DenvType |String | null |The environment type (like DEV, INT, PREP, PROD..), if null the plugin will prompt for a value.
|-DjustThisVersion |boolean |false |If you want to clean all version relationship between an artifact and an environment node
|===
==== versionEnv
The action versionEnv is able to verify if your project have all dependencies available on all environments.
In this example, the project project-consumer is using a REST endpoint produced by spring-boot-training-lifecycle. PREP_2 is not deployed. The service project project-consumer can't work correctly on this environment.
Also, this project use a REST endpoint [GET]/comments/comments but no producer have been detected
image::doc/versionEnv.png[]
.Additional configuration |=== |Property | type | default value | description
|-Dexport |boolean |false |Allow exporting result as CSV file
|-DuseMavenProject |boolean |false |Allow using current project GAV and not ask for this information |===
==== envInfo
This action is a quick representation of an environment deployment status. It's able to retrieve which artifacts are present on which environments.
image::doc/envInfo.png[]
.Additional configuration |=== |Property | type | default value | description
|-Dexport |boolean |false |Allow to export result as CSV file |===
=== encodePassword
This action is just a small tool to encode a password or sensible value in AES.
image::doc/password.png[]
.Additional configuration |=== |Property | type | default value | description
|-Dinugami.maven.plugin.analysis.secret |String (16 chars) |null |AES passphrase |===
== Analyzers :
=== Feign clients
Feign clients analyzer scan all feign client interface to resolve project consuming REST endpoints;
.Properties |=== |Property | type | default value | description
|inugami.maven.plugin.analysis.analyzer.feign.enable |boolean |true |Allow to disable feign client analyzer
|inugami.maven.plugin.analysis.analyzer.restControllers.strict |boolean |true |if this mode isn't enable, only mandatory fields in models have been used for identify REST endpoint |===
=== SpringBoot RestControllers
To resolve project REST endpoint exposition, this analyzer scan all SpringBoot RestController.
.Properties |=== |Property | type | default value | description
|inugami.maven.plugin.analysis.analyzer.restControllers.enable |boolean |true |Allow disabling feign client analyzer
|inugami.maven.plugin.analysis.analyzer.restControllers.strict |boolean |true |if this mode isn't enable, only mandatory fields in models have been used for identify REST endpoint |===
=== Spring properties
Bad properties configuration is the source of most problems on a spring project. This analyzer scan all properties injected by @Value annotation or Bean configuration definition.
.Properties |=== |Property | type | default value | description
|inugami.maven.plugin.analysis.analyzer.properties.enable |boolean |true |Allow disabling feign client analyzer |===
=== ActiveMQ
To resolve activeMQ consumers and listeners, this analyzer is scanning all Spring @JmsListener annotation.
.Properties |=== |Property | type | default value | description
|inugami.maven.plugin.analysis.analyzer.jms.enable |boolean |true |Allow disabling feign client analyzer |===
=== Error code
To resolve activeMQ consumers and listeners, this analyzer is scanning all Spring @JmsListener annotation.
.Properties |=== |Property | type | default value | description
|inugami.maven.plugin.analysis.analyzer.errorCode.enable |boolean |true |Allow disabling error code analyzer
|inugami.maven.plugin.analysis.analyzer.errorCode.interface |String |io.inugami.api.exceptions.ErrorCode |Allow to specify the error code interface, configured by default with inugami error code interface
|inugami.maven.plugin.analysis.analyzer.errorCode.fieldName |String |errorCode |Allow to override the default error code "field". The method defined in error code interface resolves this field. Accessor prefix is ignored |===
=== Flyway
this analyze allow to reference all flyway script. In release note you will see all them as differential.
.Properties |=== |Property | type | default value | description
|inugami.maven.plugin.analysis.analyzer.flyway.enabled |boolean |false |Allow to enable or disable flyway analyzer
|inugami.maven.plugin.analysis.analyzer.flyway.paths |String (path) |null |To define all root folders who contains flyway scripts. Semicolon is use for split each path
|inugami.maven.plugin.analysis.analyzer.flyway.defaultDb |String |{{folder name}} |Allow force default Database name
|inugami.maven.plugin.analysis.analyzer.flyway.scriptTypes |String |sql |Allow to define scripts type |===
=== Git SCM
Git scm analyzer allow to extract all commit since last project tag. If your project haven't tag yet, this analyzer retrieve all commit since repository creation.
After analyze, new nodes types appear :
feature/123_my_feature, issue 123 will be extracted).image::doc/git_scm.png[]
image::doc/github_issues.png[]
image::doc/github_merge_request.png[]
To display the release note you can invoke task mvn info -Daction=releaseNote -PpreviousVersion={previousVersion}
image::doc/release_note_light.png[]
You can see on this example generated release-note as asciidoc : link:doc/release-note-example.adoc[release-note]
==== Issue Management
the Git scm analyzer will extract issues and merge request from commit message. On each it will call your issue management to retrieve more information on tickets.
To enable this behavior it's require to add issueManagement with link to SCM API in your pom.xml :
For GitLab :
For GitHub :
For Jira :
All issue management need credentials to grant access on REST API. To configure these you will add server tag in your maven settings.xml :
It's possible to encrypt your password with maven standard encryption mechanism (https://maven.apache.org/guides/mini/guide-encryption.html)
.Properties |=== |Property | type | default value | description
|inugami.maven.plugin.analysis.git |boolean |false |Allow to enable git scanning and retrieve information from issues manager
|inugami.maven.plugin.analysis.issue.tracker.pr.url
|String
|${issueManagement.url}
|If you use another repository to manage your project backlog, issueManagement.url must be configure on it. But to trace
merge request you should define inugami.maven.plugin.analysis.issue.tracker.pr.url with the issue management of your
source code repository
|===
===== Jira custom fields
Jira allow to define custom fields on your issues.
To extract these you can create a SPI implementation of interface i.inugami.maven.plugin.analysis.api.scan.issue.tracker.JiraCustomFieldsAppender
.Parameters |=== |Property | type | description
|issueId |String |Current issue uid
|json |com.fasterxml.jackson.databind.JsonNode |Tree representation of current Json response. For more information on Jira Rest API see https://docs.atlassian.com/software/jira/docs/api/REST/8.13.2/#api/2/issue-getIssue
|issueProperties |LinkedHashMap<String, Serializable> |Current properties
|neo4jResult |io.inugami.maven.plugin.analysis.api.models.ScanNeo4jResult |Allow to create another nodes or relationships |===
Your implementation can be in classpath or linked on plugin dependencies.
All implementation must be declare into src/resources/META-INF/services/io.inugami.maven.plugin.analysis.api.scan.issue.tracker.JiraCustomFieldsAppender
Example :
src/resources/META-INF/services/io.inugami.maven.plugin.analysis.api.scan.issue.tracker.JiraCustomFieldsAppender :
package io.app;
=== ReleaseNote
Plugin main target is to generate a release note from current project. By default this release note will be generate as Json file.
An ASCIIDOC implementation is present to generate a documentation more human friendly.
To display the release note you can invoke task mvn info -Daction=releaseNote -PpreviousVersion={previousVersion}
.Properties |=== |Property | type | default value | description
|inugami.maven.plugin.analysis.display.release.note.full |boolean |false |Allow to append more information on your release note
|previousVersion |String |null |To be able to compute the difference between two version; it's require to specify previous version.
|interactive |boolean |true |If you doesn't need JSON release note; you can disable this feature with this parameter.
|inugami.maven.plugin.analysis.display.release.note.asciidoc |boolean |false |Allow to generate release note as ASCIIDOC
|inugami.maven.plugin.analysis.display.release.note.asciidoc.baseDir |String (path) |{builddir}/src/doc/releases |Allow to specify target folder
|inugami.maven.plugin.analysis.display.release.note.asciidoc.splitFile |boolean |false |Allow to generate the release note with one document or multi document parts |===
==== ReleaseNote UI
Since version 1.6.0 a spring boot module allow to display current project release notes. To include this ui you should add this dependency :
By default the ui is accessible on URL : http://localhost:8080/release-note-app/
.Properties |=== |Property | type | default value | Require | description
|inugami.release.note.artifactName |String |null |true | Release note list json file name. This property is mandatory
After the release note building, two file will be created in your project :
|===
image::doc/ui-01.png[ui global,920,500]
image::doc/ui-02.png[ui detail,920,500]
https://www.youtube.com/watch?v=dJlF4RYd4eI&ab_channel=inugami
===== Update & ban dependencies
The inugami front ui is able to display information about dependencies baned or deprecated. The scan process doesn't check this information at this moment.
But you can create new DependenciesCheckService implementation:
To implement this one you need to create a newer service and define it into a configuration bean :
@Configuration public class MyProjectConfiguration {
@Primary
@Bean
public DependenciesCheck buildDependenciesCheck(){
return new MyDependenciesCheckService();
}This interface requires to return a DependenciesCheck object. This object is a basic DTO :
Each list contains a DependencyRule object like :
== Others goals :
=== mkdirs
This goal allow to create basic folders
=== delete
This goal allow to delete folder or files
=== loadProperties
This goal allow to load maven properties. All loaded properties will be accessible in nextmaven phase.
==== Global properties
The goal loadProperties can have global properties. All of them will added in maven properties context.
==== Local file properties
In most of time, we need to add properties from local file. This files can be properties file or json file (another file will be supported in next release). To do that you can specify resources. Each one need to specify the path (this path can have maven properties to templatize this one). Also it's require to specify the file type (properties or json)
After properties loaded, you can use properties in maven context.
In case of JSON file, all properties will be render as flat value. For example :
Will be rendered in maven context as :
==== Properties convertors
All properties convertors are SPI implementation. You can create easly one and enable its by including your jar dependency in inugami plugin. Inugami use a strategy partner to resolve right implementation. All of them need to implement the PropertiesConvertorSPI interface.
public interface PropertiesConvertorSpi { boolean accept(final String type);
Map<String, String> convert(final String content);As all SPI implementation you need to declare its in the specific file /META-INF/services/io.inugami.maven.plugin.analysis.api.convertors.PropertiesConvertorSpi
After that you can create your implementation :
@SpiPriority(10) public class MyConvertor implements PropertiesConvertorSpi {
public static final String PROPERTIES = "properties";
@Override
public boolean accept(final String type) {
return PROPERTIES.equalsIgnoreCase(type);
}
@Override
public Map<String, String> convert(final String content) {
// implementation
}Inugami order all implementation by higher SpiPriority. You can use this annotation if you need to override existing implementation.
==== External URL properties
If you need to retrieve properties from external source, like springboot cloud config, you can specify corresponding url to load this resource.
In this example, the endpoint will give us a response like :
It will be accessible in maven context by flatten value :
=== writeFile
WriteFile goal allw to write file by using mustache template. By default, maven properties will be transform to mustache values.
For example :
Will write in ${basedir}/target/file.from.innerTemplate.html this content :
You can also create external template file :
with template like :
With external template, you can create more complex file without pollute your maven pom.xml
Will generate this file :
{{description}}
=== copy
This goal allow to copy file. It's also allow to filtering resource. This goal will inject properties only on text file, binary file will only be copy to target file.
==== copy simple file
In this example we have a simple file in ${basedir}/src/test/resources/simple.template.html
{{description}}
This file will be copy to ${basedir}/src/test/resources/simple.template.html and all maven context properties will be injected :
The file result will be :
Lorem ipsum
==== copy folder
The copy goal can also copy folder. To do that you need only to specify folder path and target as directories:
==== maven dependencies
The copy goal can copy maven dependencies. In this case you need to specify the artifact GAV to copy in target destination :
=== unpack
Unpack goal can unzip resources into folder. When resources are write on filesystem, if it's text resources, the filtering is apply. This behavior can be disabled by configuration.