Merge pull request #1268 from amazeeio/kibana-docs-update

WIP: Kibana examples docs update
uselagoon · Sep 25, 2019 · 6576d2e · 6576d2e
2 parents 0740f6b + d7c9674
commit 6576d2e
Show file tree

Hide file tree

Showing 8 changed files with 74 additions and 2 deletions.
diff --git a/docs/images/kibana_example1.png b/docs/images/kibana_example1.png
diff --git a/docs/images/kibana_example2.png b/docs/images/kibana_example2.png
diff --git a/docs/images/kibana_example3.png b/docs/images/kibana_example3.png
diff --git a/docs/images/kibana_example4.png b/docs/images/kibana_example4.png
diff --git a/docs/images/kibana_example5.png b/docs/images/kibana_example5.png
diff --git a/docs/using_lagoon/logging/kibana_examples.md b/docs/using_lagoon/logging/kibana_examples.md
@@ -0,0 +1,71 @@
+# Kibana Examples
+
+Have you seen the Kibana getting started video and are now ready to work with logs? We are here to help!  This page will give you examples of Kibana queries you can use.  This is not a Kibana 101 class, but it can help you understand some of what you can do in Kibana.  Ready to get started? Good!
+
+## Router Logs
+
+Below you'll find examples for two common log requests: Viewing the total number of hits/requests to your site and viewing the number of hits/requests from a specific IP address. Let's start with the first one, viewing the total number of hits/requests to your site.
+
+### Total Number of hits/requests to your site
+
+Let's start Kibana up and select Discovery(#1 in screen shot below) then the Router logs for your project(#2).  From there, we will filter some of this information down a bit.  Let's focus on our main production environment.  In the search bar (#3), let's enter:
+
+`openshift_project: "name of your production project"`
+
+This will show you all the hits to your production environment in the given time frame.  You can change the time frame in the upper right hand corner (#4).  Clicking on the arrow next to the entry (#5) will expand it and show you all the information that was captured.  You can add any of those fields to the window by hovering over them and clicking add on the left hand side (#6).  You can also further filter your results by using the search bar.
+
+[![Kibana Router Logs Example 1](/images/kibana_example1.png)](/images/kibana_example1.png)
+
+### Number of hits/requests from a specific IP address
+
+Running the query above will give you a general look at all the traffic to your site, but what if you want to narrow in on a specific IP address? Perhaps you want to see how many times an IP has hit your site and what specific pages they were looking at.  This next query should help.
+
+We are going to start off with the same query as above, but we are going to add a couple of things.  First, you can add the following fields: `client_ip` and `http_request`.  This will show you a list of all IP addresses and the page they requested.  Here is what we see for the Amazee.io page:
+
+[![Kibana Router Logs Example 2](/images/kibana_example2.png)](/images/kibana_example2.png)
+
+That looks good, but what if we wanted to just show requests from a specific IP address? You can filter for the address by adding it to your search criteria.  We are going to add: `AND client_ip: "IP address"`.  That will filter the results to just show you hits from that specific IP address, and the page they were requesting.  Here is what it looks like for our Amazee.io website:
+
+[![Kibana Router Logs Example 3](/images/kibana_example3.png)](/images/kibana_example3.png)
+
+
+## Container Logs
+
+Container logs will show you all stout and sterr messages for your specific container and project.  We are going to show an example for getting logs from a specific container and finding specific error numbers in that container.
+
+### Logs from a container
+
+Want to see the logs for a specific container (php, nginx, etc)? This section will help!  Let's focus on looking at nginx logs.  We start by opening up Kibana and selecting Discover (#1 in the screen shot below).  From there, we select the container logs for our project (#2).  Let's go to the search bar (#3) and enter:
+
+`kubernetes.container_name: "nginx"`
+
+This will display all nginx logs for our project.  Clicking on the arrow next to an entry (#4) will expand that entry and show you all of the information it gathered.  Let's add the message field and the level field to the view.  You can do that by clicking on "Add" on the left hand side (#5).  You can change the time frame in the upper right hand corner of the screen (#6), in the example below I'm looking at logs for the last 4 hours.
+
+[![Kibana Container Logs Example 1](/images/kibana_example4.png)](/images/kibana_example4.png)
+
+### Specific errors in logs
+
+Want to see how many 500 errors you've had in your nginx container? You can easily do that by changing the search query.  If you search:
+
+`kubernetes.container_name: "nginx" AND message: "500"`
+
+That will only display 500 error messages in the nginx container.  You can search for any error message in any container that you would like!
+
+## Visualization
+
+Kibana will also give you the option to create visualizations or graphs.  We are going to create a chart to show number of hits/requests in a month using the same query we used above.
+
+1.  Click on Visualize on the left hand side of Kibana
+2.  Click on the blue plus sign
+3.  For this example, we are going to select a Vertical Bar chart.
+4.  Select the router logs for your project
+5.  Click on X-Axis under Buckets and select Date Histogram, with the interval set to Daily
+6.  Success!! You should now see a nice bar graph showing your daily traffic.  
+
+Note: Make sure that you select an appropriate time frame for the data in the upper right hand corner.
+
+Here is an example of a daily hits visualization chart:
+
+[![Kibana Visualization Example 1](/images/kibana_example5.png)](/images/kibana_example5.png)
+
+Also note that you can save your visualizations (and searches)! That will make it even faster to access them in the future.  And because each Account has their own Kibana Tenant, which means no saved searches or visualizations are shared with another Account.
diff --git a/docs/using_lagoon/logging.md → docs/using_lagoon/logging/logging.md b/docs/using_lagoon/logging.md → docs/using_lagoon/logging/logging.md
@@ -1,4 +1,3 @@
-# Logging
 
 Lagoon provides access to the following logs via Kibana:
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -19,7 +19,9 @@ pages:
     - Nginx: using_lagoon/docker_images/nginx.md
   - Workflows: using_lagoon/workflows.md
   - Backups: using_lagoon/backups.md
-  - Logging: using_lagoon/logging.md
+  - Logs: 
+     - Logging: using_lagoon/logging/logging.md
+     - Kibana Examples: using_lagoon/logging/kibana_examples.md
   - Remote Shell: using_lagoon/remote_shell.md
   - GraphQL API: using_lagoon/graphql_api.md
   - Drupal: