Skip to main content
Version: NG-2.16

Apache Karaf

Introduction​

Apache Karaf O11ySource monitors the health, performance, and security of Apache Karaf OSGi runtime instances deployements in enterprise environments. It delivers production-ready dashboards and alerts into vuSmartMaps

Getting Started​

Compatibility​

The Apache Karaf O11ySource supports monitoring Apache Karaf versions 4.4.6 and later. Java 11 or later is required. PAX Logging (Log4j2) must be active.

Apache Karaf VersionSupportNotes4.4.6SupportedOnly version in estate; validated end-to-end; Java 11+ required; PAX Logging (Log4j2)4.3.xPartialMBean structure equivalent for v1 domains; Karaf system MBean attributes may differ — not confirmed4.2.xNot supportedLog4j1 default PAX backend requires different log config; not tested Java RuntimeSupportJava 11Required minimumJava 17 / 21Compatible (HotSpot MBeans intact; verify GC collector names if GC algorithm changes)

Data Collection Method​

vuSmartMaps collects Apache Karaf metrics and logs using VuNet's Healthbeat and Logbeat agents. Healthbeat collects metrics, while Logbeat collects Apache Karaf logs.

Prerequisites​

Dependent Configuration​

To configure this O11ySource, create a 'credential' of type 'user' under the 'Definition' tab.

Inputs for Configuring Data Source​

  • Karaf Host / IP: IP address or FQDN of the Apache Karaf instance. This becomes the monitored target identifier.
  • Polling Interval [seconds]: How frequently Healthbeat polls Jolokia and exec helpers. Use 60 seconds unless the deployment requires a slower interval.
  • Jolokia Host / IP: Host or IP where the Karaf Jolokia HTTP endpoint is reachable. Usually the same value as Karaf Host / IP.
  • Jolokia Port: TCP port for the Karaf Jolokia JVM agent.
  • Jolokia Credentials: Optional credentials when Jolokia basic authentication is enabled. Leave empty only when Jolokia is intentionally unauthenticated.
  • karaf Log Path: Full path to the Karaf application log consumed by vuSmartMaps
  • Audit Log Path: Full path to audit.log. Add the PAX audit logger block before enabling this collection.
  • Access Log Path: Full path to access.log. Add the PAX access logger block before enabling this collection.
  • Admin Log Path: Full path to admin.log. Add the PAX admin logger block before enabling this collection.

Firewall Requirement​

To collect data from this O11ySource, ensure the following ports are opened:

Source IPDestination IPDestination PortProtocolDirection
IP address of the Apache Karaf serverData Collector End Point9092/9094(SSL)*TCPInbound

*Before providing the firewall requirements, please update the port based on the customer environment.

Configuring the Target​

Step 1 — Enable the Jolokia JVM agent
Download the Jolokia JVM agent jar to the Karaf host:

wget https://repo1.maven.org/maven2/org/jolokia/jolokia-jvm/1.7.2/jolokia-jvm-1.7.2-agent.jar -O /opt/karaf/lib/jolokia-jvm-agent.jar


Add the Jolokia agent to Karaf JVM options in /opt/karaf/bin/setenv:

