| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| // |
| |
| === Collectors |
| |
| Decanter collectors harvest the monitoring data, and send this data to the Decanter appenders. |
| |
| Two kinds of collector are available: |
| |
| * Event Driven Collectors react to events and "broadcast" the data to the appenders. |
| * Polled Collectors are periodically executed by the Decanter Scheduler. When executed, the collectors harvest the |
| data and send to the appenders. |
| |
| ==== Log |
| |
| The Decanter Log Collector is an event driven collector. It automatically reacts when a log occurs, and |
| send the log details (level, logger name, message, etc) to the appenders. |
| |
| The `decanter-collector-log` feature installs the log collector: |
| |
| ---- |
| karaf@root()> feature:install decanter-collector-log |
| ---- |
| |
| The log collector doesn't need any configuration, the installation of the decanter-collector-log feature is enough. |
| |
| [NOTE] |
| ===================================================================== |
| The Decanter log collector is using `osgi:DecanterLogCollectorAppender` appender. |
| In order to work, your Apache Karaf Pax Logging configuration should contain this appender. |
| |
| The default Apache Karaf `etc/org.ops4j.pax.logging.cfg` configuration file is already fine: |
| |
| ---- |
| log4j.rootLogger = DEBUG, out, osgi:* |
| ---- |
| |
| If you want, you can explicitly specify the `DecanterLogCollectorAppender` appender: |
| |
| ---- |
| log4j.rootLogger = DEBUG, out, osgi:DecanterLogCollectorAppender, osgi:VmLogAppender |
| ---- |
| |
| ===================================================================== |
| |
| ==== Log Socket |
| |
| The Decanter Log Socket Collector is an event driven collector. It creates a socket, waiting for incoming event. The expected |
| events are log4j LoggingEvent. The log4j LoggingEvent is transformed as a Map containing the log details (level, logger name, message, ...). |
| This Map is sent to the appenders. |
| |
| The collector allows you to remotely use Decanter. For instance, you can have an application running on a different platform (spring-boot, |
| application servers, ...). This application can use a log4j socket appender that send the logging events to the Decanter |
| log socket collector. |
| |
| The `decanter-collector-log-socket` feature install the log socket collector: |
| |
| ---- |
| karaf@root()> feature:install decanter-collector-log-socket |
| ---- |
| |
| This feature installs the collector and a default `etc/org.apache.karaf.decanter.collector.log.socket.cfg` configuration file |
| containing: |
| |
| ---- |
| # |
| # Decanter Log/Log4j Socket collector configuration |
| # |
| |
| #port=4560 |
| #workers=10 |
| |
| ---- |
| |
| * the `port` property defines the port number where the collector is bound and listen for incoming logging event. Default is 4560. |
| * the `workers` properties defines the number of threads (workers) which can deal with multiple clients in the same time. |
| |
| ==== File |
| |
| The Decanter File Collector is an event driven collector. It automatically reacts when new lines are appended into |
| a file (especially a log file). It acts like the tail Unix command. Basically, it's an alternative to the log collector. |
| The log collector reacts for local Karaf log messages, whereas the file collector can react to any files, included log |
| file from other system than Karaf. It means that you can monitor and send collected data for any system (even not Java |
| base, or whatever). |
| |
| The file collector deals with file rotation, file not found. |
| |
| The `decanter-collector-file` feature installs the file collector: |
| |
| ---- |
| karaf@root()> feature:install decanter-collector-file |
| ---- |
| |
| Now, you have to create a configuration file for each file that you want to monitor. In the etc folder, you have to |
| create a file with the following format name `etc/org.apache.karaf.decanter.collector.file-ID.cfg` where ID is an ID |
| of your choice. |
| |
| This file contains: |
| |
| ---- |
| type=my |
| path=/path/to/file |
| any=value |
| ---- |
| |
| * `type` is an ID (mandatory) that allows you to easily identify the monitored file |
| * `path` is the location of the file that you want to monitore |
| * all other values (like `any`) will be part of the collected data. It means that you can add your own custom data, and |
| easily create queries bases on this data. |
| |
| For instance, instead of the log collector, you can create the following `etc/org.apache.karaf.decanter.collector.file-karaf.cfg` |
| file collector configuration file: |
| |
| ---- |
| type=karaf-log-file |
| path=/path/to/karaf/data/log/karaf.log |
| my=stuff |
| ---- |
| |
| The file collector will tail on karaf.log file, and send any new line in this log file as collected data. |
| |
| ==== EventAdmin |
| |
| The Decanter EventAdmin Collector is an event-driven collector, listening for all internal events happening in |
| the Apache Karaf Container. |
| |
| [NOTE] |
| ================================================ |
| It's the perfect way to audit all actions performed on resources (features, bundles, configurations, ...) by users |
| (via local shell console, SSH, or JMX). |
| |
| We recommend to use this collector to implement users and actions auditing. |
| ================================================ |
| |
| The `decanter-collector-eventadmin` feature installs the eventadmin collector: |
| |
| ---- |
| karaf@root()> feature:install decanter-collector-eventadmin |
| ---- |
| |
| By default, the eventadmin collector is listening for all OSGi framework and Karaf internal events. |
| |
| You can specify additional events to trap by providing a `etc/org.apache.karaf.decanter.collector.eventadmin-my.cfg' configuration |
| file, containing the EventAdmin topics you want to listen: |
| |
| ---- |
| event.topics=my/* |
| ---- |
| |
| [NOTE] |
| ================================================ |
| By default, the events contain timestamp and subject. |
| You can disable this by modifying `etc/org.apache.felix.eventadmin.impl.EventAdmin` configuration file: |
| |
| ---- |
| org.apache.felix.eventadmin.AddTimestamp=true |
| org.apache.felix.eventadmin.AddSubject=true |
| ---- |
| ================================================ |
| |
| ==== JMX |
| |
| The Decanter JMX Collector is a polled collector, executed periodically by the Decanter Scheduler. |
| |
| The JMX collector connects to a JMX MBeanServer (local or remote), and retrieves all attributes of each available MBeans. |
| The JMX metrics (attribute values) are send to the appenders. |
| |
| The `decanter-collector-jmx` feature installs the JMX collector, and a default configuration file: |
| |
| ---- |
| karaf@root()> feature:install decanter-collector-jmx |
| ---- |
| |
| This feature brings a `etc/org.apache.karaf.decanter.collector.jmx-local.cfg` configuration file containing: |
| |
| ---- |
| # |
| # Decanter Local JMX collector configuration |
| # |
| |
| # Name/type of the JMX collection |
| type=jmx-local |
| |
| # URL of the JMX MBeanServer. |
| # local keyword means the local platform MBeanServer or you can specify to full JMX URL |
| # like service:jmx:rmi:///jndi/rmi://hostname:port/karaf-instance |
| url=local |
| |
| # Username to connect to the JMX MBeanServer |
| #username=karaf |
| |
| # Password to connect to the JMX MBeanServer |
| #password=karaf |
| |
| # Object name filter to use. Instead of harvesting all MBeans, you can select only |
| # some MBeans matching the object name filter |
| #object.name=org.apache.camel:context=*,type=routes,name=* |
| ---- |
| |
| This file harvests the data of the local MBeanServer: |
| |
| * the `type` property is a name (of your choice) allowing you to easily identify the harvested data |
| * the `url` property is the MBeanServer to connect. "local" is reserved keyword to specify the local MBeanServer. |
| Instead of "local", you can use the JMX service URL. For instance, for Karaf version 3.0.0, 3.0.1, 3.0.2, and 3.0.3, |
| as the local MBeanServer is secured, you can specify `service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root`. You |
| can also polled any remote MBean server (Karaf based or not) providing the service URL. |
| * the `username` property contains the username to connect to the MBean server. It's only required if the MBean server |
| is secured. |
| * the `password` property contains the password to connect to the MBean server. It's only required if the MBean server |
| is secured. |
| * the `object.name` property is optional. If this property is not specified, the collector will retrieve the attributes |
| of all MBeans. You can filter to consider only some MBeans. This property contains the ObjectName filter to retrieve |
| the attributes only to some MBeans. |
| * any other values will be part of the collected data. It means that you can add your own property if you want to add |
| additional data, and create queries based on this data. |
| |
| You can retrieve multiple MBean servers. For that, you just create a new configuration file using the file name format |
| `etc/org.apache.karaf.decanter.collector.jmx-[ANYNAME].cfg`. |
| |
| ==== ActiveMQ (JMX) |
| |
| The ActiveMQ JMX collector is just a special configuration of the JMX collector. |
| |
| The `decanter-collector-activemq` feature installs the default JMX collector, with the specific ActiveMQ JMX configuration: |
| |
| ---- |
| karaf@root()> feature:install decanter-collector-activemq |
| ---- |
| |
| This feature installs the same collector as the `decanter-collector-jmx`, but also add the |
| `etc/org.apache.karaf.decanter.collector.jmx-activemq.cfg` configuration file. |
| |
| This file contains: |
| |
| ---- |
| # |
| # Decanter Local ActiveMQ JMX collector configuration |
| # |
| |
| # Name/type of the JMX collection |
| type=jmx-activemq |
| |
| # URL of the JMX MBeanServer. |
| # local keyword means the local platform MBeanServer or you can specify to full JMX URL |
| # like service:jmx:rmi:///jndi/rmi://hostname:port/karaf-instance |
| url=local |
| |
| # Username to connect to the JMX MBeanServer |
| #username=karaf |
| |
| # Password to connect to the JMX MBeanServer |
| #password=karaf |
| |
| # Object name filter to use. Instead of harvesting all MBeans, you can select only |
| # some MBeans matching the object name filter |
| object.name=org.apache.activemq:* |
| ---- |
| |
| This configuration actually contains a filter to retrieve only the ActiveMQ JMX MBeans. |
| |
| ==== Camel (JMX) |
| |
| The Camel JMX collector is just a special configuration of the JMX collector. |
| |
| The `decanter-collector-camel` feature installs the default JMX collector, with the specific Camel JMX configuration: |
| |
| ---- |
| karaf@root()> feature:install decanter-collector-camel |
| ---- |
| |
| This feature installs the same collector as the `decanter-collector-jmx`, but also add the |
| `etc/org.apache.karaf.decanter.collector.jmx-camel.cfg` configuration file. |
| |
| This file contains: |
| |
| ---- |
| # |
| # Decanter Local Camel JMX collector configuration |
| # |
| |
| # Name/type of the JMX collection |
| type=jmx-camel |
| |
| # URL of the JMX MBeanServer. |
| # local keyword means the local platform MBeanServer or you can specify to full JMX URL |
| # like service:jmx:rmi:///jndi/rmi://hostname:port/karaf-instance |
| url=local |
| |
| # Username to connect to the JMX MBeanServer |
| #username=karaf |
| |
| # Password to connect to the JMX MBeanServer |
| #password=karaf |
| |
| # Object name filter to use. Instead of harvesting all MBeans, you can select only |
| # some MBeans matching the object name filter |
| object.name=org.apache.camel:context=*,type=routes,name=* |
| ---- |
| |
| This configuration actually contains a filter to retrieve only the Camel Routes JMX MBeans. |
| |
| ==== Camel Tracer |
| |
| The Camel Tracer provides a Camel Tracer Handler that you can set on a Camel Tracer. |
| |
| If you enable the tracer on a Camel route, all tracer events (exchanges on each step of the route) are send to the |
| appenders. |
| |
| The `decanter-collector-camel-tracer` feature provides the Camel Tracer Handler: |
| |
| ---- |
| karaf@root()> feature:install decanter-collector-camel-tracer |
| ---- |
| |
| Now, you can use the Decanter Camel Tracer Handler in a tracer that you can use in routes. |
| |
| For instance, the following route definition shows how to enable tracer on a route, and use the Decanter Tracer Handler |
| in the Camel Tracer: |
| |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"> |
| |
| <reference id="eventAdmin" interface="org.osgi.service.event.EventAdmin"/> |
| |
| <bean id="traceHandler" class="org.apache.karaf.decanter.collector.camel.DecanterTraceEventHandler"> |
| <property name="eventAdmin" ref="eventAdmin"/> |
| </bean> |
| |
| <bean id="tracer" class="org.apache.camel.processor.interceptor.Tracer"> |
| <property name="traceHandler" ref="traceHandler"/> |
| <property name="enabled" value="true"/> |
| <property name="traceOutExchanges" value="true"/> |
| <property name="logLevel" value="OFF"/> |
| </bean> |
| |
| <camelContext trace="true" xmlns="http://camel.apache.org/schema/blueprint"> |
| <route id="test"> |
| <from uri="timer:fire?period=10000"/> |
| <setBody><constant>Hello World</constant></setBody> |
| <to uri="log:test"/> |
| </route> |
| </camelContext> |
| |
| </blueprint> |
| ---- |
| |
| ==== System |
| |
| The system collector is a polled collector (periodically executed by the Decanter Scheduler). |
| |
| This collector executes operating system commands (or scripts) and send the execution output to the appenders. |
| |
| The `decanter-collector-system` feature installs the system collector: |
| |
| ---- |
| karaf@root()> feature:install decanter-collector-system |
| ---- |
| |
| This feature installs a default `etc/org.apache.karaf.decanter.collector.system.cfg` configuration file containing: |
| |
| ---- |
| # |
| # Decanter OperationSystem Collector configuration |
| # |
| |
| # This collector executes system commands, retrieve the exec output/err |
| # sent to the appenders |
| # |
| # The format is command.key=command_to_execute |
| # where command is a reserved keyword used to identify a command property |
| # for instance: |
| # |
| # command.df=df -h |
| # command.free=free |
| # |
| # You can also create a script containing command like: |
| # |
| # df -k / | awk -F " |%" '/dev/{print $8}' |
| # |
| # This script will get the available space on the / filesystem for instance. |
| # and call the script: |
| # |
| # command.df=/bin/script |
| # |
| # Another example of script to get the temperature: |
| # |
| # sensors|grep temp1|awk '{print $2}'|cut -b2,3,4,5 |
| # |
| ---- |
| |
| You can add the commands that you want to execute using the format: |
| |
| ---- |
| command.name=system_command |
| ---- |
| |
| The collector will execute each command described in this file, and send the execution output to the appenders. |
| |
| For instance, if you want to periodically send the free space available on the / filesystem, you can add: |
| |
| ---- |
| command.df=df -k / | awk -F " |%" '/dev/{print $8}' |
| ---- |
| |
| ==== Network socket |
| |
| The Decanter network socket collector listens for incoming messages coming from a remote network socket collector. |
| |
| The `decanter-collector-socket` feature installs the network socket collector: |
| |
| ---- |
| karaf@root()> feature:install decanter-collector-socket |
| ---- |
| |
| This feature installs a default `etc/org.apache.karaf.decanter.collector.socket.cfg` configuration file containing: |
| |
| ---- |
| # Decanter Socket Collector |
| |
| # Port number on which to listen |
| #port=34343 |
| |
| # Number of worker threads to deal with |
| #workers=10 |
| ---- |
| |
| * the `port` property contains the port number where the network socket collector is listening |
| * the `workers` property contains the number of worker thread the socket collector is using for connection |