<commit_before>= Getting Started
<NAME>
2015-02-25
:description: How to get started with Hawkular
:jbake-type: page
:jbake-status: published
:icons: font
:toc: macro
:toc-title:

toc::[]

== Getting Started with Hawkular.

NOTE
Right now there is no Hawkular distribution to download and go. We are working on it.

Once we have a distribution available, you can unzip and start the server

[source,shell]
----
unzip hawkular.zip
cd hawkular
cd wildfly-8.2.0.Final
bin/standalone.sh  # use standalone.bat on Windows
----

You can then navigate your browser to http://localhost:8080/

=== Cassandra Integration
Hawkular uses Cassandra. Out of the box Hawkular is configured to use an embedded
single-node cluster. You do not have to worry about setting up and configuring
Cassandra before getting started with Hawkular.

NOTE: The embedded instance is not intended for production use

==== Embedded Cassandra Configuration
[options="header"]
|===========================
| Setting | Value | Description
| Cassandra version | 2.1.1 |
| CQL Port | 9042 | The port on which Cassandra listens for client requests
| Data directory | `jboss.server.data.dir`/hawkular-metrics | The location of Cassandra data files. Currently this is only used by Hawkular Metrics.
| Keyspace | hawkular_metrics | The default keyspace. This is currently only used by Hawkular Metrics.
|===========================

TIP: The embedded instance only listens for requests on localhost.

==== Using an external Cassandra Cluster
Beyond basic usage and development, you will likely want to configure Hawkular
to use an external Cassandra cluster.

NOTE: Hawkular requires Cassandra 2.1.1 or later. It is recommended to use the
latest 2.1.x release if possible.

Fortunately, this only requires setting
a few system properties.

From the command line::
[source,shell]
----
bin/standalone.sh -Dhawkular-metrics.cassandra-nodes="node_1_address,node_2_address,node_n_address" -Dhawkular-metrics.backend=remote
----

The `hawkular-metrics.cassandra-nodes` property should be a comma-delimited list
of Cassandra node endpoint addresses. The value for each address should match the
value of the `rpc_address` in the cassandra.yaml configuration file. You do not
actually have to specify the address of every Cassandra node. As long as Hawkular
is able to connect to one node, it will discover all of the other cluster nodes.

From standalone.xml::
[source,xml]
----
<system-properties>
  <property name="hawkular-metrics.cassandra-nodes" value="node_1_address,node_2_address,node_n_address"/>
  <property name="hawkular-metrics.backend" value="remote"/>
</system-properties>
----

TIP: You can change the keyspace used by setting the `cassandra.keyspace` system property.

=== Try via Docker

Hawkular is publishing builds to https://registry.hub.docker.com/u/hawkular/hawkular/[Docker Hub] that you can try
and download from Docker.

NOTE: Those builds are not secured and should not be run on a public network.

The following assumes that you have Docker installed and started if necessary.

