はじめる前に

Confluence 11.0 introduces asynchronous macro execution, which allows eligible macros on a page to render in parallel rather than sequentially. On pages with multiple slow macros, this can reduce page load time.

What asynchronous macro execution does in Confluence 11.0

No macro bundled with Confluence is currently marked as safe to run in parallel. Only third-party macros whose vendors have explicitly marked them as safe can run asynchronously, and an administrator must also enable each macro individually.

On a standard Confluence 11.0 instance, enabling the feature has no visible effect.

Why the feature is experimental

Work is ongoing to ensure that macros can run safely in parallel in every situation. This includes reviewing Confluence macros and providing app vendors with the controls required to make their macros safe for concurrent execution. Apps that assume macros always run one at a time may behave incorrectly when asynchronous execution is enabled.

What is planned

In a future release, Confluence is expected to mark appropriate built-in macros as safe for parallel execution and provide app vendors with the tools needed to make their macros safe.

推奨事項

• Leave asynchronous macro execution disabled on production instances.

• Evaluate the feature on a test/staging instance

• Check with app vendors before enabling asynchronous execution for their macros.

How asynchronous macro execution works

By default, Confluence executes every macro sequentially on the Tomcat HTTP request thread. The browser waits for every macro to finish before receiving the page. A single slow macro, such as a Jira query, blog-posts roll-up, or contributors report, can delay the entire page for all users.

Asynchronous macro execution moves eligible macros to a dedicated thread pool. This allows them to run concurrently, frees the HTTP thread, and assembles macro results as they complete.

Confluence applies the following policies to each execution, in order of priority:

1. Cache hit: If the macro is cacheable and a valid result is already cached for the current user and parameters, Confluence returns the cached result without executing the macro.

2. Deduplication: If an identical execution is already in progress for the same macro, parameters, and user, the new request attaches to the existing execution and waits for its result. Confluence does not perform duplicate work.

3. New asynchronous execution: Confluence submits a new task to the thread pool and assigns it a unique execution ID.

Safe fallback: If the thread pool queue is full, or if the EWMA-smoothed queue latency exceeds the configured threshold while the queue depth exceeds the pool size, Confluence falls back to synchronous execution on the HTTP thread. Requests are not dropped.

Configure global flags

Global flags are Confluence site dark features. Confluence reads these flags dynamically, so a restart is not required after changing them.

1. Go to Administration ⚙️ > General Configuration > Dark Features (or open /admin/darkfeatures.action).

2. Enter the dark feature key in the text field and select submit.

Global controls cannot be set through the REST API or application code. Dark features and JVM system properties are the only supported configuration mechanisms.
 
 
 

Configure JVM system properties

Confluence reads these properties once at startup. Restart Confluence after changing any of them.

Thread pool

 Global execution limits

These values are fallback defaults when a macro does not have a per-macro override. A macro's own rateLimit or timeLimit takes precedence when configured.
 
  

 Result-cache size and time to live

Statistics retention

Configure macros via the REST API

After enabling the global flags, configure which macros can execute asynchronously. Configuration is persisted in Confluence plugin settings and takes effect immediately; a restart is not required.

If a macro plugin is disabled, an administrator cannot configure it for asynchronous execution. The plugin must be active when configuration is submitted.

Access: All endpoints require System Administrator credentials and WebSudo confirmation.

Base URL: {CONFLUENCE_BASE_URL}/rest/asyncmacros/latest

Configure a single macro

PUT /rest/asyncmacros/latest/execution-controls/
 
 { "macroName": "jira", "isAsync": true, "deduplication": true, "rateLimit": 10, "timeLimit": 60000 }

The endpoint returns 200 OK.

A 200 OK response confirms that the configuration was accepted and stored. It does not mean that the macro will run asynchronously.

Confluence accepts and stores isAsync: true even when the macro has not declared itself safe for concurrent execution. The setting has no effect until the macro supports asynchronous execution, and Confluence logs a warning.

To check whether the setting is effective, read the macro's configuration:
 

GET /rest/asyncmacros/latest/execution-controls/{macroName}

• supportedByMacro: true means that the macro declares itself safe and the isAsync setting takes effect.

• supportedByMacro: false means that the macro does not declare itself safe and the isAsync setting is stored but ignored.

In Confluence 11.0, supportedByMacro is false for every macro bundled with Confluence.

Configure multiple macros

PUT /rest/asyncmacros/latest/execution-controls/batch
 
 { "controls": 
	[ 
		{ "macroName": "blog-posts", "isAsync": true, "deduplication": false, "rateLimit": 50, "timeLimit": 120000 }, 
		{ "macroName": "contributors-summary", "isAsync": true, "deduplication": true, "rateLimit": 20, "timeLimit": 60000 }, 
		{ "macroName": "jira", "isAsync": true, "deduplication": true, "rateLimit": 100, "timeLimit": 30000 } 
	] 
}

The endpoint returns 204 No Content. Confluence validates all entries before saving. If validation fails, the endpoint returns 400 with details for all failing entries.

The Confluence-provided macros are candidates expected to benefit from asynchronous execution. But in Confluence 11.0, none declares itself safe for concurrent execution, so configuring these macros has no effect yet.

Request body fields

Partial updates: PUT merges with the existing configuration. Omitting a field preserves its current value.

Read current configuration

GET /rest/asyncmacros/latest/execution-controls?start=0&limit=25

The endpoint returns all configured macros in alphabetical order, with pagination.
 
 

GET /rest/asyncmacros/latest/execution-controls/{macroName}

The endpoint returns 404 if the macro is not configured.
 
 

GET /rest/asyncmacros/latest/execution-controls/by-names?macroNames=jira,blog-posts

This endpoint returns configuration for the listed macros.

Remove a macro's configuration

DELETE /rest/asyncmacros/latest/execution-controls/{macroName}

The endpoint returns 204 No Content. The macro reverts to synchronous execution.

Configure result caching

When caching is enabled, Confluence stores a macro result and reuses it for subsequent requests with the same inputs. This avoids redundant executions.

How the cache works

• Scope: The cache is local to each Confluence node and is not replicated across the cluster.

• Cache key: Macro parameters, macro body hash, and user ID. Results are private to each user.

• Time to live: Results expire after the configured write TTL, which defaults to 60 seconds.

• Cache hit: The macro does not execute; Confluence returns the cached string. Cache hits take priority over deduplication and new execution.

Prerequisites

Both conditions must be true for caching to work:

1. Enable the global dark feature atlassian.macros.async.execution.caching.

2. The macro's Java implementation must return true from isCacheable().

The administrator configures the first condition. The macro developer configures the second. The isCacheable value is visible as a read-only field in the GET /execution-controls/{macroName} response.

Considerations before enabling caching

• Node-local cache: Users accessing different cluster nodes have separate caches. Results can differ between nodes during the TTL window.

• Heap impact: Each entry stores a rendered macro output string. Large caches and outputs can increase garbage-collection pressure.

• Deterministic output: Cache only macros that produce deterministic output for the same parameters, body, and user.

• Staleness: With the default 60-second TTL, users may see results that are up to one minute old. Adjust atlassian.macros.result.cache.expire.after.write.millis according to how often the underlying data changes.