Add docs for metrics (#1619)

* Add docs for metrics

* Formatting changes

* Add how-to page for accessing metrics in stackdriver

* More formatting and capitalization changes

* Add comment before the iam policy binding shell command

* Correct links in metrics.md

docs/examples/metrics/README.md

@@ -0,0 +1,124 @@
+# Metrics Example
+
+## Overview
+
+This sample shows how to configure and view `metrics`. This includes setting up metrics, generating them by sending
+events to a Broker with an attached Trigger and viewing those metrics with common filters in Stackdriver.
+
+## Prerequisites
+
+1. [Install Knative-GCP](../../install/install-knative-gcp.md)
+
+2. [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md)
+
+## Setup
+
+1. Follow the instructions here to [Access Metrics in Stackdriver](../../how-to/metrics.md).
+
+## Generating metrics
+
+This example will run everything in the cloud-run-events-example namespace.
+
+1. Create the namespace
+
+   ```shell
+   kubectl apply -f namespace.yaml
+   ```
+
+2. Deploy a Broker and event publisher
+
+   ```shell
+   kubectl apply -f broker.yaml
+   kubectl apply -f event-publisher.yaml
+   ```
+
+3. Verify that the Broker is ready
+
+    ```shell
+    kubectl -n cloud-run-events-example get broker test-broker
+    ```
+
+   ```shell
+   NAME          READY   REASON   URL                                                                                                         AGE
+   test-broker   True             http://default-brokercell-ingress.cloud-run-events.svc.cluster.local/cloud-run-events-example/test-broker   9s
+   ```
+
+4. Deploy a Trigger and event consumer
+
+   ```shell
+   kubectl apply -f trigger.yaml
+   kubectl apply -f event-consumer.yaml
+   ```
+
+5. Verify that the Trigger is ready
+
+    ```shell
+    kubectl -n cloud-run-events-example get trigger hello-display
+    ```
+
+    ```shell
+    NAME              READY   REASON   BROKER        SUBSCRIBER_URI                                                       AGE
+    hello-display     True             test-broker   http://hello-display.cloud-run-events-example.svc.cluster.local/     4s
+    ```
+
+6. ##### Send events to the Broker:
+    SSH into the event publisher Pod by running the following command:
+
+    ```shell
+    kubectl -n cloud-run-events-example attach curl -it
+    ```
+
+    A prompt similar to the one below will appear:
+
+    ```sh
+    Defaulting container name to curl.
+    Use 'kubectl describe pod/ -n cloud-run-events-example' to see all of the containers in this pod.
+    If you don't see a command prompt, try pressing enter.
+    [ root@curl:/ ]$
+    ```
+
+   Send multiple events like this to generate metrics:
+
+    ```sh
+    curl -v "http://default-brokercell-ingress.cloud-run-events.svc.cluster.local/cloud-run-events-example/test-broker" \
+      -X POST \
+      -H "Ce-Id: say-hello" \
+      -H "Ce-Specversion: 1.0" \
+      -H "Ce-Type: greeting" \
+      -H "Ce-Source: not-sendoff" \
+      -H "Content-Type: application/json" \
+      -d '{"msg":"Hello Cloud Run Events!"}'
+    ```
+
+## Viewing metrics
+In the [metrics explorer](https://console.cloud.google.com/monitoring/metrics-explorer) in Stackdriver, build the query
+to see metrics. There are multiple options to view the results of queries - Line, Stacked Bar, Stacked Area, Heatmap.
+
+#### Sample queries:
+
+-   Resource type: `Cloud run for Anthos Broker`  
+    Metric: `Broker event count`  
+    Filter: `project_id="<your_project_id">`  
+    Aggregator: `sum`
+
+    A line graph for the above query with 5 events sent to the Broker will look like this over a few minutes:
+
+    ![Alt text](broker_event_count.png)
+
+-   Resource type: `Cloud run for Anthos Trigger`  
+    Metric: `Event Dispatch Latencies`  
+    Filter: `project_id="<your_project_id>"`  
+    Aggregator: `50th percentile`
+
+    A stacked bar graph for the above query with 5 events received by the Trigger will look this over a few minutes:
+
+    ![Alt text](trigger_latencies.png)
+
+## Cleaning up
+```shell
+kubectl delete -f event-publisher.yaml
+kubectl delete -f event-consumer.yaml
+kubectl delete -f trigger.yaml
+kubectl delete -f broker.yaml
+kubectl delete -f namespace.yaml
+```

docs/examples/metrics/broker.yaml

@@ -0,0 +1,21 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: eventing.knative.dev/v1beta1
+kind: Broker
+metadata:
+  name: test-broker
+  namespace: cloud-run-events-example
+  annotations:
+    "eventing.knative.dev/broker.class": "googlecloud"

docs/examples/metrics/event-consumer.yaml

@@ -0,0 +1,49 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: hello-display
+  namespace: cloud-run-events-example
+spec:
+  replicas: 1
+  selector:
+    matchLabels: &labels
+      app: hello-display
+  template:
+    metadata:
+      labels: *labels
+    spec:
+      containers:
+        - name: event-display
+          # Source code: https://github.com/knative/eventing-contrib/tree/master/cmd/event_display
+          image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display:latest
+
+---
+
+# Service pointing at the previous Deployment. This will be the target for event
+# consumption.
+  kind: Service
+  apiVersion: v1
+  metadata:
+    name: hello-display
+    namespace: cloud-run-events-example
+  spec:
+    selector:
+      app: hello-display
+    ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 8080

docs/examples/metrics/event-publisher.yaml

@@ -0,0 +1,30 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: v1
+kind: Pod
+metadata:
+  labels:
+    run: curl
+  name: curl
+  namespace: cloud-run-events-example
+spec:
+  containers:
+    # This could be any image that we can SSH into and has curl.
+  - image: radial/busyboxplus:curl
+    imagePullPolicy: IfNotPresent
+    name: curl
+    resources: {}
+    stdin: true
+    tty: true

docs/examples/metrics/namespace.yaml

@@ -0,0 +1,20 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: cloud-run-events-example
+  labels:
+    events.cloud.google.com/release: devel

docs/examples/metrics/trigger.yaml

@@ -0,0 +1,26 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: eventing.knative.dev/v1beta1
+kind: Trigger
+metadata:
+  name: hello-display
+  namespace: cloud-run-events-example
+spec:
+  broker: test-broker
+  subscriber:
+    ref:
+      apiVersion: v1
+      kind: Service
+      name: hello-display

docs/how-to/metrics.md

@@ -0,0 +1,52 @@
+# Accessing Metrics in Stackdriver
+
+## Enable the Metrics API
+
+In cloud console, navigate to
+[`Monitoring > Metrics explorer`](https://console.cloud.google.com/monitoring/metrics-explorer). Enable the monitoring
+metrics API and add your project to a workspace (or create a new workspace).
+
+## Add the Monitoring Metric Writer Role to the Dataplane Service Account
+
+Determine the Google Service Account your data plane is running as. If you followed
+[Install Knative-GCP](../install/install-knative-gcp.md) or
+[Create a Service Account for the Data Plane](../install/dataplane-service-account.md), then the Google Service
+Account will be named `cre-dataplane@$PROJECT_ID.iam.gserviceaccount.com`. The following command uses that name. If the
+Google Service Account you are using is different, then replace it before running the command.
+
+```shell
+gcloud projects add-iam-policy-binding $PROJECT_ID \
+  --member=serviceAccount:cre-dataplane@$PROJECT_ID.iam.gserviceaccount.com \
+  --role roles/monitoring.metricWriter
+```
+
+## Enable Metrics in the `config-observability` ConfigMap
+
+Edit the `config-observability` ConfigMap under the `cloud-run-events` namespace in Cloud Console or with the following
+`kubectl` command:
+
+```shell
+kubectl edit configmap -n cloud-run-events config-observability
+```
+
+and add the following entries:
+
+```
+metrics.backend-destination: stackdriver
+metrics.stackdriver-project-id: "<your stackdriver project id>" # Replace with your project's ID.
+metrics.reporting-period-seconds: "60"
+```
+
+## Accessing metrics in Cloud Console
+
+Navigate to
+[`Monitoring > Metrics explorer`](https://console.cloud.google.com/monitoring/metrics-explorer) and build a query to
+see metrics. An example query would look like:
+
+-   Resource type: `Cloud run for Anthos Broker`  
+    Metric: `Broker event count`  
+    Filter: `project_id="<your_project_id">`  
+    Aggregator: `sum`
+
+A graphical view should be displayed on canvas as the query result. The graph can be viewed in different formats like
+Line, Stacked Bar, Stacked Area, Heatmap, depending on the aggregator.