Merge pull request #23 from loburm/update-documentation

Add simple documentation for prometheus-to-sd.

hack/verify-flags/exceptions.txt

@@ -4,5 +4,6 @@ kubelet-to-gcm/monitor/kubelet/translate.go:				"namespace_id":   namespace,
 kubelet-to-gcm/monitor/kubelet/translate.go:				"pod_id":         podID,
 kubelet-to-gcm/monitor/kubelet/translate.go:		"namespace_id":   "",
 kubelet-to-gcm/monitor/kubelet/translate.go:		"pod_id":         "machine",
+prometheus-to-sd/README.md:the prometheus-to-sd. Values of the `namespace_id` and `pod_id` can be passed to
 prometheus-to-sd/translator/translator.go:		"namespace_id":   config.PodConfig.NamespaceId,
 prometheus-to-sd/translator/translator.go:		"pod_id":         config.PodConfig.PodId,

prometheus-to-sd/README.md

@@ -0,0 +1,48 @@
+# Overview
+
+prometheus-to-sd is a simple component that can scrape metrics stored in
+[prometheus text format](https://prometheus.io/docs/instrumenting/exposition_formats/)
+from one or multiple components and push them to the Stackdriver. Main requirement:
+k8s cluster should run on GCE or GKE.
+
+## Container Image
+
+The latest container image can be found at
+`gcr.io/google-containers/prometheus-to-sd:v0.2.1`.
+
+# Usage
+
+For scraping metrics from the component it's name, host, port and metrics should passed
+through the flag `source` in the next format:
+`component-name:http://host:port?whitelisted=a,b,c`. If whitelisted part is
+omitted, then all metrics that are scraped from the component will be pushed
+to the Stackdriver.
+
+## Custom metrics
+
+To be able to push custom metrics to the Stackdriver flag `metrics-prefix=custom.googleapis.com`
+has to be specified. In such case metric `bar` from the component
+`foo` is going to be pushed to the Stackdriver as `custom.googleapis.com/foo/bar`.
+
+## Metrics autodiscovery
+
+If metric descriptors already exist on the Stackdriver (created manually or by different component)
+then autodiscovery feature could be used. In such case prometheus-to-sd will push metrics for
+which metric descriptors are available on the Stackdriver. To use this feature a flag
+`auto-whitelist-metrics=true` has to be passed.
+
+## Resource descriptor
+
+Each pushed metric includes [monitored resource
+descriptor](https://cloud.google.com/logging/docs/api/v2/resource-list#resource-types). Fields, such as
+`project_id`, `cluster_name`, `instance_id` and `zone` are filled automatically by
+the prometheus-to-sd. Values of the `namespace_id` and `pod_id` can be passed to
+the component through the additional flags or omitted. `container_name` is
+always empty for now.
+
+## Deployment
+
+Example of [deployment](https://github.com/GoogleCloudPlatform/k8s-stackdriver/blob/master/prometheus-to-sd/kubernetes/prometheus-to-sd-kube-state-metrics.yaml)
+used to monitor
+[kube-state-metrics](https://raw.githubusercontent.com/kubernetes/kube-state-metrics) component, that is used to collect
+different metrics about the state of k8s cluster.

prometheus-to-sd/kubernetes/prometheus-to-sd-kube-state-metrics.yaml

@@ -0,0 +1,45 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: kube-metrics
+spec:
+  hostNetwork: true
+  containers:
+  - name: kube-state-metrics
+    image: gcr.io/google_containers/kube-state-metrics:v1.0.0-rc.1
+    ports:
+      - name: http-metrics
+        containerPort: 8080
+    readinessProbe:
+      httpGet:
+        path: /healthz
+        port: 8080
+      initialDelaySeconds: 5
+      timeoutSeconds: 5
+    resources:
+      requests:
+        memory: 200Mi
+        cpu: 100m
+      limits:
+        memory: 300Mi
+        cpu: 200m
+  - name: prometheus-to-sd
+    image: gcr.io/google-containers/prometheus-to-sd:v0.2.1
+    ports:
+      - name: profiler
+        containerPort: 6060
+    command:
+      - /monitor
+      - --stackdriver-prefix=custom.googleapis.com
+      - --source=kube-state-metrics:http://localhost:8080
+      - --pod-id=$(POD_NAME)
+      - --namespace-id=$(POD_NAMESPACE)
+    env:
+      - name: POD_NAME
+        valueFrom:
+          fieldRef:
+            fieldPath: metadata.name
+      - name: POD_NAMESPACE
+        valueFrom:
+          fieldRef:
+            fieldPath: metadata.namespace