From 0740eae730441c45d013424b00b16afe8405b63b Mon Sep 17 00:00:00 2001 From: Douglas Reid Date: Thu, 28 Sep 2017 07:32:16 -0700 Subject: [PATCH] Break up istio addon task into three distinct functionally-focused tasks (#555) * Break up addons task * Wrap text * Remove unnecessary header --- _docs/guides/telemetry.md | 11 +- _docs/setup/kubernetes/quick-start.md | 15 +- _docs/tasks/telemetry/istio-addons.md | 257 ------------------ _docs/tasks/telemetry/metrics-logs.md | 24 +- _docs/tasks/telemetry/querying-metrics.md | 137 ++++++++++ _docs/tasks/telemetry/servicegraph.md | 114 ++++++++ .../tasks/telemetry/using-istio-dashboard.md | 122 +++++++++ 7 files changed, 399 insertions(+), 281 deletions(-) delete mode 100644 _docs/tasks/telemetry/istio-addons.md create mode 100644 _docs/tasks/telemetry/querying-metrics.md create mode 100644 _docs/tasks/telemetry/servicegraph.md create mode 100644 _docs/tasks/telemetry/using-istio-dashboard.md diff --git a/_docs/guides/telemetry.md b/_docs/guides/telemetry.md index 925ab8f136..714937daa4 100644 --- a/_docs/guides/telemetry.md +++ b/_docs/guides/telemetry.md @@ -34,10 +34,13 @@ developers to manually instrument their applications. 1. [Collecting metrics]({{home}}/docs/tasks/telemetry/metrics-logs.html) This task will configure Mixer to collect a uniform set of metrics - across all services in the Bookinfo application. It will configure Istio - Mixer to propagate the metrics to a Prometheus backend. Interested users can - setup Grafana to visualize the metrics by following the - [Istio Add-ons]({{home}}/docs/tasks/telemetry/istio-addons.html). + across all services in the Bookinfo application. + +1. [Querying metrics]({{home}}/docs/tasks/telemetry/querying-metrics.html) This task installs the Prometheus add-on for metrics collection and demonstrates querying a configured Prometheus server for Istio metrics. + +1. [Using the Istio Dashboard]({{home}}/docs/tasks/telemetry/using-istio-dashboard.html) This task installs the Grafana add-on with a pre-configured dashboard for monitoring mesh traffic. + +1. [Generating a Service Graph]({{home}}/docs/tasks/telemetry/servicegraph.html) This task generates a graph of service connections based on observed mesh traffic using the Servicegraph add-on. 1. [Request tracing]({{home}}/docs/tasks/telemetry/distributed-tracing.html) We will now use Istio to trace how requests are flowing across services in the diff --git a/_docs/setup/kubernetes/quick-start.md b/_docs/setup/kubernetes/quick-start.md index 28d07fc77b..f681e914b7 100644 --- a/_docs/setup/kubernetes/quick-start.md +++ b/_docs/setup/kubernetes/quick-start.md @@ -123,20 +123,17 @@ Starting with the {{ site.data.istio.version }} release, Istio is installed in i ## Verifying the installation 1. Ensure the following Kubernetes services are deployed: `istio-pilot`, `istio-mixer`, - `istio-ingress`, `istio-egress`, and, optionally, `grafana`, `prometheus` and `servicegraph`. + `istio-ingress`, `istio-egress`. ```bash kubectl get svc -n istio-system ``` ```bash NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE - grafana 10.83.252.16 3000:30432/TCP 5h istio-egress 10.83.247.89 80/TCP 5h istio-ingress 10.83.245.171 35.184.245.62 80:32730/TCP,443:30574/TCP 5h istio-pilot 10.83.251.173 8080/TCP,8081/TCP 5h istio-mixer 10.83.244.253 9091/TCP,9094/TCP,42422/TCP 5h - prometheus 10.83.247.221 9090:30398/TCP 5h - servicegraph 10.83.242.48 8088:31928/TCP 5h ``` Note: If your cluster is running in an environment that does not support an external load balancer @@ -145,21 +142,18 @@ Starting with the {{ site.data.istio.version }} release, Istio is installed in i 2. Ensure the corresponding Kubernetes pods are deployed and all containers are up and running: `istio-pilot-\*`, `istio-mixer-\*`, `istio-ingress-\*`, `istio-egress-\*`, `istio-ca-\*`, - and, optionally, `istio-initializer-\*`, `grafana-\*`, `prometheus-\*` and `servicegraph-\*`. + and, optionally, `istio-initializer-\*`. ```bash kubectl get pods -n istio-system ``` ```bash - grafana-3836448452-vhc1v 1/1 Running 0 5h istio-ca-3657790228-j21b9 1/1 Running 0 5h istio-egress-1684034556-fhw89 1/1 Running 0 5h istio-ingress-1842462111-j3vcs 1/1 Running 0 5h istio-initializer-184129454-zdgf5 1/1 Running 0 5h istio-pilot-2275554717-93c43 1/1 Running 0 5h istio-mixer-2104784889-20rm8 2/2 Running 0 5h - prometheus-3067433533-wlmt2 1/1 Running 0 5h - servicegraph-3127588006-pc5z3 1/1 Running 0 5h ``` ## Deploy your application @@ -186,11 +180,8 @@ kubectl create -f <(istioctl kube-inject -f .yaml) ## Uninstalling -1. Uninstall any Istio add-ons: +1. Uninstall Istio initializer: - ```bash - kubectl delete -f install/kubernetes/addons/ - ``` If you installed Istio with initializer enabled, uninstall it: ```bash diff --git a/_docs/tasks/telemetry/istio-addons.md b/_docs/tasks/telemetry/istio-addons.md deleted file mode 100644 index 934e64473e..0000000000 --- a/_docs/tasks/telemetry/istio-addons.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -title: Using the Istio Add-ons - -overview: This task shows you how to setup and use the Istio Addons, including Prometheus, Grafana, and Servicegraph. - -order: 120 - -layout: docs -type: markdown ---- -{% include home.html %} - -This task shows how to install and use the set of Istio add-ons. The add-ons -include a Prometheus server with config to pull metrics from Istio endpoints, a -Grafana server preconfigured with a default dashboard for monitoring an Istio -service mesh, and an example ServiceGraph service that can generate a visual -representation of an Istio service mesh. - -The [BookInfo]({{home}}/docs/guides/bookinfo.html) sample application is used -as the example application throughout this task. - -## Before you begin -* [Install Istio]({{home}}/docs/setup/) in your cluster and deploy an - application. - -## Using the Prometheus add-on - -### Installation and Usage - -1. To collect, view, and query the metrics provided by Mixer, install the - Prometheus add-on. - - In Kubernetes environments, execute the following command: - - ```bash - kubectl apply -f install/kubernetes/addons/prometheus.yaml - ``` - -1. Verify that the service is running in your cluster. - - In Kubernetes environments, execute the following command: - - ```bash - kubectl -n istio-system get svc prometheus - ``` - - The output will be similar to: - - ``` - NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE - prometheus 10.59.241.54 9090/TCP 2m - ``` - -1. Send traffic to the mesh. - - For the BookInfo sample, visit `http://$GATEWAY_URL/productpage` in your web - browser or issue the following command: - - ```bash - curl http://$GATEWAY_URL/productpage - ``` - -1. Open the Prometheus UI. - - In Kubernetes environments, execute the following command: - - ```bash - kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=prometheus -o jsonpath='{.items[0].metadata.name}') 9090:9090 & - ``` - - Visit [http://localhost:9090/graph](http://localhost:9090/graph) in your web browser. - -1. Execute a Prometheus query. - - In the "Expression" input box at the top of the web page, enter the text: - `request_count`. Then, click the **Execute** button. - - The results will be similar to: - -
Prometheus Query Result -
Prometheus Query Result
- -### About the Prometheus Add-on - -Mixer comes with a built-in [Prometheus](https://prometheus.io) adapter that -exposes an endpoint serving generated metric values. The Prometheus add-on is a -Prometheus server that comes pre-configured to scrape Mixer endpoints to collect -the exposed metrics. It provides a mechanism for persistent storage and querying -of Istio metrics. The Grafana add-on, for instance, uses this add-on as the -source for all of the dashboard data. - -The configured Prometheus add-on scrapes three endpoints: -1. *istio-mesh* (`istio-mixer.istio-system:42422`): all Mixer-generated mesh - metrics. -1. *mixer* (`istio-mixer.istio-system:9093`): all Mixer-specific metrics. Used - to monitor Mixer itself. -1. *envoy* (`istio-mixer.istio-system:9102`): raw stats generated by Envoy (and - translated from statsd to prometheus). - -## Using the Grafana add-on - -**NOTE**: Use of the Grafana add-on _requires_ use of the Prometheus add-on. - -### Installation and Usage - -1. To view Istio metrics in a graphical dashboard install the Grafana add-on. - - In Kubernetes environments, execute the following command: - - ```bash - kubectl apply -f install/kubernetes/addons/grafana.yaml - ``` - -1. Verify that the service is running in your cluster. - - In Kubernetes environments, execute the following command: - - ```bash - kubectl -n istio-system get svc grafana - ``` - - The output will be similar to: - - ``` - NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE - grafana 10.59.247.103 3000/TCP 2m - ``` - -1. Open the Istio Dashboard via the Grafana UI. - - In Kubernetes environments, execute the following command: - - ```bash - kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=grafana -o jsonpath='{.items[0].metadata.name}') 3000:3000 & - ``` - - Visit [http://localhost:3000/dashboard/db/istio-dashboard](http://localhost:3000/dashboard/db/istio-dashboard) in your web browser. - - The Istio Dashboard will look similar to: - -
Istio Dashboard -
Istio Dashboard
- -1. Send traffic to the mesh. - - For the BookInfo sample, visit `http://$GATEWAY_URL/productpage` in your web - browser or issue the following command: - - ```bash - curl http://$GATEWAY_URL/productpage - ``` - - Refresh the page a few times (or send the command a few times) to generate a - small amount of traffic. - - Look at the Istio Dashboard again. It should reflect the traffic that was - generated. It will look similar to: - -
Istio Dashboard With Traffic -
Istio Dashboard With Traffic
- - -### About the Grafana add-on - -The Grafana add-on is a pre-configured instance of Grafana. The base image -([`grafana/grafana:4.1.2`](https://hub.docker.com/r/grafana/grafana/)) has been -modified to start with both a Prometheus data source and the Istio Dashboard -installed. The base install files for Istio, and Mixer in particular, ship with -a default configuration of global (used for every service) metrics. The Istio -Dashboard is built to be used in conjunction with the default Istio metrics -configuration and a Prometheus backend. - -The Istio Dashboard consists of three main sections: -1. A Global Summary View. This section provides high-level summary of HTTP - requests flowing through the service mesh. -1. A Mesh Summary View. This section provides slightly more detail than the - Global Summary View, allowing per-service filtering and selection. -1. Individual Services View. This section provides metrics about requests and - responses for each individual service within the mesh (HTTP and TCP). - -For more on how to create, configure, and edit dashboards, please see the -[Grafana documentation](http://docs.grafana.org/). - -## Using the Servicegraph add-on - -**NOTE**: Use of the Grafana add-on _requires_ use of the Prometheus add-on. - -1. To view a graphical representation of your service mesh, install the - Servicegraph add-on. - - In Kubernetes environments, execute the following command: - - ```bash - kubectl apply -f install/kubernetes/addons/servicegraph.yaml - ``` - -1. Verify that the service is running in your cluster. - - In Kubernetes environments, execute the following command: - - ```bash - kubectl -n istio-system get svc servicegraph - ``` - - The output will be similar to: - - ``` - NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE - servicegraph 10.59.253.165 8088/TCP 30s - ``` - -1. Send traffic to the mesh. - - For the BookInfo sample, visit `http://$GATEWAY_URL/productpage` in your web - browser or issue the following command: - - ```bash - curl http://$GATEWAY_URL/productpage - ``` - - Refresh the page a few times (or send the command a few times) to generate a - small amount of traffic. - -1. Open the Servicegraph UI. - - In Kubernetes environments, execute the following command: - - ```bash - kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=servicegraph -o jsonpath='{.items[0].metadata.name}') 8088:8088 & - ``` - - Visit [http://localhost:8088/dotviz](http://localhost:8088/dotviz) in your web browser. - - The results will look similar to: - -
Example Servicegraph -
Example Servicegraph
- -### About the Servicegraph Add-on - -The Servicegraph service is an example service that provides endpoints for -generating and visualizing a graph of services within a mesh. It exposes the -following endpoints: - -- `/graph` which provides a JSON serialization of the servicegraph -- `/dotgraph` which provides a dot serialization of the servicegraph -- `/dotviz` which provides a visual representation of the servicegraph - -All endpoints take an optional argument of `time_horizon`, which controls the -timespan to consider for graph generation. - -All endpoints also take an optional argument of `filter_empty=true`, which will -restrict the nodes and edges shown to only those that reflect non-zero traffic -levels during the specified `time_horizon`. - -The Servicegraph example is built on top of Prometheus queries. \ No newline at end of file diff --git a/_docs/tasks/telemetry/metrics-logs.md b/_docs/tasks/telemetry/metrics-logs.md index af51b4d991..d16fe1cb3c 100644 --- a/_docs/tasks/telemetry/metrics-logs.md +++ b/_docs/tasks/telemetry/metrics-logs.md @@ -167,6 +167,9 @@ as the example application throughout this task. double_request_count{destination="reviews.default.svc.cluster.local",instance="istio-mixer.istio-system:42422",job="istio-mesh",message="twice the fun!",source="productpage.default.svc.cluster.local"} 2 ``` + For more on querying Prometheus for metric values, see the [Querying Istio + Metrics]({{home}}/docs/tasks/telemetry/querying-metrics.html) Task. + 1. Verify that the logs stream has been created and is being populated for requests. @@ -187,14 +190,6 @@ as the example application throughout this task. {"level":"warn","ts":"2017-09-21T04:33:31.233Z","instance":"newlog.logentry.istio-config-default","destination":"ingress.istio-system.svc.cluster.local","latency":"74.47ms","responseCode":200,"responseSize":5599,"source":"unknown","user":"unknown"} ``` -## Cleanup - -Remove the new telemetry configuration: - -```bash -istioctl delete -f new_telemetry.yaml -``` - ## Understanding the telemetry configuration In this task, you added Istio configuration that instructed Mixer to @@ -299,6 +294,14 @@ configure a rule to be executed for all requests. Omitting the entire `match` parameter from the `spec` is equivalent to setting `match: true`. It is included here to illustrate how to use `match` expressions to control rule execution. +## Cleanup + +Remove the new telemetry configuration: + +```bash +istioctl delete -f new_telemetry.yaml +``` + ## What's next * Learn more about [Mixer]({{home}}/docs/concepts/policy-and-control/mixer.html) @@ -311,6 +314,11 @@ here to illustrate how to use `match` expressions to control rule execution. * Read the reference guide to [Writing Config]({{home}}/docs/reference/writing-config.html). +* Try out the related telemetry tasks: + - [Querying Istio Metrics]({{home}}/docs/tasks/telemetry/querying-metrics.html) + - [Using the Istio Dashboard]({{home}}/docs/tasks/telemetry/using-istio-dashboard.html) + - [Generating an Istio Service Graph]({{home}}/docs/tasks/telemetry/servicegraph.html) + * If you are not planning to explore any follow-on tasks, refer to the [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions to shutdown the application and cleanup the associated rules. diff --git a/_docs/tasks/telemetry/querying-metrics.md b/_docs/tasks/telemetry/querying-metrics.md new file mode 100644 index 0000000000..04eedeb74b --- /dev/null +++ b/_docs/tasks/telemetry/querying-metrics.md @@ -0,0 +1,137 @@ +--- +title: Querying Istio Metrics + +overview: This task shows you how to query for Istio Metrics using Prometheus. + +order: 15 + +layout: docs +type: markdown +--- +{% include home.html %} + +This task shows you how to query for Istio Metrics using Prometheus. As part of +this task, you will install the Prometheus Istio addon and use the web-based +interface for querying metric values. + +The [BookInfo]({{home}}/docs/guides/bookinfo.html) sample application is used as +the example application throughout this task. + +## Before you begin +* [Install Istio]({{home}}/docs/setup/) in your cluster and deploy an + application. + +## Querying Istio Metrics + +1. To query the metrics provided by Mixer, first install the Prometheus add-on. + + In Kubernetes environments, execute the following command: + + ```bash + kubectl apply -f install/kubernetes/addons/prometheus.yaml + ``` + +1. Verify that the service is running in your cluster. + + In Kubernetes environments, execute the following command: + + ```bash + kubectl -n istio-system get svc prometheus + ``` + + The output will be similar to: + + ``` + NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE + prometheus 10.59.241.54 9090/TCP 2m + ``` + +1. Send traffic to the mesh. + + For the BookInfo sample, visit `http://$GATEWAY_URL/productpage` in your web + browser or issue the following command: + + ```bash + curl http://$GATEWAY_URL/productpage + ``` + + Note: `$GATEWAY_URL` is the value set in the + [BookInfo]({{home}}/docs/guides/bookinfo.html) guide. + +1. Open the Prometheus UI. + + In Kubernetes environments, execute the following command: + + ```bash + kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=prometheus -o jsonpath='{.items[0].metadata.name}') 9090:9090 & + ``` + + Visit [http://localhost:9090/graph](http://localhost:9090/graph) in your web browser. + +1. Execute a Prometheus query. + + In the "Expression" input box at the top of the web page, enter the text: + `request_count`. Then, click the **Execute** button. + + The results will be similar to: + +
Prometheus Query Result +
Prometheus Query Result
+ + Other queries to try: + + - Total count of all requests to `productpage` service: + + ``` + request_count{destination_service="productpage.default.svc.cluster.local"} + ``` + + - Total count of all requests to `v3` of the `reviews` service: + + ``` + request_count{destination_service="reviews.default.svc.cluster.local", destination_version="v3"} + ``` + + This query returns the current total count of all requests to the v3 of the reviews service. + + - Rate of requests over the past 5 minutes to all `productpage` services: + + ``` + rate(request_count{destination_service=~"productpage.*", response_code="200"}[5m]) + ``` + +### About the Prometheus Add-on + +Mixer comes with a built-in [Prometheus](https://prometheus.io) adapter that +exposes an endpoint serving generated metric values. The Prometheus add-on is a +Prometheus server that comes pre-configured to scrape Mixer endpoints to collect +the exposed metrics. It provides a mechanism for persistent storage and querying +of Istio metrics. + +The configured Prometheus add-on scrapes three endpoints: +1. *istio-mesh* (`istio-mixer.istio-system:42422`): all Mixer-generated mesh + metrics. +1. *mixer* (`istio-mixer.istio-system:9093`): all Mixer-specific metrics. Used + to monitor Mixer itself. +1. *envoy* (`istio-mixer.istio-system:9102`): raw stats generated by Envoy (and + translated from statsd to prometheus). + +For more on querying Prometheus, please read their [querying +docs](https://prometheus.io/docs/querying/basics/). + +## Cleanup + +In Kubernetes environments, execute the following command to remove the +Prometheus add-on: + +```bash +kubectl delete -f install/kubernetes/addons/prometheus.yaml +``` + +## What's next + +* Try out the related telemetry tasks: + - [Using the Istio + Dashboard]({{home}}/docs/tasks/telemetry/using-istio-dashboard.html) + - [Generating an Istio Service + Graph]({{home}}/docs/tasks/telemetry/servicegraph.html) \ No newline at end of file diff --git a/_docs/tasks/telemetry/servicegraph.md b/_docs/tasks/telemetry/servicegraph.md new file mode 100644 index 0000000000..0ad026d21e --- /dev/null +++ b/_docs/tasks/telemetry/servicegraph.md @@ -0,0 +1,114 @@ +--- +title: Generating an Istio Service Graph + +overview: This task shows you how to generate a graph of services within an Istio mesh. + +order: 25 + +layout: docs +type: markdown +--- +{% include home.html %} + +This task shows you how to setup and use the Istio Dashboard to monitor mesh +traffic. As part of this task, you will install the Grafana Istio addon and use +the web-based interface for viewing service mesh traffic data. + +The [BookInfo]({{home}}/docs/guides/bookinfo.html) sample application is used as +the example application throughout this task. + +## Before you begin + +* [Install Istio]({{home}}/docs/setup/) in your cluster and deploy an + application. + +* Install the Prometheus add-on. Directions for install of this add-on are + supplied as part of the [Querying + Metrics]({{home}}/docs/tasks/telemetry/querying-metrics.html) Task. + + Use of the Prometheus add-on is _required_ for the Istio Dashboard. + +## Generating a Service Graph + +1. To view a graphical representation of your service mesh, install the + Servicegraph add-on. + + In Kubernetes environments, execute the following command: + + ```bash + kubectl apply -f install/kubernetes/addons/servicegraph.yaml + ``` + +1. Verify that the service is running in your cluster. + + In Kubernetes environments, execute the following command: + + ```bash + kubectl -n istio-system get svc servicegraph + ``` + + The output will be similar to: + + ``` + NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE + servicegraph 10.59.253.165 8088/TCP 30s + ``` + +1. Send traffic to the mesh. + + For the BookInfo sample, visit `http://$GATEWAY_URL/productpage` in your web + browser or issue the following command: + + ```bash + curl http://$GATEWAY_URL/productpage + ``` + + Refresh the page a few times (or send the command a few times) to generate a + small amount of traffic. + + Note: `$GATEWAY_URL` is the value set in the + [BookInfo]({{home}}/docs/guides/bookinfo.html) guide. + +1. Open the Servicegraph UI. + + In Kubernetes environments, execute the following command: + + ```bash + kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=servicegraph -o jsonpath='{.items[0].metadata.name}') 8088:8088 & + ``` + + Visit [http://localhost:8088/dotviz](http://localhost:8088/dotviz) in your web browser. + + The results will look similar to: + +
Example +Servicegraph
+ +### About the Servicegraph Add-on + +The Servicegraph service is an example service that provides endpoints for +generating and visualizing a graph of services within a mesh. It exposes the +following endpoints: + +- `/graph` which provides a JSON serialization of the servicegraph +- `/dotgraph` which provides a dot serialization of the servicegraph +- `/dotviz` which provides a visual representation of the servicegraph + +All endpoints take an optional argument of `time_horizon`, which controls the +timespan to consider for graph generation. + +All endpoints also take an optional argument of `filter_empty=true`, which will +restrict the nodes and edges shown to only those that reflect non-zero traffic +levels during the specified `time_horizon`. + +The Servicegraph example is built on top of Prometheus queries. + +## Cleanup + +In Kubernetes environments, execute the following command to remove the +ServiceGraph add-on: + +```bash +kubectl delete -f install/kubernetes/addons/servicegraph.yaml +``` \ No newline at end of file diff --git a/_docs/tasks/telemetry/using-istio-dashboard.md b/_docs/tasks/telemetry/using-istio-dashboard.md new file mode 100644 index 0000000000..43deb2a786 --- /dev/null +++ b/_docs/tasks/telemetry/using-istio-dashboard.md @@ -0,0 +1,122 @@ +--- +title: Using the Istio Dashboard + +overview: This task shows you how to setup and use the Istio Dashboard to monitor mesh traffic. + +order: 18 + +layout: docs +type: markdown +--- +{% include home.html %} + +This task shows you how to setup and use the Istio Dashboard to monitor mesh +traffic. As part of this task, you will install the Grafana Istio addon and use +the web-based interface for viewing service mesh traffic data. + +The [BookInfo]({{home}}/docs/guides/bookinfo.html) sample application is used as +the example application throughout this task. + +## Before you begin +* [Install Istio]({{home}}/docs/setup/) in your cluster and deploy an + application. + +* Install the Prometheus add-on. Directions for install of this add-on are + supplied as part of the [Querying + Metrics]({{home}}/docs/tasks/telemetry/querying-metrics.html) Task. + + Use of the Prometheus add-on is _required_ for the Istio Dashboard. + +## Viewing the Istio Dashboard + +1. To view Istio metrics in a graphical dashboard install the Grafana add-on. + + In Kubernetes environments, execute the following command: + + ```bash + kubectl apply -f install/kubernetes/addons/grafana.yaml + ``` + +1. Verify that the service is running in your cluster. + + In Kubernetes environments, execute the following command: + + ```bash + kubectl -n istio-system get svc grafana + ``` + + The output will be similar to: + + ``` + NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE + grafana 10.59.247.103 3000/TCP 2m + ``` + +1. Open the Istio Dashboard via the Grafana UI. + + In Kubernetes environments, execute the following command: + + ```bash + kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=grafana -o jsonpath='{.items[0].metadata.name}') 3000:3000 & + ``` + + Visit [http://localhost:3000/dashboard/db/istio-dashboard](http://localhost:3000/dashboard/db/istio-dashboard) in your web browser. + + The Istio Dashboard will look similar to: + +
Istio +Dashboard
+ +1. Send traffic to the mesh. + + For the BookInfo sample, visit `http://$GATEWAY_URL/productpage` in your web + browser or issue the following command: + + ```bash + curl http://$GATEWAY_URL/productpage + ``` + + Refresh the page a few times (or send the command a few times) to generate a + small amount of traffic. + + Look at the Istio Dashboard again. It should reflect the traffic that was + generated. It will look similar to: + +
+
Istio Dashboard With Traffic
+ + Note: `$GATEWAY_URL` is the value set in the + [BookInfo]({{home}}/docs/guides/bookinfo.html) guide. + + +### About the Grafana add-on + +The Grafana add-on is a pre-configured instance of Grafana. The base image +([`grafana/grafana:4.1.2`](https://hub.docker.com/r/grafana/grafana/)) has been +modified to start with both a Prometheus data source and the Istio Dashboard +installed. The base install files for Istio, and Mixer in particular, ship with +a default configuration of global (used for every service) metrics. The Istio +Dashboard is built to be used in conjunction with the default Istio metrics +configuration and a Prometheus backend. + +The Istio Dashboard consists of three main sections: +1. A Global Summary View. This section provides high-level summary of HTTP + requests flowing through the service mesh. +1. A Mesh Summary View. This section provides slightly more detail than the + Global Summary View, allowing per-service filtering and selection. +1. Individual Services View. This section provides metrics about requests and + responses for each individual service within the mesh (HTTP and TCP). + +For more on how to create, configure, and edit dashboards, please see the +[Grafana documentation](http://docs.grafana.org/). + +## Cleanup + +In Kubernetes environments, execute the following command to remove the Grafana +add-on: + +```bash +kubectl delete -f install/kubernetes/addons/grafana.yaml +```