This is an automated email from the ASF dual-hosted git repository.
cschneider pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-distribution-journal.git
The following commit(s) were added to refs/heads/master by this push:
new 5e1bed8 Document metrics
5e1bed8 is described below
commit 5e1bed8df7f15a2470edc56eecea181e85db57ee
Author: Christian Schneider <[email protected]>
AuthorDate: Wed Jan 14 10:20:40 2026 +0100
Document metrics
---
README.md | 28 +++++
docs/metrics_overview.md | 268 +++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 296 insertions(+)
diff --git a/README.md b/README.md
index ec736fa..2fb2b8f 100644
--- a/README.md
+++ b/README.md
@@ -6,3 +6,31 @@
This module is part of the [Apache Sling](https://sling.apache.org) project,
it implements [Apache Sling Content
Distribution](https://sling.apache.org/documentation/bundles/content-distribution.html)
agents on a message journal.
Please refer to the [documentation](docs/documentation.md) to learn about the
use case and general design.
+
+## Metrics
+
+This bundle exposes comprehensive metrics for monitoring publisher and
subscriber operations. All metrics are exposed through the Apache Sling Metrics
Service. Metric names use underscores instead of dots and are prefixed with
`sling_`.
+
+### Publisher Metrics
+
+Publisher metrics (prefixed with `sling_distribution_journal_publisher_`)
track package export, request handling, package building, queue operations, and
subscriber discovery:
+- **Package Export**:
`sling_distribution_journal_publisher_exported_package_size` (histogram)
+- **Request Handling**:
`sling_distribution_journal_publisher_accepted_requests`,
`sling_distribution_journal_publisher_dropped_requests` (meters)
+- **Package Building**:
`sling_distribution_journal_publisher_build_package_duration`,
`sling_distribution_journal_publisher_enqueue_package_duration` (timers)
+- **Queue Operations**: `sling_distribution_journal_publisher_queue_size`
(gauge), `sling_distribution_journal_publisher_queue_cache_fetch_count`,
`sling_distribution_journal_publisher_queue_access_error_count` (counters)
+- **Subscriber Discovery**:
`sling_distribution_journal_publisher_subscriber_count` (gauge)
+
+### Subscriber Metrics
+
+Subscriber metrics (prefixed with `sling_distribution_journal_subscriber_`)
track package import, processing, errors, and distribution duration:
+- **Package Import**:
`sling_distribution_journal_subscriber_imported_package_size`,
`sling_distribution_journal_subscriber_imported_package_duration`,
`sling_distribution_journal_subscriber_current_import_duration`
(histogram/timer/gauge)
+- **Package Status**:
`sling_distribution_journal_subscriber_package_status_count` (counter) with
status tags (IMPORTED, REMOVED, REMOVED_FAILED)
+- **Error Tracking**:
`sling_distribution_journal_subscriber_transient_import_errors`,
`sling_distribution_journal_subscriber_permanent_import_errors`,
`sling_distribution_journal_subscriber_import_errors`,
`sling_distribution_journal_subscriber_current_retries` (counters/gauge)
+- **Processing**: Pre/post-processing and installation metrics
(counters/timers)
+- **Distribution Duration**:
`sling_distribution_journal_subscriber_request_distributed_duration`,
`sling_distribution_journal_subscriber_package_journal_distribution_duration`
(timers)
+- **Readiness**: `sling_distribution_journal_subscriber_readiness_duration`
(timer) with ready reason tags
+- **FileVault**: `sling_distribution_journal_subscriber_fv_message_count`,
`sling_distribution_journal_subscriber_fv_error_count` (counters)
+
+All metrics are tagged with `sub_name`/`pub_name` and `editable` (for
subscriber metrics) to enable filtering and aggregation.
+
+For a complete list of all metrics with detailed descriptions, see the
[Metrics Overview](docs/METRICS_OVERVIEW.md).
diff --git a/docs/metrics_overview.md b/docs/metrics_overview.md
new file mode 100644
index 0000000..395e7f2
--- /dev/null
+++ b/docs/metrics_overview.md
@@ -0,0 +1,268 @@
+# Metrics Overview
+
+This document provides a comprehensive overview of all metrics in the Apache
Sling Distribution Journal bundle, organized by publisher and subscriber
components.
+
+## Publisher Metrics
+
+All publisher metrics are prefixed with
`sling_distribution_journal_publisher_` and include the following tag:
+- `pub_name`: Name of the publish agent
+
+### Package Export Metrics
+
+#### `sling_distribution_journal_publisher_exported_package_size` (Histogram)
+- **Type**: Histogram
+- **Unit**: Bytes
+- **Description**: Histogram of the exported content package size in bytes
+- **Tags**: `pub_name`
+
+### Request Metrics
+
+#### `sling_distribution_journal_publisher_accepted_requests` (Meter)
+- **Type**: Meter
+- **Description**: Rate of requests returning a
`DistributionRequestState.ACCEPTED` state
+- **Tags**: `pub_name`
+
+#### `sling_distribution_journal_publisher_dropped_requests` (Meter)
+- **Type**: Meter
+- **Description**: Rate of requests returning a
`DistributionRequestState.DROPPED` state
+- **Tags**: `pub_name`
+
+### Package Building Metrics
+
+#### `sling_distribution_journal_publisher_build_package_duration` (Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of building a content package
+- **Tags**: `pub_name`
+
+#### `sling_distribution_journal_publisher_enqueue_package_duration` (Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of adding a package to the queue
+- **Tags**: `pub_name`
+
+### Queue Metrics
+
+#### `sling_distribution_journal_publisher_queue_size` (Gauge)
+- **Type**: Gauge
+- **Description**: Current size of the queue (maximum queue size)
+- **Tags**: `pub_name`
+
+#### `sling_distribution_journal_publisher_queue_cache_fetch_count` (Counter)
+- **Type**: Counter
+- **Description**: Count of fetch operations to feed the queue cache
+- **Tags**: `pub_name`
+
+#### `sling_distribution_journal_publisher_queue_access_error_count` (Counter)
+- **Type**: Counter
+- **Description**: Count of queue access errors
+- **Tags**: `pub_name`
+
+### Subscriber Discovery Metrics
+
+#### `sling_distribution_journal_publisher_subscriber_count` (Gauge)
+- **Type**: Gauge
+- **Description**: Current number of subscribers for this publisher
+- **Tags**: `pub_name`
+
+---
+
+## Subscriber Metrics
+
+All subscriber metrics are prefixed with
`sling_distribution_journal_subscriber_` and typically include the following
tags:
+- `sub_name`: Name of the subscriber agent
+- `pub_name`: Name of the subscribed publish agent (first only if more than
one)
+- `editable`: Whether the queue is editable (true/false)
+
+### Package Import Metrics
+
+#### `sling_distribution_journal_subscriber_imported_package_size` (Histogram)
+- **Type**: Histogram
+- **Unit**: Bytes
+- **Description**: Histogram of the imported content package size in bytes
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_imported_package_duration` (Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of successful package import operations
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_current_import_duration` (Gauge)
+- **Type**: Gauge
+- **Unit**: Milliseconds
+- **Description**: Current duration of the package import operation in
progress (0 if no import is currently happening)
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_failed_package_imports` (Meter)
+- **Type**: Meter
+- **Description**: Rate of failures to import packages (increased on every
failure to apply a package)
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+### Package Removal Metrics
+
+#### `sling_distribution_journal_subscriber_removed_package_duration` (Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of packages successfully removed from an editable
subscriber
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_removed_failed_package_duration`
(Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of packages successfully removed automatically
from a subscriber supporting error queue
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+### Package Status Metrics
+
+#### `sling_distribution_journal_subscriber_package_status_count` (Counter)
+- **Type**: Counter
+- **Description**: Counter for all the different package statuses. Tracks the
number of packages that reached each status
+- **Tags**: `sub_name`, `pub_name`, `editable`, `status`
+- **Status Values**:
+ - `IMPORTED`: Package was successfully imported
+ - `REMOVED`: Package was successfully removed from an editable subscriber
+ - `REMOVED_FAILED`: Package failed and was removed from error queue
+
+### Error Metrics
+
+#### `sling_distribution_journal_subscriber_transient_import_errors` (Counter)
+- **Type**: Counter
+- **Description**: Count of packages that failed before but then succeeded
(transient errors that were eventually resolved)
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_permanent_import_errors` (Counter)
+- **Type**: Counter
+- **Description**: Count of permanent import errors (only counted in error
queue setup)
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_import_errors` (Counter)
+- **Type**: Counter
+- **Description**: Count of packages that failed more than n times and thus
caused a blocked queue (blocking import errors)
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_current_retries` (Gauge)
+- **Type**: Gauge
+- **Description**: Number of packages with at least one failure to apply
(current retry count)
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+### Processing Metrics
+
+#### `sling_distribution_journal_subscriber_import_pre_process_request_count`
(Counter)
+- **Type**: Counter
+- **Description**: Number of import pre-processing requests
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_import_pre_process_success_count`
(Counter)
+- **Type**: Counter
+- **Description**: Number of successful import pre-processing operations
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_import_pre_process_duration`
(Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of import pre-processing operations
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_import_post_process_request_count`
(Counter)
+- **Type**: Counter
+- **Description**: Number of import post-processing requests
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_import_post_process_success_count`
(Counter)
+- **Type**: Counter
+- **Description**: Number of successful import post-processing operations
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_import_post_process_duration`
(Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of import post-processing operations
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_package_install_count` (Counter)
+- **Type**: Counter
+- **Description**: Number of package installation operations
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_package_install_duration` (Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of package installation operations
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+### Invalidation Metrics
+
+####
`sling_distribution_journal_subscriber_invalidation_process_request_count`
(Counter)
+- **Type**: Counter
+- **Description**: Number of invalidation process requests
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+####
`sling_distribution_journal_subscriber_invalidation_process_success_count`
(Counter)
+- **Type**: Counter
+- **Description**: Number of successful invalidation process operations
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_invalidation_process_duration`
(Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of invalidation process operations
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+### Distribution Duration Metrics
+
+#### `sling_distribution_journal_subscriber_request_distributed_duration`
(Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of distributing a distribution package. The timer
starts when the package is enqueued and stops when the package is successfully
imported
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+####
`sling_distribution_journal_subscriber_package_journal_distribution_duration`
(Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration that a package spent in the distribution journal.
The timer starts when the package is enqueued and stops when the package is
consumed
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+### Status Reporting Metrics
+
+#### `sling_distribution_journal_subscriber_send_stored_status_duration`
(Timer)
+- **Type**: Timer
+- **Unit**: Milliseconds
+- **Description**: Duration of sending a stored package status
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+### Readiness Metrics
+
+#### `sling_distribution_journal_subscriber_readiness_duration` (Timer)
+- **Type**: Timer
+- **Unit**: Seconds
+- **Description**: Duration until the subscriber becomes ready, categorized by
the reason for readiness
+- **Tags**: `sub_name`, `pub_name`, `editable`, `ready_reason`
+- **Ready Reason Values**:
+ - `IDLE`: Subscriber became ready after being idle for a configured duration
+ - `MAX_RETRIES`: Subscriber became ready because retries exceeded maximum
+ - `LATENCY`: Subscriber became ready because package message latency was
below acceptable limit
+ - `FORCE`: Subscriber became ready due to forced readiness after timeout
+
+### FileVault (FV) Metrics
+
+#### `sling_distribution_journal_subscriber_fv_message_count` (Counter)
+- **Type**: Counter
+- **Description**: Count of FileVault progress messages during package
import/extraction operations. FileVault (Apache Jackrabbit FileVault) is used
for installing content packages.
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+#### `sling_distribution_journal_subscriber_fv_error_count` (Counter)
+- **Type**: Counter
+- **Description**: Count of FileVault errors encountered during package
import/extraction operations
+- **Tags**: `sub_name`, `pub_name`, `editable`
+
+---
+
+## Metric Types Reference
+
+- **Counter**: A cumulative metric that represents a single monotonically
increasing counter
+- **Gauge**: A metric that represents a single numerical value that can
arbitrarily go up and down
+- **Histogram**: A metric that samples observations and counts them in
configurable buckets
+- **Meter**: A metric that measures the rate of events over time
+- **Timer**: A metric that measures both the rate that a particular piece of
code is called and the distribution of its duration
+
