Merge pull request #119 from CoScale/feature/install-instructions

Feature/install instructions

_docs_agent/application-monitoring.md

@@ -0,0 +1,53 @@
+---
+layout: page
+title: Application monitoring
+description: Overview of information on how to configure CoScale application monitoring
+---
+
+CoScale can monitor applications running on your host machines as well as applications running inside Docker containers. The technology is set up in a way that you don't need to expose ports or mounts filesystems for the monitoring to function. To setup an application for CoScale monitoring you need to configure the CoScale agent to do so. If you haven't installed a CoScale agent yet, [check out the instructions on how to install the CoScale agent here]({{ site.baseurl }}/agent/install).
+
+For containers our monitoring is launched from inside the container, this has certain advantages:
+
+* **Local network access**: Our plugins share the same network space as the container, this means all open ports are accessible, even if not exposed.
+* **File system access**: Our plugins share the same file system as the container, this means container filesystem is accessible, even if not mounted on host.
+* **Docker API access**: Our plugins have access to Docker API through the CoScale agent, this means Docker logs data is available for use as a path (`/dev/stdout`), [secrets and environment variables]({{ site.baseurl }}/agent/linux/environment-variables/) are available for other configuration settings.
+
+A [full list of our supported technologies can be found on our Agent page]({{ site.baseurl }}/agent/index#integrations), including for each the configuration required to set it up.
+
+## Configuration
+
+Go the agent page by going to `Datasources > Agent` in the sidebar inside your CoScale application. Click on the configure button next to the agent you want to update.
+
+### Configure the CoScale Docker agent with Docker label detection
+
+The agent will automatically start to monitor all Docker containers which have a label that starts with `com.coscale.monitoring` and contains a list of plugins and their configuration. These labels can be generated by clicking on the `Generate Docker labels` button under the configuration pane. You can mark an image to be monitored by placing the generated label in your Dockerfile:
+
+{% highlight docker %}
+LABEL com.coscale.monitoring='[{"PluginType":"GENERICSCRIPT","Configuration":{"SCRIPT":["/script.sh"]}}]'
+{% endhighlight %}
+
+For already existing images the label can also be specified when creating containers, in the `docker run` command via the `--label` or `--label-file` options:
+
+{% highlight bash %}
+docker run -d --label com.coscale.monitoring='[{"PluginType":"CASSANDRA","Configuration":{"JMX HOSTNAME":["localhost"],"JMX PORT":["7199"]}}]' cassandra
+{% endhighlight %}
+
+Note that if the container's base image already has the 'com.coscale.monitoring' label, adding it again on `docker run` will overwrite the configuration in the base image. If instead want to extend the list of plugins defined in the base image, you can use a different label name in the `docker run` command, for example `com.coscale.monitoring.extra` or `com.coscale.monitoring.anything`.
+
+You can find some more example images on our [Github repository](https://github.com/CoScale/docker-adapted), please don't hesitate to contact us if you need a specific example.
+
+### Configure the CoScale Docker agent with Docker image detection
+
+The CoScale agent also has a system that scans running containers and sets up the monitoring based on the image name and tag. You will need to add a set of plugins to be installed when a container with your specific image is running, this can be done through our UI by clicking the `Add image` button. Our image and tag detection can use wildcards, so "jboss-*" will trigger on all images that start with "jboss". After adding a plugin, you will receive instructions on how to setup your Docker container so that our agent can monitor it.
+
+<img src="{{ site.baseurl}}/gfx/agent/plugins/docker/configuration.png" alt="Screenshot of Docker configuration" class="img-responsive" />
+
+You can add multiple images at the same time. After saving your configuration the CoScale agent will pick-up the new configuration and start to scan for images.
+
+### Configure the CoScale agent for host application monitoring
+
+To monitor applications in a non-container environment you need to enable the plugins on the agent of the software you want to monitor. The resource plugin is enabled by default, but you probably also want to enable other plugins. For a web server running Tomcat i.e. you would enable the Tomcat plugin by clicking on it. You can enable as many plugins as you like.
+
+<img alt="Deployment type" src="{{ site.baseurl }}/gfx/agent/install/03-plugins.png" style="img-responsive"/>
+
+Some plugins require further configuration, read and follow the instructions carefully. If necessary, apply the proposed changes to the server as shown in the instructions and fill in the required fields. After saving your configuration the CoScale agent will pick-up the new configuration and start to monitor your applications.