Metadata file support

[ttddyy]

Currently, docs-gen can only generate asciidoc files based on the existing source code files.
To make this project more useful, also as raised in #80, it should support metadata files.

docs-gen project(or else) should do two things:

• Generate metadata for the current project source-code
• Generate documentation from metadata

For metadata, it would be something like this:

{
  "name": "spring-framework",
  "spans": [...]
  "metrics": [...]
}

The creation of documentation should be able to specify what groups of metadata to be included/excluded.
For example, a doc is created with all metadata or specific metadata files in the classpath or file system.

Things to consider:

• Define metadata format
  This could be based on the current model classes(SpanEntry, MetricEntry, ObservationConventionEntry)

• Hookup the docs-gen to maven and gradle lifecycle
  In order to include the metadata files in the generating jar, the metadata generation needs to happen before jar creation.

• Allow manual metadata
  Similar to additional-spring-configuration-metadata in Spring Boot, allows users to provide a manual metadata file.

• Resolve model classes from metadata
  When the' ObservationConvention' class references classes in dependent jars, those jars may have metadata files.
  The referenced model resolution needs to be extended to consider the metadata files in jars in addition to the source files within the project.

• Metadata inclusion/exclusion
  When generating documents, provide filtering(include/exclude) by jar files(?), metadata name, package, etc.

[github-actions]

If you would like us to look at this issue, please provide the requested information. If the information is not provided within the next 7 days this issue will be closed.

[brunobat]

I want to do this on a custom KeyValues enum:

        /**
         * The method being observed (traced or measured).
         */
        CODE_FUNCTION {
            @Override
            public String asString() {
                return SemanticAttributes.CODE_FUNCTION.getKey();
            }
        }

Right now we need to supply a plain string on the asString method.
This functionality could also benefit from this issue.

[brunobat]

cc @marcingrzejszczak @jonatan-ivanov

[chicobento]

@ttddyy , thats a great idea, I like it more than what I proposed in #80.
During @jonatan-ivanov @shakuzen session in Spring IO Barcelona someone asked something about dashboards generation. If we have the metadata defined it could also be used in this context.

[shakuzen]

I think we're all in agreement this would be a really neat feature with a lot of possible benefits/use. I've marked it as help wanted to indicate we'd be happy to receive help in designing/implementing this. The description talks about a lot of parts, but if someone wants to work on this, it will likely be easier to contribute portions of this at a time so it is easier to review and integrate rather than all at once.