[source, shell]
----
$ docker run -d -p 8081:8080 hawkular/hawkular   #<1>
Unable to find image 'hawkular/hawkular:latest' locally #<2>
Pulling repository hawkular/hawkular
26830c504ec5: Download complete
[...]
612ba72033af: Download complete
Status: Downloaded newer image for hawkular/hawkular:latest #<3>
c792a1f059521f6ae99  #<4>
----
<1> Start the docker container in the background (`-d`) and tell it that the internal port 8080 should be
available as port 8081 (`-p 8081:8080).
<2> This is the first time that image is to be used, so docker is downloading it from Docker Hub, which may take a
while. Starting the same image the next time will only take a few seconds.
<3> Download has finished, Hawkular server will be started
<4> Hawkular server has started with a container id of `c792a1f0595`. This id will be different for each start.

Now as Docker is running the container and you can reach the Hawkular UI at http://localhost:8081/  ( If you are
running docker on OS/X via boot2docker, you need to use the IP address that is stored in the `DOCKER_HOST`
environment variable instead of `localhost`.)

When you are done, you can shut down the container via

[source,shell]
----
$ docker stop c792a1f0595  #<1>
----
<1> Container id that was emitted above

To upgrade to a newer build just run

[source,shell]
----
$ docker pull hawkular/hawkular:latest  #<1>
Pulling repository hawkular/hawkular
26830c504ec5: Download complete
511136ea3c5a: Download complete
[...]
612ba72033af: Download complete
Status: Image is up to date for hawkular/hawkular:latest #<2>
----
<1> We ask for the latest build
<2> In this case the local one was already the latest, so we are good here.


=== Working on Hawkular source

If you are interested in hacking on Hawkular, or building it from source, then check out
link:/docs/dev/development.html[Development resources]<commit_msg>agent instructions<commit_after>= Getting Started
<NAME>
2015-02-25
:description: How to get started with Hawkular
:jbake-type: page
:jbake-status: published
:icons: font
:toc: macro
:toc-title:

toc::[]

== Getting Started with Hawkular.

NOTE
Right now there is no Hawkular distribution to download and go. We are working on it.

Once we have a distribution available, you can unzip and start the server

[source,shell]
----
unzip hawkular.zip
cd hawkular
cd wildfly-8.2.0.Final
bin/standalone.sh  # use standalone.bat on Windows
----

You can then navigate your browser to http://localhost:8080/

=== Cassandra Integration
Hawkular uses Cassandra. Out of the box Hawkular is configured to use an embedded
single-node cluster. You do not have to worry about setting up and configuring
Cassandra before getting started with Hawkular.

NOTE: The embedded instance is not intended for production use

==== Embedded Cassandra Configuration
[options="header"]
|===========================
| Setting | Value | Description
| Cassandra version | 2.1.1 |
| CQL Port | 9042 | The port on which Cassandra listens for client requests
| Data directory | `jboss.server.data.dir`/hawkular-metrics | The location of Cassandra data files. Currently this is only used by Hawkular Metrics.
| Keyspace | hawkular_metrics | The default keyspace. This is currently only used by Hawkular Metrics.
|===========================

TIP: The embedded instance only listens for requests on localhost.

==== Using an external Cassandra Cluster
Beyond basic usage and development, you will likely want to configure Hawkular
to use an external Cassandra cluster.

NOTE: Hawkular requires Cassandra 2.1.1 or later. It is recommended to use the
latest 2.1.x release if possible.

Fortunately, this only requires setting
a few system properties.

From the command line::
[source,shell]
----
bin/standalone.sh -Dhawkular-metrics.cassandra-nodes="node_1_address,node_2_address,node_n_address" -Dhawkular-metrics.backend=remote
----

The `hawkular-metrics.cassandra-nodes` property should be a comma-delimited list
of Cassandra node endpoint addresses. The value for each address should match the
value of the `rpc_address` in the cassandra.yaml configuration file. You do not
actually have to specify the address of every Cassandra node. As long as Hawkular
is able to connect to one node, it will discover all of the other cluster nodes.

From standalone.xml::
[source,xml]
----
<system-properties>
  <property name="hawkular-metrics.cassandra-nodes" value="node_1_address,node_2_address,node_n_address"/>
  <property name="hawkular-metrics.backend" value="remote"/>
</system-properties>
----

TIP: You can change the keyspace used by setting the `cassandra.keyspace` system property.

=== Try via Docker

Hawkular is publishing builds to https://registry.hub.docker.com/u/hawkular/hawkular/[Docker Hub] that you can try
and download from Docker.

NOTE: Those builds are not secured and should not be run on a public network.

The following assumes that you have Docker installed and started if necessary.

[source, shell]
----
$ docker run -d -p 8081:8080 hawkular/hawkular   #<1>
Unable to find image 'hawkular/hawkular:latest' locally #<2>
Pulling repository hawkular/hawkular
26830c504ec5: Download complete
[...]
612ba72033af: Download complete
Status: Downloaded newer image for hawkular/hawkular:latest #<3>
c792a1f059521f6ae99  #<4>
----
<1> Start the docker container in the background (`-d`) and tell it that the internal port 8080 should be
available as port 8081 (`-p 8081:8080).
<2> This is the first time that image is to be used, so docker is downloading it from Docker Hub, which may take a
while. Starting the same image the next time will only take a few seconds.
<3> Download has finished, Hawkular server will be started
<4> Hawkular server has started with a container id of `c792a1f0595`. This id will be different for each start.

Now as Docker is running the container and you can reach the Hawkular UI at http://localhost:8081/  ( If you are
running docker on OS/X via boot2docker, you need to use the IP address that is stored in the `DOCKER_HOST`
environment variable instead of `localhost`.)

When you are done, you can shut down the container via

[source,shell]
----
$ docker stop c792a1f0595  #<1>
----
<1> Container id that was emitted above

To upgrade to a newer build just run