```bash
export EXTRA_JAVA_OPTS="-javaagent:/opt/karaf/lib/jolokia-jvm-agent.jar=protocol=http,host=0.0.0.0,port=8790,discoveryEnabled=false"

Restart Karaf and verify the Jolokia endpoint:

curl http://<karaf-host>:8790/jolokia/version

Step 2 — Configure PAX Logging for additional log files Append the following appender configuration to /opt/karaf/etc/org.ops4j.pax.logging.cfg to enable audit, access, and admin log files:

log4j2.appender.audit.type = RollingFile
log4j2.appender.audit.name = AuditRollingFile
log4j2.appender.audit.fileName = $\{karaf.data\}/log/audit.log
log4j2.appender.audit.filePattern = $\{karaf.data\}/log/audit.log.%i
log4j2.appender.audit.layout.type = PatternLayout
log4j2.appender.audit.layout.pattern = %d\{ISO8601\} | %5p | %m%n

No Karaf restart is required for PAX Logging configuration changes. Log files appear after the first matching event. Step 3 — Install Python 3 on the Karaf host The bundle-state and feature-state collection scripts run on the Karaf host and call Jolokia over HTTP. Python 3 must be installed:

python3 --version

Step 4 — Configure the source in vuSmartMaps In the source form, provide:

  • Karaf Host / IP* — hostname or IP of the Karaf instance
  • Jolokia Host / IP* — Jolokia HTTP endpoint host (defaults to Karaf host)
  • Jolokia Port* — Jolokia HTTP port (default: 8790)
  • Username / Password* — optional Jolokia credentials
  • Polling Interval* — how often metrics are collected
  • Log File Paths* — paths to karaf.log, audit.log, admin.log, and access.log
### Configuration Steps
- Enable the Apache Karaf O11ySource.
- Select the Sources tab and press the **``+``** button to add a new Apache Karaf host to be monitored.
- Set up metrics and log collection configurations. Afterwards, select **``Save and Continue``** to proceed with downloading the Healthbeat and Logbeat agent.
- The following packages will be available for download based on the OS:Download <OS> Healthbeat Installation Binary - Downloads the full Healthbeat package with required configurations for a fresh installationDownload <OS> Healthbeat Update Configuration Binary - Downloads the agent configuration package to update an existing Healthbeat installationDownload <OS> Logbeat Installation Binary - Downloads the full Logbeat package with required configurations for a fresh installationDownload <OS> Logbeat Update Configuration Binary - Downloads the agent configuration package to update an existing Logbeat installation
- Download the agent installation or update package, then click **``Finish``** to close the data source window.
## Metrics Collected
| Name | Description | Data Type |
|------|-------------|-----------|
| timestamp | Event time normalized from epoch milliseconds by the materialized view. | DateTime64(3) |
| doc_type | Discriminator for metric family such as karaf_jvm_memory, karaf_jvm_gc, karaf_feature, or karaf_bundle. | LowCardinality(String) |
| target | Karaf instance identifier derived from input tags.host; first dashboard variable. | LowCardinality(String) |
| o11ysource_name | Constant value Apache Karaf added by the metrics ContextStream pipeline. | LowCardinality(String) |
| topic_name | Source topic marker in the output payload. Current sample value remains apache-karaf-metrics-input; Kafka engine consumes output topic apache-karaf-metrics. | LowCardinality(String) |
| tenant_id | Tenant identifier added by Healthbeat fields_under_root; constant 1 in testlab. | LowCardinality(String) |
| bu_id | Business unit identifier added by Healthbeat fields_under_root; constant 1 in testlab. | LowCardinality(String) |
| start_time_ms | JVM start time in epoch milliseconds. | Nullable(Float64) |
| uptime_ms | JVM uptime in milliseconds; Karaf system MBean uptime is not available in 4.4.6. | Nullable(Float64) |
| total_compilation_time_ms | Cumulative JIT compilation time in milliseconds. | Nullable(Float64) |
| gc_young_collection_time | Cumulative G1 Young Generation GC pause time in milliseconds. | Nullable(Float64) |
| gc_young_collection_count | Cumulative G1 Young Generation GC cycle count. | Nullable(Int64) |
| gc_old_collection_time | Cumulative G1 Old Generation GC pause time in milliseconds. | Nullable(Float64) |
| gc_old_collection_count | Cumulative G1 Old Generation GC cycle count. | Nullable(Int64) |
| heap_memory_usage_committed | Heap memory committed by the JVM. | Nullable(Int64) |
| heap_memory_usage_init | Initial heap requested at JVM start. | Nullable(Int64) |
| heap_memory_usage_max | Maximum heap size and denominator for heap utilization. | Nullable(Int64) |
| heap_memory_usage_used | Heap memory currently used by live objects. | Nullable(Int64) |
| non_heap_memory_usage_committed | Non-heap memory committed by the JVM. | Nullable(Int64) |
| non_heap_memory_usage_init | Initial non-heap requested at JVM start. | Nullable(Int64) |
| non_heap_memory_usage_max | Maximum non-heap value; sample shows -1 for unlimited Metaspace. | Nullable(Int64) |
| non_heap_memory_usage_used | Non-heap memory used, mainly Metaspace and JIT code. | Nullable(Int64) |
| daemon_thread_count | Current daemon thread count. | Nullable(Int32) |
| peak_thread_count | Peak live thread count since JVM start or last reset. | Nullable(Int32) |
| thread_count | Current live thread count. | Nullable(Int32) |
| total_started_thread_count | Cumulative threads ever started. | Nullable(Int64) |
| available_processors | Logical processors available to the JVM. | Nullable(Int32) |
| free_physical_memory_bytes | Free host physical memory in bytes. | Nullable(Int64) |
| free_swap_space_bytes | Free swap space in bytes. | Nullable(Int64) |
| max_file_descriptor_count | JVM process file descriptor limit. | Nullable(Int64) |
| open_file_descriptor_count | Open file descriptors held by the JVM process. | Nullable(Int64) |
| process_cpu_load | JVM process CPU load ratio from 0.0 to 1.0. | Nullable(Float64) |
| system_cpu_load | Whole-host CPU load ratio from 0.0 to 1.0. | Nullable(Float64) |
| system_load_average | 1-minute OS load average. | Nullable(Float64) |
| total_physical_memory_bytes | Total host physical memory in bytes. | Nullable(Int64) |
| total_swap_space_bytes | Total swap space in bytes. | Nullable(Int64) |
| loaded_class_count | Classes currently loaded. | Nullable(Int32) |
| total_loaded_class_count | Cumulative classes loaded since JVM start. | Nullable(Int64) |
| unloaded_class_count | Cumulative classes unloaded since JVM start. | Nullable(Int64) |
| karaf_framework | Framework implementation, sample value felix. | LowCardinality(String) |
| karaf_start_level | Karaf framework start level, sample value 100. | Nullable(Int32) |
| karaf_version | Karaf version string, sample value 4.4.6. | String |
| feature_count_installed | Count of currently installed Karaf features. | Nullable(Int32) |
| feature_count_total | Total known features in the repository. | Nullable(Int32) |
| feature_count_uninstalled | Derived count of features not installed. | Nullable(Int32) |
| bundle_count_active | Bundles currently ACTIVE. | Nullable(Int32) |
| bundle_count_installed | Bundles stuck INSTALLED. | Nullable(Int32) |
| bundle_count_resolved | Bundles RESOLVED but not active. | Nullable(Int32) |
| bundle_count_starting | Bundles currently STARTING. | Nullable(Int32) |
| bundle_count_stopping | Bundles currently STOPPING. | Nullable(Int32) |
| bundle_count_total | Total bundles registered in framework. | Nullable(Int32) |
| timestamp | Event timestamp of the log entry with millisecond precision. | DateTime64(3) |
| log_timestamp | Raw timestamp string as extracted from the log line. | String |
| log_collection_time | Time when the log entry was collected by the agent. | String |
| target | Hostname or IP of the Karaf instance that generated the log. | LowCardinality(String) |
| doc_type | Document type identifier used for pipeline routing. | LowCardinality(String) |
| log_type | Log file type: karaf-application, karaf-audit, karaf-access, or karaf-admin. | LowCardinality(String) |
| log_level | Severity level of the log entry (INFO, WARN, ERROR, FATAL, DEBUG). | LowCardinality(String) |
| log_file_path | Path of the log file on the Karaf host. | String |
| log_message | Parsed log message body extracted from the log line. | String |
| service_name | Service or application name associated with the log entry. | LowCardinality(String) |
| o11ysource_name | Name of the O11ySource that collected this log entry. | LowCardinality(String) |
| host_hostname | Full hostname of the server where the Karaf instance is running. | String |
| host_os_platform | Operating system platform of the Karaf host. | LowCardinality(String) |
| host_os_version | OS version of the Karaf host. | String |
| host_architecture | CPU architecture of the Karaf host. | String |
| host_id | Unique identifier of the Karaf host. | String |
| agent_type | Type of collection agent (e.g., filebeat). | LowCardinality(String) |
| agent_version | Version of the collection agent. | LowCardinality(String) |
| log_offset | Byte offset of the log entry in the source file. | Int64 |
| log_component | OSGi bundle or Java class that emitted the log entry. | String |
| thread_name | JVM thread name that produced the log entry. | String |
| log_class | Java class name associated with the log entry. | String |
| bundle_info | OSGi bundle identifier and version extracted from the log entry. | String |
| http_method | HTTP method for access log entries (GET, POST, etc.). | LowCardinality(String) |
| http_path | HTTP request path for access log entries. | String |
| http_status | HTTP response status code for access log entries. | LowCardinality(String) |
| response_bytes | Number of bytes in the HTTP response body. | Int64 |
| client_ip | Client IP address for access log and admin log entries. | String |
| auth_user | Authenticated username for audit and admin log entries. | String |
| message | Raw full log line preserved for search and drill-down. | String |