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 IP	Destination IP	Destination Port	Protocol	Direction
IP address of the Apache Karaf server	Data Collector End Point	9092/9094(SSL)*	TCP	Inbound

*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:

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 |

Introduction​

Getting Started​

Compatibility​

Data Collection Method​

Prerequisites​

Dependent Configuration​

Inputs for Configuring Data Source​

Firewall Requirement​

Configuring the Target​