[source,shell]
----
$ docker pull hawkular/hawkular:latest  #<1>
Pulling repository hawkular/hawkular
26830c504ec5: Download complete
511136ea3c5a: Download complete
[...]
612ba72033af: Download complete
Status: Image is up to date for hawkular/hawkular:latest #<2>
----
<1> We ask for the latest build
<2> In this case the local one was already the latest, so we are good here.


=== Working on Hawkular source

If you are interested in hacking on Hawkular, or building it from source, then check out
link:/docs/dev/development.html[Development resources]

== Install a Wildfly Monitoring Agent

If you wish to monitor a WildFly instance,  you can do so with the following steps:

. Download the WildFly module from http://download.jboss.org/hawkular/wildfly-monitor/0.0.9/hawkular-monitor-0.0.9-module.zip[here].
. Unzip the file inside the `modules` directory of  your WildFly 8.2 instance
. In the `standalone/configuration/standalone.xml` file of your WildFly instance, make the following additions
.. Add the Hawkular Monitor Agent extension in the <extensions> section:
[source,xml]
----
<extension module="org.hawkular.agent.monitor"/>
----
. Add the Hawkular Monitor Agent subsystem declaration in the <profile> section. Note that you must set your Hawkular credentials in the username and password attributes (in other words, replace SET_ME with their true values for your Hawkular system):
[source,xml]
----
<subsystem apiJndiName="java:global/hawkular/agent/monitor/api" numMetricSchedulerThreads="3" numAvailSchedulerThreads="3" enabled="true" xmlns="urn:org.hawkular.agent.monitor:monitor:1.0">
  <diagnostics enabled="true" reportTo="LOG" interval="5" timeUnits="minutes"/>
  <storage-adapter type="HAWKULAR" username="SET_ME" password="<PASSWORD>" serverOutboundSocketBindingRef="hawkular" />
  <metric-set-dmr name="WildFly Memory Metrics" enabled="true">
    <metric-dmr name="Heap Used" interval="30" timeUnits="seconds" metricUnits="bytes" path="/core-service=platform-mbean/type=memory" attribute="heap-memory-usage#used"/>
    <metric-dmr name="Heap Committed" interval="1" timeUnits="minutes" path="/core-service=platform-mbean/type=memory" attribute="heap-memory-usage#committed"/>
    <metric-dmr name="NonHeap Used" interval="30" timeUnits="seconds" path="/core-service=platform-mbean/type=memory" attribute="non-heap-memory-usage#used"/>
    <metric-dmr name="NonHeap Committed" interval="1" timeUnits="minutes" path="/core-service=platform-mbean/type=memory" attribute="non-heap-memory-usage#committed"/>
  </metric-set-dmr>
  <metric-set-dmr name="WildFly Threading Metrics" enabled="true">
    <metric-dmr name="Thread Count" interval="2" timeUnits="minutes" metricUnits="none" path="/core-service=platform-mbean/type=threading" attribute="thread-count"/>
  </metric-set-dmr>
  <avail-set-dmr name="Server Availability" enabled="true">
    <avail-dmr name="App Server" interval="30" timeUnits="seconds" path="/" attribute="server-state" upRegex="run.*"/>
  </avail-set-dmr>
  <resource-type-set-dmr name="Main" enabled="true">
    <resource-type-dmr name="WildFly Server" resourceNameTemplate="WildFly Server" path="/" metricSets="WildFly Memory Metrics,WildFly Threading Metrics" availSets="Server Availability"/>
  </resource-type-set-dmr>
  <managed-servers>
    <local-dmr name="Local Server" enabled="true" resourceTypeSets="Main"/>
  </managed-servers>
</subsystem>
----
WARNING: It is known that this only works with WildFly 8.2 at the moment and not with WildFly 9 or above.
. Add an outbound socket binding to your WildFly instance's <socket-binding-group> that points to your running Hawkular server instance:
[source,xml]
----
<outbound-socket-binding name="hawkular">
  <remote-destination host="your-hawkular-server-hostname" port="8080" />
</outbound-socket-binding>'
----
{'fraction_non_alphanumeric': 0.10294902080317, 'fraction_numerical': 0.024308466051969825, 'mean_word_length': 4.7687912087912085, 'pattern_counts': {'":': 0, '<': 71, '<?xml version=': 0, '>': 71, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 9}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 24, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7655558', 'n_tokens_mistral': 4102, 'n_tokens_neox': 3781, 'n_words': 1538}