[extentions/observers] add endpoint and example config to docker read…

…me (#6420)

extension/observer/dockerobserver/README.md

@@ -2,35 +2,62 @@
 
 **Status: beta**
 
-The `docker_observer` uses a Docker client and queries the Docker Engine API for running containers.
+The Docker observer extension is a [Receiver Creator](../../../receiver/receivercreator/README.md)-compatible "watch observer" that will detect and report
+container endpoints discovered through the Docker API. Only containers that are in the state of `Running` and not `Paused` will emit endpoints.
+This observer watches the Docker engine's stream of events to dynamically create, update, and remove endpoints as events are processed.
 
 Requires Docker API Version 1.22+.
 
 The collector will need permissions to access the Docker Engine API, specifically it will need
 read access to the Docker socket (default `unix:///var/run/docker.sock`).
 
 
-### Configuration
+## Example Config
 
-#### `endpoint`
+```yaml
+extensions:
+  docker_observer:
+    # url of the docker socket, default to unix:///var/run/docker.sock
+    endpoint: my/path/to/docker.sock
+    # list of container image names to exclude
+    excluded_images: ['redis', 'another_image_name']
+    # client API version, default to 1.22
+    api_version: 1.24
+    # max amount of time to wait for a response from Docker API , default to 5s
+    timeout: 15s
+
+receivers:
+  receiver_creator:
+    watch_observers: [docker_observer]
+    receivers:
+      nginx:
+        rule: type == "container" and name matches "nginx" and port == 80
+        config:
+          endpoint: '`endpoint`/status'
+          collection_interval: 10s
+```
+
+## Configuration
+
+### `endpoint`
 
 The URL of the docker server.
 
 default: `unix:///var/run/docker.sock`
 
-#### `timeout`
+### `timeout`
 
 The maximum amount of time to wait for docker API responses.
 
 default: `5s`
 
-#### `excluded_images`
+### `excluded_images`
 
 A list of filters whose matching images are to be excluded. Supports literals, globs, and regex.
 
 default: `[]`
 
-#### `use_hostname_if_present`
+### `use_hostname_if_present`
 
 If true, the `Config.Hostname` field (if present) of the docker
 container will be used as the discovered host that is used to configure
@@ -40,28 +67,41 @@ in the output of the Docker API's [Container Inspect](https://docs.docker.com/en
 
 default: `false`
 
-#### `use_host_bindings`
+### `use_host_bindings`
 
 If true, the observer will configure receivers for matching container endpoints
 using the host bound ip and port.  This is useful if containers exist that are not
 accessible to an instance of the collector running outside of the docker network stack.
 
 default: `false`
 
-#### `ignore_non_host_bindings`
+### `ignore_non_host_bindings`
 
 If true, the observer will ignore discovered container endpoints that are not bound
 to host ports.  This is useful if containers exist that are not accessible
 to an instance of the collector running outside of the docker network stack.
 
 default: `false`
 
-#### `cache_sync_interval`
+### `cache_sync_interval`
 
 The time to wait before resyncing the list of containers the observer maintains
 through the docker event listener example: `cache_sync_interval: "20m"`
 
 default: `60m`
 
-### Endpoint Variables
-`TODO in subsequent PR`
+## Endpoint Variables
+
+The following endpoint variables are exposed to the receiver creator to be used in discovery rules:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| name | string | Primary name of the container |
+| image | string | Name of the container image |
+| port | uint16 | Exposed port of the container |
+| alternate_port | uint16 | Exposed port accessed through redirection, such as a mapped port |
+| command | string | The command used to invoke the process of the container |
+| container_id | string | ID of the container |
+| host | string | Hostname or IP of the underlying host the container is running on |
+| transport | string | Transport protocol used by the endpoint (TCP or UDP) |
+| labels | map[string]string | User-specified metadata labels on the container |