Merge pull request #7 from nulab/fix/opentelemetry-tracing

Add @WithSpan annotations for OpenTelemetry phase tracing

Author: raydive

flexmark/pom.xml

@@ -62,6 +62,10 @@
             <groupId>com.vladsch.flexmark</groupId>
             <artifactId>flexmark-util-visitor</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.opentelemetry.instrumentation</groupId>
+            <artifactId>opentelemetry-instrumentation-annotations</artifactId>
+        </dependency>
         <dependency>
             <groupId>org.openjdk.jmh</groupId>
             <artifactId>jmh-core</artifactId>

flexmark/src/main/java/com/vladsch/flexmark/html/HtmlRenderer.java

@@ -18,6 +18,7 @@
 import com.vladsch.flexmark.util.sequence.Escaping;
 import com.vladsch.flexmark.util.sequence.LineAppendable;
 import com.vladsch.flexmark.util.sequence.TagRange;
+import io.opentelemetry.instrumentation.annotations.WithSpan;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -203,6 +204,7 @@ public void render(@NotNull Node node, @NotNull Appendable output) {
      * @param node   node to render
      * @param output appendable to use for the output
      */
+    @WithSpan("markdown.render")
     public void render(@NotNull Node node, @NotNull Appendable output, int maxTrailingBlankLines) {
         HtmlWriter htmlWriter = new HtmlWriter(output, htmlOptions.indentSize, htmlOptions.formatFlags, !htmlOptions.htmlBlockOpenTagEol, !htmlOptions.htmlBlockCloseTagEol);
         MainNodeRenderer renderer = new MainNodeRenderer(options, htmlWriter, node.getDocument());

flexmark/src/main/java/com/vladsch/flexmark/parser/Parser.java

@@ -17,6 +17,7 @@
 import com.vladsch.flexmark.util.sequence.BasedSequence;
 import com.vladsch.flexmark.util.sequence.ReplacedBasedSequence;
 import com.vladsch.flexmark.util.sequence.mappers.SpecialLeadInHandler;
+import io.opentelemetry.instrumentation.annotations.WithSpan;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -353,6 +354,7 @@ public static Builder builder(DataHolder options) {
      * @param input the text to parse
      * @return the root node
      */
+    @WithSpan("markdown.parse")
     public @NotNull Document parse(@NotNull BasedSequence input) {
         // NOTE: parser can only handle contiguous sequences with no out of base characters
         if (input instanceof ReplacedBasedSequence) {
@@ -379,6 +381,7 @@ public static Builder builder(DataHolder options) {
      * @param input the text to parse
      * @return the root node
      */
+    @WithSpan("markdown.parse")
     public @NotNull Document parse(@NotNull String input) {
         DocumentParser documentParser = new DocumentParser(options
                 , blockParserFactories
@@ -398,6 +401,7 @@ public static Builder builder(DataHolder options) {
      * @return the root node
      * @throws IOException when reading throws an exception
      */
+    @WithSpan("markdown.parse")
     public @NotNull Document parseReader(@NotNull Reader input) throws IOException {
         DocumentParser documentParser = new DocumentParser(options
                 , blockParserFactories

flexmark/src/main/java/com/vladsch/flexmark/parser/internal/DocumentParser.java

@@ -18,6 +18,7 @@
 import com.vladsch.flexmark.util.misc.CharPredicate;
 import com.vladsch.flexmark.util.sequence.BasedSequence;
 import com.vladsch.flexmark.util.sequence.PrefixedSubSequence;
+import io.opentelemetry.instrumentation.annotations.WithSpan;
 import org.jetbrains.annotations.NotNull;
 
 import java.io.BufferedReader;
@@ -271,16 +272,23 @@ public InlineParser getInlineParser() {
      */
     public Document parse(CharSequence source) {
         BasedSequence input = BasedSequence.of(source);
-        int lineStart = 0;
-        int lineBreak;
-        int lineEOL;
-        int lineEnd;
         lineNumber = 0;
 
         documentBlockParser.initializeDocument(options, input);
         inlineParser.initializeDocument(documentBlockParser.getBlock());
 
         currentPhase = ParserPhase.PARSE_BLOCKS;
+        parseBlocks(input);
+
+        return finalizeAndProcess();
+    }
+
+    @WithSpan("markdown.parse.blocks")
+    private void parseBlocks(BasedSequence input) {
+        int lineStart = 0;
+        int lineBreak;
+        int lineEOL;
+        int lineEnd;
 
         while ((lineBreak = Parsing.findLineBreak(input, lineStart)) != -1) {
             BasedSequence line = input.subSequence(lineStart, lineBreak);
@@ -308,8 +316,6 @@ public Document parse(CharSequence source) {
             incorporateLine(lineWithEOL);
             lineNumber++;
         }
-
-        return finalizeAndProcess();
     }
 
     public Document parse(Reader input) throws IOException {
@@ -745,6 +751,7 @@ private void finalize(BlockParser blockParser) {
     /**
      * Walk through a block & children recursively, parsing string content into inline content where appropriate.
      */
+    @WithSpan("markdown.parse.inlines")
     private void processInlines() {
         for (BlockParser blockParser : blockTracker.allBlockParsers()) {
             blockParser.parseInlines(inlineParser);
@@ -938,6 +945,7 @@ private void preProcessParagraph(Paragraph block, List<ParagraphPreProcessorFact
         }
     }
 
+    @WithSpan("markdown.parse.pre_process_paragraphs")
     private void preProcessParagraphs() {
         // here we run preProcessing stages
         if (blockTracker.getNodeClassifier().containsCategory(Paragraph.class)) {
@@ -951,6 +959,7 @@ private void preProcessParagraphs() {
         }
     }
 
+    @WithSpan("markdown.parse.pre_process_blocks")
     private void preProcessBlocks() {
         // here we run preProcessing stages
         HashSet<Class<?>> blockTypes = new HashSet<>();

flexmark/src/main/java/com/vladsch/flexmark/parser/internal/PostProcessorManager.java

@@ -12,6 +12,7 @@
 import com.vladsch.flexmark.util.dependency.DependencyResolver;
 import com.vladsch.flexmark.util.dependency.DependentItem;
 import com.vladsch.flexmark.util.dependency.DependentItemMap;
+import io.opentelemetry.instrumentation.annotations.WithSpan;
 
 import java.util.*;
 
@@ -50,6 +51,7 @@ public static List<PostProcessorDependencyStage> calculatePostProcessors(DataHol
         return dependencyStages;
     }
 
+    @WithSpan("markdown.parse.post_process")
     public static Document processDocument(Document document, List<PostProcessorDependencyStage> processorDependencies) {
         if (!processorDependencies.isEmpty()) {
             PostProcessorManager manager = new PostProcessorManager(processorDependencies);

pom.xml

@@ -538,6 +538,15 @@
                 <version>${project.version}</version>
             </dependency>
 
+            <!-- Annotation-only dependency, spans are created by a Java agent
+                 (dd-java-agent with dd.trace.otel.enabled=true, or opentelemetry-javaagent).
+                 Inert without an agent. -->
+            <dependency>
+                <groupId>io.opentelemetry.instrumentation</groupId>
+                <artifactId>opentelemetry-instrumentation-annotations</artifactId>
+                <version>2.16.0</version>
+            </dependency>
+
             <!-- Common test dependencies -->
             <dependency>
                 <groupId>junit</groupId>