[docs.targets] Improve targets documentation.

docs/content/docs/how-to/targets/index.md

@@ -11,29 +11,29 @@ date: 2016-10-25T17:24:32-07:00
 Cloudprober probes usually run against some targets[^1] to check those targets'
 status, such as an HTTP probe to your APIs servers, or PING/TCP probes to a
 third-party provider to verify network connectivity to them. Each probe can have
-multiple targets. If a probe has multiple targets, Cloudprober runs concurrent
-probes against each target. This page further explains how targets work in
+multiple targets. If a probe has multiple targets, Cloudprober runs parallel
+probes for each target. This page further explains how targets work in
 Cloudprober.
 
+[^1]:
+    There are some cases where there is no explicit target, for example, you may
+    run a probe to measure your CI system's performance, or run a complex probe
+    that touches many endpoints.
+
 {{< figure src=targets.svg width=350 >}}
 
 ## Dynamically Discovered Targets
 
 One of the core features of Cloudprober is the automatic and continuous
-discovery of targets. This feature is especially critical for the dynamic
-environments that today's cloud based deployments make possible. For exmaple in
+discovery of targets. This feature is especially important for the dynamic
+environments that today's cloud based deployments make possible. For example in
 a kubernetes cluster the number of pods and their IPs can change on the fly,
 either in response to replica count changes or node failures. Automated targets
 discovery makes sure that we don't have to reconfigure Cloudprober in response
 to such events.
 
 {{< figure src=targets2.svg width=350 >}}
 
-[^1]:
-    There are some cases where there is no explicit target, for example, you may
-    run a probe to measure your CI system's performance, or run a complex probe
-    that touches many endpoints.
-
 ## Targets Configuration
 
 Cloudprober provides multiple ways to configure targets for a probe.
@@ -52,10 +52,37 @@ probe {
 }
 ```
 
-In the above config, probe will run concurrently against 3 hosts:
+In the above config, probe will run against 3 hosts in parallel:
 _www.google.com_, _www.yahoo.com_, and _cloudprober:9313_ (yes, you can specify
 ports here for port-aware probes).
 
+You can specify more detailed targets using the
+[`endpoints`](/docs/config/targets/#cloudprober_targets_TargetsDef) field. Using
+endpoints, you can even specify the URL directly in target definition; this
+method is particularly useful if you want to run an HTTP probe for multiple
+similar targets.
+
+```shell
+probe {
+  type: HTTP
+  ...
+  targets {
+    endpoints {
+      # This will probe https://web.example.com/url1, target will show up as
+      # "frontend_main" in metrics.
+      name: "frontend_main"
+      url: "https://web.example.com/url1"
+    }
+    endpoints {
+      # This will probe http://cms.example.com, target will show up as
+      # "cms.example.com" in metrics.
+      name: "cms.example.com"
+    }
+  }
+  ..
+}
+```
+
 ### File based targets
 
 You can define your targets in a file and refer to them in Cloudprober through

docs/layouts/index.html

@@ -41,8 +41,8 @@ <h2 class="h3" style="font-weight:700">Trusted by multiple large organizations</
         <h2 class="h3" style="font-weight:700">Easy integration</h2>
         <p style="font-weight:400">
           Out of the box, config based, integration with many popular monitoring
-          systems: Prometheus, Grafana, DataDog, PostgreSQL, AWS Cloudwatch,
-          Stackdriver, and more.
+          and alerting systems: Prometheus, Grafana, DataDog, PostgreSQL, AWS Cloudwatch,
+          Stackdriver, PagerDuty, Opsgenie, and more.
         </p>
       </div>
     </div>
@@ -64,7 +64,7 @@ <h2 class="h3" style="font-weight:700">Automated targets discovery</h2>
       <div class="col-lg-5">
         <h2 class="h3" style="font-weight:700">Deployment friendly</h2>
         <p>
-          Written entirely in Go. Available as standalone static binary or
+          Written entirely in Go. Available as a standalone static binary or
           through a docker image. Multiple ways to configure, including
           environment variables.
         </p>

targets/proto/targets.proto

@@ -77,22 +77,23 @@ message K8sTargets {
 }
 
 message Endpoint {
-  // Resource name.
+  // Endpoint name. Metrics for a target are identified by a combination of
+  // endpoint name and port name, if specified.
   required string name = 1;
 
-  // Resource's IP address. If not specified, resource name is DNS resolved.
+  // Optional IP address. If not specified, endpoint name is DNS resolved.
   optional string ip = 2;
 
-  // Resource's port. If specified, this port will be used by the port-based
+  // Endpoint port. If specified, this port will be used by the port-based
   // probes (e.g.  TCP, HTTP), if probe's configuration doesn't specify a port.
   optional int32 port = 3;
 
-  // Resource's URL. If provided, this field is used by the HTTP probe, if
+  // HTTP probe URL. If provided, this field is used by the HTTP probe, if
   // probe configuration itself doesn't specify URL fields.
   optional string url = 4;
 
-
-  // Resource's labels, if any.
+  // Endpoint labels. These labels can be exported as metrics labels using the
+  // `additional_label` field in the probe configuration.
   map<string, string> labels = 5;
 }
 

targets/proto/targets_proto_gen.cue

@@ -75,21 +75,23 @@ import (
 }
 
 #Endpoint: {
-	// Resource name.
+	// Endpoint name. Metrics for a target are identified by a combination of
+	// endpoint name and port name, if specified.
 	name?: string @protobuf(1,string)
 
-	// Resource's IP address. If not specified, resource name is DNS resolved.
+	// Optional IP address. If not specified, endpoint name is DNS resolved.
 	ip?: string @protobuf(2,string)
 
-	// Resource's port. If specified, this port will be used by the port-based
+	// Endpoint port. If specified, this port will be used by the port-based
 	// probes (e.g.  TCP, HTTP), if probe's configuration doesn't specify a port.
 	port?: int32 @protobuf(3,int32)
 
-	// Resource's URL. If provided, this field is used by the HTTP probe, if
+	// HTTP probe URL. If provided, this field is used by the HTTP probe, if
 	// probe configuration itself doesn't specify URL fields.
 	url?: string @protobuf(4,string)
 
-	// Resource's labels, if any.
+	// Endpoint labels. These labels can be exported as metrics labels using the
+	// `additional_label` field in the probe configuration.
 	labels?: {
 		[string]: string
 	} @protobuf(5,map[string]string)