feat: tracer option and trace utils

Author: farnabaz

docs/content/5.api/1.parse.md

@@ -365,18 +365,18 @@ Both `parseMarkdown()` and `createMarkdownParser()` accept the same `ParserOptio
 | `headingIds` | `boolean` | `true` | Auto-generate `id` attributes for `h1`–`h6` headings. Set `false` to disable |
 | `registerDefaultPlugins` | `boolean` | `true` | Register the built-in default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`). Set `false` to disable. Also can be used to configure default plugins like `components` in conjunction with `plugins` |
 | `plugins` | `ComarkPlugin[]` | `[]` | Array of plugins to apply |
-| `perf` | `ComarkPerf` | `undefined` | Timing recorder for the parse pipeline — see [Timing the parse](#timing-the-parse) |
+| `tracer` | `ComarkTracer` | `undefined` | Timing recorder for the parse pipeline — see [Timing the parse](#timing-the-parse) |
 
 ### Timing the parse
 
-Pass a `perf` recorder to time each phase of the pipeline and every plugin hook, so you can see where parse time goes (e.g. a slow `post` highlight hook). The contract is a structural subset of [OpenTelemetry](https://opentelemetry.io/docs/languages/js/instrumentation/#creating-spans) `Tracer` — `startSpan` and `startActiveSpan` — so a real OTel tracer works as-is:
+Pass a `tracer` to time each phase of the pipeline and every plugin hook, so you can see where parse time goes (e.g. a slow `post` highlight hook). The contract is a structural subset of [OpenTelemetry](https://opentelemetry.io/docs/languages/js/instrumentation/#creating-spans) `Tracer` — `startSpan` and `startActiveSpan` — so a real OTel tracer works as-is:
 
 ```ts
 import { trace } from '@opentelemetry/api'
 
 const parse = createMarkdownParser({
   // Uses the OpenTelemetry provider registered by your app or hosting platform.
-  perf: trace.getTracer('comark'),
+  tracer: trace.getTracer('comark'),
   plugins: [highlight()],
 })
 ```
@@ -393,20 +393,20 @@ Or a minimal recorder:
 
 ```ts
 const spans: { name: string, duration: number }[] = []
-const perf = {
+const tracer = {
   startSpan(name) {
     const start = performance.now()
     return { end: () => spans.push({ name, duration: performance.now() - start }) }
   },
   startActiveSpan(name, optionsOrFn, maybeFn) {
     const fn = typeof optionsOrFn === 'function' ? optionsOrFn : maybeFn
-    const span = perf.startSpan(name)
+    const span = tracer.startSpan(name)
     // Nested startActiveSpan/startSpan calls become children via your context/stack.
     return fn(span) // caller (comark) ends the span
   },
 }
 
-const parse = createMarkdownParser({ perf, plugins: [highlight()] })
+const parse = createMarkdownParser({ tracer, plugins: [highlight()] })
 await parse(markdown)
 // spans → comark:parse
 //           ├─ comark:autoclose
@@ -418,7 +418,7 @@ await parse(markdown)
 //           …
 ```
 
-Recorded spans: a root `comark:parse` active span enclosing `comark:autoclose`, `comark:tokenize` (markdown parsing), `comark:nodes` (token → AST conversion and unwrapping), and `comark:pre:<name>` / `comark:post:<name>` for each plugin hook. Nested `startActiveSpan` calls form the parent → child hierarchy (OTel active context, or a stack in a simple recorder). There is no timing overhead when `perf` is omitted, and no Node-specific API is used — it works in the browser too.
+Recorded spans: a root `comark:parse` active span enclosing `comark:autoclose`, `comark:tokenize` (markdown parsing), `comark:nodes` (token → AST conversion and unwrapping), and `comark:pre:<name>` / `comark:post:<name>` for each plugin hook. Nested `startActiveSpan` calls form the parent → child hierarchy (OTel active context, or a stack in a simple recorder). There is no timing overhead when `tracer` is omitted, and no Node-specific API is used — it works in the browser too.
 
 ### Inline rendering
 

examples/3.cli/perf-trace/index.ts

@@ -11,7 +11,7 @@
  * Or from this directory:
  *   pnpm start
  */
-import { createMarkdownParser, type ComarkPerf, type ComarkSpan, type ComarkSpanOptions } from 'comark'
+import { createMarkdownParser, type ComarkTracer, type ComarkSpan, type ComarkSpanOptions } from 'comark'
 import rangi from 'comark/plugins/rangi'
 import toc from 'comark/plugins/toc'
 import security from 'comark/plugins/security'
@@ -29,7 +29,7 @@ interface TraceNode {
   children: TraceNode[]
 }
 
-function createTracePerf() {
+function createTraceTracer() {
   const entries: PerfEntry[] = []
   const stack: string[] = []
   let nextId = 0
@@ -52,7 +52,7 @@ function createTracePerf() {
     return { span, id, parent, start }
   }
 
-  const perf: ComarkPerf = {
+  const tracer: ComarkTracer = {
     startSpan(name) {
       // Non-active child of the current active span (if any).
       return makeSpan(name).span
@@ -69,7 +69,7 @@ function createTracePerf() {
     },
   }
 
-  return { perf, entries }
+  return { tracer, entries }
 }
 
 /** Rebuild a tree from parent → id links. */
@@ -171,9 +171,9 @@ Nested component body with **bold**.
 - item two
 `
 
-const { perf, entries } = createTracePerf()
+const { tracer, entries } = createTraceTracer()
 const parse = createMarkdownParser({
-  perf,
+  tracer,
   plugins: [
     rangi(),
     toc({ depth: 3 }),

examples/3.cli/perf-trace/otel.ts

@@ -69,7 +69,7 @@ const provider = new NodeTracerProvider({
 provider.register()
 
 const parse = createMarkdownParser({
-  perf: trace.getTracer('comark'),
+  tracer: trace.getTracer('comark'),
   plugins: [
     rangi(),
     toc({ depth: 3 }),

packages/comark/package.json

@@ -42,6 +42,7 @@
     ".": "./dist/index.js",
     "./plugins/*": "./dist/plugins/*.js",
     "./utils": "./dist/utils/index.js",
+    "./utils/trace": "./dist/utils/trace.js",
     "./parse": "./dist/parse.js",
     "./render": "./dist/render.js"
   },

packages/comark/src/parse.ts

@@ -5,9 +5,6 @@ import type {
   MarkdownExitPlugin,
   MergePluginFrontmatter,
   MergePluginMeta,
-  ComarkPerf,
-  ComarkSpan,
-  ComarkSpanOptions,
   ParserOptions,
   ResolvedFrontmatter,
   ResolvedMeta,
@@ -27,29 +24,14 @@ import { marmdownItTokensToMarkdownDocument } from './internal/parse/token-proce
 import { autoCloseMarkdown } from './internal/parse/auto-close/index.ts'
 import { extractReusableNodes } from './internal/parse/incremental.ts'
 import { createSerializedTask, dedupePlugins } from './utils/helpers.ts'
+import { noopTracer, withSpan } from './utils/trace.ts'
 
 // Re-export frontmatter utilities
 export { parseFrontmatter } from './internal/frontmatter.ts'
 
 // Re-export plugin utilities
 export { defineComarkPlugin } from './utils/helpers.ts'
 
-/** No-op span used by {@link noopPerf}. */
-const noopSpan: ComarkSpan = { end: () => {} }
-
-/** No-op recorder used when no `perf` option is provided — zero overhead. */
-const noopPerf: ComarkPerf = {
-  startSpan: () => noopSpan,
-  startActiveSpan: (
-    _name: string,
-    optionsOrFn: ComarkSpanOptions | ((span: ComarkSpan) => unknown),
-    fn?: (span: ComarkSpan) => unknown
-  ) => {
-    const run = typeof optionsOrFn === 'function' ? optionsOrFn : fn!
-    return run(noopSpan)
-  },
-}
-
 /**
  * Creates a parser function for Comark content.
  *
@@ -81,7 +63,7 @@ const noopPerf: ComarkPerf = {
 export function createMarkdownParser<const TPlugins extends readonly ComarkPlugin<any, any>[] = []>(
   options: ParserOptions<TPlugins> = {} as ParserOptions<TPlugins>
 ): ComarkParseFn<ResolvedMeta<MergePluginMeta<TPlugins>>, ResolvedFrontmatter<MergePluginFrontmatter<TPlugins>>> {
-  const { autoUnwrap = true, autoClose = true, perf = noopPerf } = options
+  const { autoUnwrap = true, autoClose = true, tracer = noopTracer } = options
   // Tag set to strip from the top level of the tree (MDC `unwrap`). Resolved once.
   const unwrapTags = resolveUnwrapTags(options.unwrap)
 
@@ -124,29 +106,12 @@ export function createMarkdownParser<const TPlugins extends readonly ComarkPlugi
   let lastOutput: MarkdownDocument | null = null
   let lastInput: string | null = null
 
-  /** Run `fn` inside an active span; always ends the span (incl. async). */
-  function withSpan<T>(name: string, fn: () => T): T {
-    return perf.startActiveSpan(name, (span) => {
-      try {
-        const result = fn()
-        if (result instanceof Promise) {
-          return result.finally(() => span.end()) as T
-        }
-        span.end()
-        return result
-      } catch (error) {
-        span.end()
-        throw error
-      }
-    })
-  }
-
   const parseFn: ComarkParseFn = async (markdown, opts = {}) => {
     // Root active span for the full parse pipeline. Nested startActiveSpan /
     // startSpan calls become children (OTel active context, or a stack in a
     // simple recorder) → hierarchical trace:
     //   comark:parse → autoclose / pre / tokenize / nodes / post
-    return await withSpan('comark:parse', async () => {
+    return await withSpan(tracer, 'comark:parse', async () => {
       const state = {
         options,
         tokens: [] as unknown[],
@@ -175,7 +140,7 @@ export function createMarkdownParser<const TPlugins extends readonly ComarkPlugi
       }
 
       if (autoClose) {
-        state.markdown = withSpan('comark:autoclose', () =>
+        state.markdown = withSpan(tracer, 'comark:autoclose', () =>
           autoCloseMarkdown(state.markdown, {
             frontmatter: hasPlugin('frontmatter') && opts.streaming,
             syntax: hasPlugin('components'),
@@ -185,11 +150,11 @@ export function createMarkdownParser<const TPlugins extends readonly ComarkPlugi
 
       for (const plugin of plugins) {
         if (!plugin.pre) continue
-        await withSpan(`comark:pre:${plugin.name}`, () => plugin.pre!(state))
+        await withSpan(tracer, `comark:pre:${plugin.name}`, () => plugin.pre!(state))
       }
 
       try {
-        state.tokens = withSpan('comark:tokenize', () => parser.parse(state.markdown, {}))
+        state.tokens = withSpan(tracer, 'comark:tokenize', () => parser.parse(state.markdown, {}))
       } catch (e) {
         // in case of streaming, return the previous output if parsing fails
         // This is to avoid resetting the tree to an empty state on failure
@@ -201,7 +166,7 @@ export function createMarkdownParser<const TPlugins extends readonly ComarkPlugi
       }
 
       // Convert tokens to Comark structure
-      const nodesSpan = perf.startSpan('comark:nodes')
+      const nodesSpan = tracer.startSpan('comark:nodes')
       let nodes = marmdownItTokensToMarkdownDocument(state.tokens, {
         startLine: state.parsedLines,
         preservePositions: opts.streaming ?? false,
@@ -242,7 +207,7 @@ export function createMarkdownParser<const TPlugins extends readonly ComarkPlugi
 
       for (const plugin of plugins) {
         if (!plugin.post) continue
-        await withSpan(`comark:post:${plugin.name}`, () => plugin.post!(state as ComarkParsePostState))
+        await withSpan(tracer, `comark:post:${plugin.name}`, () => plugin.post!(state as ComarkParsePostState))
       }
 
       return state.tree

packages/comark/src/types.ts

@@ -322,17 +322,17 @@ export interface ComarkSpanOptions {
  *
  * ```ts
  * import { trace } from '@opentelemetry/api'
- * const parse = createMarkdownParser({ perf: trace.getTracer('comark') })
+ * const parse = createMarkdownParser({ tracer: trace.getTracer('comark') })
  * ```
  *
  * Nested `startActiveSpan` calls form a parent → child hierarchy via the
  * active context (OTel) or an internal stack (simple recorders). Universal
  * by design — no Node-specific APIs — so it works in the browser too.
  *
  * Like OTel, callers must `span.end()` (including in `finally` / promise
- * settlement). See {@link ParserOptions.perf}.
+ * settlement). See {@link ParserOptions.tracer}.
  */
-export interface ComarkPerf {
+export interface ComarkTracer {
   /**
    * Start a span without making it active. Call `span.end()` when done.
    * Compatible with OTel `Tracer.startSpan(name, options?)`.
@@ -505,17 +505,17 @@ export interface ParserOptions<TPlugins extends readonly ComarkPlugin<any, any>[
   plugins?: TPlugins
 
   /**
-   * Timing recorder for the parse pipeline — see {@link ComarkPerf}.
+   * Timing recorder for the parse pipeline — see {@link ComarkTracer}.
    * Structural subset of OpenTelemetry `Tracer`, so an OTel tracer works as-is:
-   * `createMarkdownParser({ perf: trace.getTracer('comark') })`.
+   * `createMarkdownParser({ tracer: trace.getTracer('comark') })`.
    *
    * When provided, the full parse is a root `comark:parse` active span containing
    * child phases (`comark:autoclose`, `comark:tokenize`, `comark:nodes`) and plugin
    * hooks (`comark:pre:<name>`, `comark:post:<name>`). Nested active spans form
    * the hierarchy. No timing overhead when omitted.
    * @default undefined
    */
-  perf?: ComarkPerf
+  tracer?: ComarkTracer
 }
 
 /**

packages/comark/src/utils/trace.ts

@@ -0,0 +1,36 @@
+import type { ComarkSpan, ComarkSpanOptions, ComarkTracer } from '../types.ts'
+
+/** No-op span used by {@link noopTracer}. */
+const noopSpan: ComarkSpan = { end: () => {} }
+
+/** No-op recorder used when no `tracer` option is provided — zero overhead. */
+export const noopTracer: ComarkTracer = {
+  startSpan: () => noopSpan,
+  startActiveSpan: (
+    _name: string,
+    optionsOrFn: ComarkSpanOptions | ((span: ComarkSpan) => unknown),
+    fn?: (span: ComarkSpan) => unknown
+  ) => {
+    const run = typeof optionsOrFn === 'function' ? optionsOrFn : fn!
+    return run(noopSpan)
+  },
+}
+
+/**
+ * Run `fn` inside an active span on `tracer`; always ends the span (incl. async).
+ */
+export function withSpan<T>(tracer: ComarkTracer, name: string, fn: () => T): T {
+  return tracer.startActiveSpan(name, (span) => {
+    try {
+      const result = fn()
+      if (result instanceof Promise) {
+        return result.finally(() => span.end()) as T
+      }
+      span.end()
+      return result
+    } catch (error) {
+      span.end()
+      throw error
+    }
+  })
+}