|
| 1 | +# Apache Karaf Integration for InfluxDB 2.0 |
| 2 | + |
| 3 | +## Features |
| 4 | + |
| 5 | +- [Submodules](#submodules) |
| 6 | +- [Installation](#installation) |
| 7 | +- [Configuration](#configuration) |
| 8 | +- [Examples](#examples) |
| 9 | + |
| 10 | +## Submodules |
| 11 | + |
| 12 | +The Apache Karaf feature definition modules supporting InfluxDB 2.0: |
| 13 | + |
| 14 | +| Module | Description | |
| 15 | +| --- | --- | |
| 16 | +| **karaf-features** | Apache Karaf feature definition (XML) artifact for InfluxDB 2.0. | |
| 17 | +| **karaf-kar** | KAraf aRchive (KAR) artifact containing client for InfluxDB 2.0. | |
| 18 | +| **karaf-assembly** | Apache Karaf (sample) distribution having InfluxDB 2.0 client. | |
| 19 | + |
| 20 | +## Installation |
| 21 | + |
| 22 | +Apache Karaf Integration can be enabled by installing Karaf feature or KAR file. |
| 23 | + |
| 24 | +### Preparing |
| 25 | + |
| 26 | +Download [Apache Karaf](http://karaf.apache.org/download.html) 4.2+, extract to directory referenced by `KARAF_HOME` below and start container: |
| 27 | + |
| 28 | +``` |
| 29 | +$KARAF_HOME/bin/karaf |
| 30 | +``` |
| 31 | + |
| 32 | +### Karaf feature installation |
| 33 | + |
| 34 | +Add feature repository (`mvn:com.influxdb/influxdb-karaf-features/VERSION/xml/features`) and install feature named `influxdb-client` (replace `VERSION` with current version). |
| 35 | + |
| 36 | +``` |
| 37 | +karaf@root()> feature:repo-add mvn:com.influxdb/influxdb-karaf-features/VERSION/xml/features |
| 38 | +karaf@root()> feature:install influxdb-client |
| 39 | +``` |
| 40 | + |
| 41 | +Feature repository can be referenced by custom Karaf distributions too. |
| 42 | + |
| 43 | +### KAR deployment |
| 44 | + |
| 45 | +Install KAR Maven artifact `mvn:com.influxdb/influxdb-karaf-kar/VERSION/kar` (replace `VERSION` with current version): |
| 46 | + |
| 47 | +``` |
| 48 | +karaf@root()> kar:install mvn:com.influxdb/influxdb-karaf-kar/VERSION/kar |
| 49 | +``` |
| 50 | + |
| 51 | +### Sample Apache Karaf distribution |
| 52 | + |
| 53 | +A sample Apache Karaf distribution is created automatically by compiling karaf-assembly Maven module. ZIP and TGZ packages can be found in `karaf-assembly/target/` directory. OSGi component developers using InfluxDB do not need to download Apache Karaf and complete installation process (above) but unpack archive only and start the server. |
| 54 | + |
| 55 | +An alternate way to start the server is running `karaf-assembly/target/assembly/bin/karaf`. Installed features and bundles can be checked by the following commands: |
| 56 | + |
| 57 | +``` |
| 58 | +karaf@root()> feature:list | grep influx |
| 59 | +influxdb-client │ 2.2.0.SNAPSHOT │ │ Started │ influxdb-features-2.2.0-SNAPSHOT │ InfluxDB client |
| 60 | +kotlin │ 1.3.72 │ │ Started │ influxdb-features-2.2.0-SNAPSHOT │ Kotlin |
| 61 | +influxdb-karaf-features │ 2.2.0.SNAPSHOT │ │ Uninstalled │ influxdb-features-2.2.0-SNAPSHOT │ Apache Karaf Features for InfluxDB 2.0 |
| 62 | +karaf@root()> bundle:list | grep -i influx |
| 63 | +16 │ Active │ 80 │ 2.2.0.SNAPSHOT │ The OSGi InfluxDB 2.0 Client |
| 64 | +``` |
| 65 | + |
| 66 | +Declarative services (i.e. that are writing data to InfluxDB by OSGi events) become available if you copy configuration files (see below) to `karaf-assembly/target/assembly/deploy` directory. |
| 67 | + |
| 68 | +``` |
| 69 | +karaf@root()> scr:list |
| 70 | +com.influxdb.client.osgi.LineProtocolWriter in bundle 16 (com.influxdb.client-osgi:2.2.0.SNAPSHOT) enabled, 1 instance. |
| 71 | + Id: 3, State:ACTIVE, PID(s): [com.influxdb.client.osgi.LineProtocolWriter.7617b1fb-5b49-402b-b794-1bab69bf6136] |
| 72 | +com.influxdb.client.osgi.InfluxDBConnector in bundle 16 (com.influxdb.client-osgi:2.2.0.SNAPSHOT) enabled, 1 instance. |
| 73 | + Id: 1, State:ACTIVE, PID(s): [com.influxdb.client.osgi.InfluxDBConnector.1e27ec4c-4dcb-4545-a2ec-40405877a409] |
| 74 | +com.influxdb.client.osgi.PointWriter in bundle 16 (com.influxdb.client-osgi:2.2.0.SNAPSHOT) enabled, 1 instance. |
| 75 | +``` |
| 76 | + |
| 77 | +## Configuration |
| 78 | + |
| 79 | +Configuration options are described by [client-osgi](../client-osgi/README.md). Create configurations by hand (`*.cfg` files, copy them to `KARAF_HOME/deploy` directory) or via web console (need to install `webconsole` Karaf feature). |
| 80 | + |
| 81 | +## Examples |
| 82 | + |
| 83 | +### Preparing |
| 84 | + |
| 85 | +Install Apache Karaf Integration as described above. Create the following configuration files (replace connection properties): |
| 86 | + |
| 87 | +- `KARAF_HOME/deploy/com.influxdb.client.osgi.InfluxDBConnector-test.cfg` |
| 88 | +``` |
| 89 | +alias=test |
| 90 | +url=http://localhost:8086 |
| 91 | +token=TOKEN |
| 92 | +organization=example |
| 93 | +bucket=test |
| 94 | +``` |
| 95 | + |
| 96 | +- `KARAF_HOME/deploy/com.influxdb.client.osgi.LineProtocolWriter-tester.cfg` |
| 97 | +``` |
| 98 | +client.target=(alias=test) |
| 99 | +timestamp.append=true |
| 100 | +``` |
| 101 | + |
| 102 | +- `KARAF_HOME/deploy/com.influxdb.client.osgi.PointWriter-tester.cfg` |
| 103 | +``` |
| 104 | +event.topics=influxdb/point/* |
| 105 | +client.target=(alias=test) |
| 106 | +host.name.add=true |
| 107 | +host.address.add=true |
| 108 | +timestamp.add=true |
| 109 | +timestamp.precision=ns |
| 110 | +``` |
| 111 | + |
| 112 | +### Write RAW (line protocol) record |
| 113 | + |
| 114 | +Publish OSGi event containing line protocol record (i.e. via Karaf console). |
| 115 | + |
| 116 | +``` |
| 117 | +karaf@root()> event:send influxdb/lineprotocol "record=weather,location=HU temperature=5.89,humidity=48" |
| 118 | +``` |
| 119 | + |
| 120 | +### Write structured data |
| 121 | + |
| 122 | +Publish OSGi event containing structured data (i.e. by custom component). Both InfluxDB Point and Java Map types are supported (see [client-osgi](../client-osgi/README.md) and [javadoc](https://influxdata.github.io/influxdb-client-java/influxdb-client-osgi/apidocs/index.html) for details). |
| 123 | + |
| 124 | +```java |
| 125 | +@Component |
| 126 | +public class Tester { |
| 127 | + |
| 128 | + @Reference |
| 129 | + EventAdmin eventAdmin; |
| 130 | + |
| 131 | + public void tester() { |
| 132 | + final Map<String, String> tags = new TreeMap<>(); |
| 133 | + tags.put("location", "HU"); |
| 134 | + |
| 135 | + final Map<String, Object> fields = new TreeMap<>(); |
| 136 | + fields.put("temperature", 5.89); |
| 137 | + fields.put("humidity", 48); |
| 138 | + fields.put("raining", false); |
| 139 | + fields.put("sky", "CLOUDY"); |
| 140 | + |
| 141 | + final Map<String, Object> point = new TreeMap<>(); |
| 142 | + point.put("tags", tags); |
| 143 | + point.put("fields", fields); |
| 144 | + |
| 145 | + eventAdmin.postEvent(new Event("influxdb/point/weather", Collections.singletonMap("point", point))); |
| 146 | + } |
| 147 | +} |
| 148 | +``` |
0 commit comments