Overview

By using the Micrometer Docs Generator project and by implementing the ObservationDocumentation, SpanDocumentation or MeterDocumentation interfaces as an enum, you can scan your sources and generate Asciidoctor documentation. This lets you maintain the docuemntation for your observability instrumentation in code, and as long as you use the enum implementation in your instrumentation, it ensures that your documentation stays in-sync with the instrumentation.

The following example shows a Maven pom.xml with the Micrometer Docs Generator project:

pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright 2023 VMware, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		 xmlns="http://maven.apache.org/POM/4.0.0"
		 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.example</groupId>
	<artifactId>micrometer-docs-generator-example</artifactId>
	<packaging>jar</packaging>
	<name>micrometer-docs-generator-example</name>
	<description>micrometer-docs-generator-example</description>
	<properties>
		<micrometer-docs-generator.version>1.0.0</micrometer-docs-generator.version>
		<micrometer-docs-generator.inputPath>${maven.multiModuleProjectDirectory}/folder-with-sources-to-scan/</micrometer-docs-generator.inputPath>
		<micrometer-docs-generator.inclusionPattern>.*</micrometer-docs-generator.inclusionPattern>
		<micrometer-docs-generator.outputPath>${maven.multiModuleProjectDirectory}/target/output-folder-with-adocs/'</micrometer-docs-generator.outputPath>
	</properties>
	<build>
		<plugins>
			<plugin>
				<groupId>org.codehaus.mojo</groupId>
				<artifactId>exec-maven-plugin</artifactId>
				<executions>
					<execution>
						<id>generate-docs</id>
						<phase>prepare-package</phase>
						<goals>
							<goal>java</goal>
						</goals>
						<configuration>
							<mainClass>io.micrometer.docs.DocsGeneratorCommand</mainClass>
							<includePluginDependencies>true</includePluginDependencies>
							<arguments>
								<argument>${micrometer-docs-generator.inputPath}</argument>
								<argument>${micrometer-docs-generator.inclusionPattern}</argument>
								<argument>${micrometer-docs-generator.outputPath}</argument>
							</arguments>
						</configuration>
					</execution>
				</executions>
				<dependencies>
					<dependency>
						<groupId>io.micrometer</groupId>
						<artifactId>micrometer-docs-generator</artifactId>
						<version>${micrometer-docs-generator.version}</version>
						<type>jar</type>
					</dependency>
				</dependencies>
			</plugin>
		</plugins>
	</build>

	<repositories>
		<repository>
			<id>spring-snapshots</id>
			<name>Spring Snapshots</name>
			<url>https://repo.spring.io/snapshot</url> <!-- For Snapshots -->
			<snapshots>
				<enabled>true</enabled>
			</snapshots>
			<releases>
				<enabled>false</enabled>
			</releases>
		</repository>
		<repository>
			<id>spring-milestones</id>
			<name>Spring Milestones</name>
			<url>https://repo.spring.io/milestone</url>  <!-- For Milestones -->
			<snapshots>
				<enabled>false</enabled>
			</snapshots>
		</repository>
	</repositories>
</project>

The following example shows a Gradle build.gradle with the Micrometer Docs Generator project:

build.gradle
repositories {
	maven { url 'https://repo.spring.io/snapshot' } // for snapshots
	maven { url 'https://repo.spring.io/milestone' } // for milestones
	mavenCentral() // for GA
}

ext {
	micrometerDocsVersion="1.0.2"
}

configurations {
	adoc
}

dependencies {
	adoc "io.micrometer:micrometer-docs-generator:$micrometerDocsVersion"
}

task generateObservabilityDocs(type: JavaExec) {
	mainClass = "io.micrometer.docs.DocsGeneratorCommand"
	classpath configurations.adoc
	// input folder, inclusion pattern, output folder
	args project.rootDir.getAbsolutePath(), ".*", project.rootProject.buildDir.getAbsolutePath()
}

Running these tasks would lead to generation of adoc files similar to these:

_metrics.adoc
[[observability-metrics]]
=== Observability - Metrics

Below you can find a list of all samples declared by this project.

[[observability-metrics-task-runner-observation]]
==== Task Runner Observation

> Observation created when a task runner is executed.

**Metric name** `spring.cloud.task.runner` (defined by convention class `org.springframework.cloud.task.configuration.observation.DefaultTaskObservationConvention`). **Type** `timer` and **base unit** `seconds`.

Fully qualified name of the enclosing class `org.springframework.cloud.task.configuration.observation.TaskDocumentedObservation`.

IMPORTANT: All tags must be prefixed with `spring.cloud.task` prefix!

.Low cardinality Keys
|===
|Name | Description
|`spring.cloud.task.runner.bean-name`|Name of the bean that was executed by Spring Cloud Task.
|===
_spans.adoc
[[observability-spans]]
=== Observability - Spans

Below you can find a list of all spans declared by this project.

[[observability-spans-task-runner-observation]]
==== Task Runner Observation Span

> Observation created when a task runner is executed.

**Span name** `spring.cloud.task.runner` (defined by convention class `org.springframework.cloud.task.configuration.observation.DefaultTaskObservationConvention`).

Fully qualified name of the enclosing class `org.springframework.cloud.task.configuration.observation.TaskDocumentedObservation`.

IMPORTANT: All tags and event names must be prefixed with `spring.cloud.task` prefix!

.Tag Keys
|===
|Name | Description
|`spring.cloud.task.runner.bean-name`|Name of the bean that was executed by Spring Cloud Task.
|===

Options

The main entry class for the docs generation is the DocsGeneratorCommand class. This class takes the following options:

Table 1. Optional parameters

--metrics

Generate metrics documentation.

--spans

Generate spans documentation.

--conventions

Generate observation conventions documentation.

--metrics-template=<location>

Handlebars template file location. This can be a path in the classpath or file system,
such as templates/metrics.adoc.hbs or /home/example/bar.hbs

--spans-template=<location>

Handlebars template file location. This can be a path in the classpath or file system,
such as templates/spans.adoc.hbs or /home/example/bar.hbs

--conventions-template=<location>

Handlebars template file location. This can be a path in the classpath or file system,
such as templates/conventions.adoc.hbs or /home/example/bar.hbs

--metrics-output=<location>

Generated metrics doc file location. This can be an absolute path or a path relative to the output directory.
Default: _metrics.adoc

--spans-output=<location>

Generated spans doc file location. This can be an absolute path or a path relative to the output directory.
Default: _spans.adoc

--conventions-output=<location>

Generated observation convention doc file location. This can be an absolute path or a path relative to the output directory.
Default: _conventions.adoc