How to fix OOM

[CLOVIS-AI]

Hi!

I'm using the version 2.0.0. In CI, I'm seeing:

* What went wrong:
Execution failed for task ':compat:compat-ktor:dokkatooGeneratePublicationHtml'.
> A failure occurred while executing dev.adamko.dokkatoo.workers.DokkaGeneratorWorker
   > Java heap space

How much memory should I configure? How can I configure it?

[aSemy]

hey @CLOVIS-AI 👋. Unfortunately Dokka is quite memory intensive, depending on the project. How many subprojects do you have? Are there a lot of dependencies?

Specifying memory options

Changing the JVM memory args is different depending on your version of Dokkatoo.

v2.0.0

The memory for the worker process can be specified in the tasks:

// build.gradle.kts

tasks.withType<DokkatooGenerateTask>.configureEach {
  workerMinHeapSize.set("512m")
  workerMaxHeapSize.set("2g")
}

v2.1.0

In v2.1.0 the options have been changed a bit. You can choose run Dokka in the same Gradle process, so if you increase the memory for a Gradle build (set org.gradle.jvmargs=... in gradle.properties), then that will be shared with the Dokka generator.

// build.gradle.kts

dokkatoo {
  // run Dokka Generator in the current Gradle build process
  dokkaGeneratorIsolation.set(
    ClassLoaderIsolation()
  )
}

Alternatively, you can continue to use a separate process for Dokka, and specify the memory in the buildscript DSL:

// build.gradle.kts

dokkatoo {
  dokkaGeneratorIsolation.set(
    ProcessIsolation {
      debug.set(false)
      enableAssertions.set(true)
      minHeapSize.set("512m")
      maxHeapSize.set("1g")
      // ...
    }
  )
}

Recommendations

I am not an expert at all when it comes to Java memory usage or tuning!

• Dokkatoo itself uses the default JVM settings

• Gradle uses Dokkatoo v2.0.0 and sets Xmx=2g and Xms=512m https://github.com/gradle/gradle/blob/74b5468e20a009b1bdc532fd5c88bb94248d8a6b/build-logic/documentation/src/main/groovy/gradlebuild/docs/GradleKotlinDslReferencePlugin.java#L69-L74

• Apollo has a large number of subprojects, and recently updated Dokkattoo and nowuses classloader isolation https://github.com/apollographql/apollo-kotlin/blob/57e2978c855b25cf5de4ba4a0160cf7402b3f393/build-logic/src/main/kotlin/Publishing.kt#L66-L68

  Previously it set Xmx=8g(!) https://github.com/apollographql/apollo-kotlin/blob/7d100f3e1b258259a13a7eb85b59239e832661bb/build-logic/src/main/kotlin/Publishing.kt#L65-L67

[aSemy]

I have vague plans to create the documentation more thorough, and JVM args, particularly memory settings, would be a thing good to document.

[CLOVIS-AI]

Do you know if it would be possible to display the Dokka memory usage in a build scan? The memory usage for the Gradle daemon itself is included, I'm not sure if it's possible to add that information.

[aSemy]

Do you know if it would be possible to display the Dokka memory usage in a build scan?

I have no idea, but I think it's a good feature request for Gradle Build Scans!

[CLOVIS-AI]

Well, the great news is updating to Dokkatoo 2.1.0 fixed the OOM. Still no idea what it was caused by, but it's not that important now.

Please ping me if this info ever becomes available in logs/build scans :) I don't know your workflow with issues, but I got all the info I needed, so I think this can be closed?

[aSemy]

Good to hear!

I'm happy to leave this open for now in lieu of writing proper documentation.

I've also been wondering about instrumenting Dokka Generator and figuring out some statistics. It should be possible to inject OpenTelemetry automatically. Though I'm not sure if there's a nice way to view the metrics. It would be nice to be able to do so without spinning up Prometheus and Grafana.