[3] grafana and docs updates (#6)

README.md

@@ -17,6 +17,8 @@ Track [Docker Events](https://docs.docker.com/engine/reference/commandline/event
 
 Head on over to the [Install](https://philosowaffle.github.io/docgraf/) page to get started!
 
+![DocGraf Demo](/images/docgraf_demo.gif?raw=true "DocGraf Demo")
+
 ## Contributors
 
 Special thanks to all the [contributors](https://github.com/philosowaffle/docgraf/graphs/contributors) who have helped improve this project!

configuration.example.json

@@ -7,7 +7,7 @@
   },
 
   "Grafana": {
-    "ApiKey":  "",
+    "ApiKey": "",
     "Uri": "http://grafana:3000"
   },
 

docs/Gemfile.lock

@@ -284,4 +284,4 @@ DEPENDENCIES
   tzinfo-data
 
 BUNDLED WITH
-   2.2.29
+   2.3.22

docs/_config.yml

@@ -1,5 +1,5 @@
 title: DocGraf
-description: Publish annotations to Grafana based on Docker Events.
+description: Track Docker Events as Annotations on https://grafana.com/grafana/.
 repository: philosowaffle/docgraf
 locale: en_US
 

docs/configuration/index.md

@@ -1,58 +1,14 @@
 ---
 layout: default
 title: Configuration
-nav_order: 3
+nav_order: 2
 has_children: true
 ---
 
 # Configuration
 
-DocGraf supports configuration via [command line arguments]({{ site.baseurl }}{% link configuration/command-line.md %}), [environment variables]({{ site.baseurl }}{% link configuration/environment-variables.md %}), and [json config file]({{ site.baseurl }}{% link configuration/json.md %}). By default, DocGraf looks for a file named `configuration.local.json` in the same directory where it is run.  This is the preferred way to provide configuration details to DocGraf.
+DocGraf supports configuration via [command line arguments]({{ site.baseurl }}{% link configuration/command-line.md %}), [environment variables]({{ site.baseurl }}{% link configuration/environment-variables.md %}), and [json config file]({{ site.baseurl }}{% link configuration/json.md %}). By default, DocGraf looks for a file named `configuration.local.json` in the same directory where it is run.
 
-## Example Config
-
-```json
-{
-  "Docker": {
-    "Uri": "http://docker-proxy:2375",
-    "ContainerEvents": [ "start", "stop", "restart" ]
-  },
-
-  "Grafana": {
-    "ApiKey":  "",
-    "Uri": "http://grafana:3000"
-  },
-
-  "Observability": {
-
-    "Prometheus": {
-      "Enabled": false,
-      "Port": 4000
-    },
-
-    "Tracing": {
-      "Enabled": true,
-      "Url": "http://localhost:4317"
-    },
-
-    "Serilog": {
-      "Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.File" ],
-      "MinimumLevel": "Information",
-      "WriteTo": [
-        { "Name": "Console" },
-        {
-          "Name": "File",
-          "Args": {
-            "path": "./output/log.txt",
-            "rollingInterval": "Day",
-            "retainedFileCountLimit": 7
-          }
-        }
-      ]
-    }
-  }
-}
-```
 
 ## Config Precedence
 
@@ -62,8 +18,8 @@ The following defines the precedence in which config definitions are honored. Wi
 1. Environment Variables
 1. Config File
 
-For example, if you defined your Peloton credentials ONLY in the Config file, then the Config file credentials will be used.
+For example, if you defined a setting ONLY in the Config file, then the Config file setting will be used.
 
-If you defined your credentials in both the Config file AND the Environment variables, then the Environment variable credentials will be used.
+If you defined a setting in both the Config file AND the Environment variables, then the Environment variable setting will be used.
 
-If you defined credentials using all 3 methods (config file, env, and command line), then the credentials provided via the command line will be used.
+If you defined a setting using all 3 methods (config file, env, and command line), then the setting provided via the command line will be used.

docs/configuration/json.md

@@ -7,23 +7,17 @@ nav_order: 0
 
 # Json Config File
 
-This is the preferred way to provide configuration details to DocGraf.  By default, DocGraf looks for a file named `configuration.local.json` in the same directory where the program is run.
-
-The config file is written in JSON and supports hot-reload for all fields except the following:
-
-1. `Observability` Section
-
 The config file is organized into the below sections.
 
 | Section      | Description       |
 |:-------------|:------------------|
-| [Docker Config](#format-config) | This section provides settings related to Docker.  |
-| [Grafana Config](#peloton-config) | This section provides settings related to Grafana.      |
+| [Docker Config](#docker-config) | This section provides settings related to Docker.  |
+| [Grafana Config](#grafana-config) | This section provides settings related to Grafana.      |
 | [Observability Config](#observability-config) | This section provides settings related to Metrics, Logs, and Traces for monitoring purposes. |
 
 ## Docker Config
 
-This section provides settings related to connecting to the Docker daemon and which events should be acted on.
+This section provides settings related to connecting to the Docker daemon and which events should be published as Annotations to Grafana.
 
 ```json
 "Docker": {
@@ -55,11 +49,11 @@ This section provides settings related to connecting to the Docker daemon and wh
 
 ## Grafana Config
 
-This section provides settings related to connecting and publishing annotations to Grafana.
+This section provides settings related to connecting to Grafana.
 
 ```json
 "Grafana": {
-    "ApiKey":  "yourApiKey==",
+    "ApiKey": "yourApiKey==",
     "Uri": "http://grafana:3000"
   },
 ```
@@ -71,7 +65,7 @@ This section provides settings related to connecting and publishing annotations
 
 ## Observability Config
 
-DocGraf supports publishing OpenTelemetry Metrics, Logs, and Trace. This section provides settings related to those pillars.
+DocGraf supports publishing OpenTelemetry Metrics, Logs, and Traces. This section provides settings related to those pillars.
 
 The Observability config section contains three main sub-sections:
 
@@ -133,8 +127,6 @@ If you are using Docker, ensure you have exposed the port from your container.
     scrape_interval: 60s
     static_configs:
       - targets: [<docgrafIPaddress>:<docgrafPort>]
-    tls_config:
-      insecure_skip_verify: true
 ```
 
 ### Tracing Config
@@ -156,7 +148,13 @@ If you are using Docker, ensure you have exposed the port from your container.
 ```json
 "Serilog": {
       "Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.File",  "Serilog.Sinks.Grafana.Loki" ],
-      "MinimumLevel": "Debug",
+      "MinimumLevel": {
+        "Default": "Information",
+        "Override": {
+          "Microsoft": "Error",
+          "System": "Error"
+        }
+      },
       "WriteTo": [
         { "Name": "Console" },
         {

docs/features/annotations.md

@@ -0,0 +1,27 @@
+---
+layout: default
+title: Grafana Annotations
+parent: Features
+nav_order: 0
+---
+
+# Grafana Annotations
+
+DocGraf can be [configured]({{ site.baseurl }}{% link configuration/index.md %}#docker-config) to publish [Grafana Annotations](https://grafana.com/docs/grafana/v9.0/dashboards/annotations/) for specific [Docker Events](https://docs.docker.com/engine/reference/commandline/events/).  When a configured event occurrs, DocGraf will publish that event as an Annotation to Grafana with the following information:
+
+* *Text*: `<event> <container> <tag>`
+* *Timestamp* of the event
+* Tags:
+	* Event Type
+	* Event
+	* Container
+	* Image
+	* Image Tag
+
+These annotations can be visualized in several ways on Grafana such as a list of recent events:
+
+![Grafana Annotations List](https://github.com/philosowaffle/docgrag/raw/main/images/annotations_list.png?raw=true "Grafana Annotations List")
+
+Or overlayed on top of other charts to correlate container events with out system metrics:
+
+![Annotation Overlay Demo](https://github.com/philosowaffle/docgrag/raw/main/images/annotation_overlay_demo.png?raw=true "Annotation Overlay Demo")

docs/features/index.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: Features
+nav_order: 3
+has_children: true
+---
+
+# Features
+
+In the DocGraf repo there is a [sample Grafana Dashboard](https://github.com/philosowaffle/docgraf/tree/main/grafana/grafana_dashboard.json) that demonstrates several different ways to use these features.

docs/features/metrics.md

@@ -0,0 +1,25 @@
+---
+layout: default
+title: Prometheus Metrics
+parent: Features
+nav_order: 1
+---
+
+# Prometheus Metrics
+
+DocGraf can be [configured]({{ site.baseurl }}{% link configuration/index.md %}#metrics-config) to expose [Prometheus Metrics](https://prometheus.io/).  The metrics exposed are grouped into two categories:
+
+1. `docgraf_docker_events_recv`
+	1. This metric will always capture all received events from the Docker daemon
+1. `docgraf_docker_events_recorded`
+	1. This metric will be a subset of `docgraf_docker_events_recv`, it is only the events that were recorded as Annotations
+
+Both metrics expose the following labels:
+
+1. Event Type
+1. Event
+1. Container
+1. Image
+1. Image Tag
+
+![Grafana Metrics Example](https://github.com/philosowaffle/docgrag/raw/main/images/metrics_example.png?raw=true "Grafana Metrics Example")

docs/index.md

@@ -6,19 +6,20 @@ nav_order: 0
 
 # Home
 
-Publish annotations to Grafana based on Docker Events.
+Track [Docker Events](https://docs.docker.com/engine/reference/commandline/events/) as [Annotations](https://grafana.com/docs/grafana/v9.0/dashboards/annotations/) on [Grafana](https://grafana.com/grafana/). 
 
-* Configure which events should create an Annotation
-* Events are tagged with Container, Event, and Type for easy filtering
+* Configure which Docker Events to monitor
+* Expose Prometheus metrics for Docker Events
+* Events are tagged with the following for robust filtering and querying
+	* Docker Event Type
+	* Docker Event
+	* Container
+	* Image
+	* Tag
 
 Head on over to the [Install]({{ site.baseurl }}{% link install/index.md %}) page to get started!
 
-## Supported Platforms
-
-* Windows
-* Mac
-* Linux
-* Docker
+![Docgraf Demo](https://github.com/philosowaffle/docgrag/raw/main/images/docgraf_demo.gif?raw=true "DocGraf Demo")
 
 ## Contributors
 

docs/install/docker.md

@@ -7,63 +7,48 @@ nav_order: 0
 
 # Docker
 
-The recommended and easiest way to get started is with Docker. To learn more about Docker head on over to their [website](https://www.docker.com/).
+The recommended and easiest way to get started is with [Docker](https://www.docker.com/).
 
 ## docker-compose
 
-A sample [docker-compose.yaml](https://github.com/philosowaffle/docgraf/blob/master/docker-compose.yaml) file and [configuration.local.json](https://github.com/philosowaffle/docgraf/blob/master/configuration.example.json) can be found in the project repo.
-
-The Docker container expects a valid `configuration.local.json` file is mounted into the container.  You can learn more about the configuration file over in the [Configuration Section](/{{ site.baseurl }}{% link configuration/index.md %}).
-
-```yaml
-version: "3.9"
-services:
-  docgraf:
-    image: philosowaffle/docgraf
-    container_name: docgraf
-    restart: unless-stopped
-    environment:
-      - TZ=America/Chicago
-    volumes:
-      - ./configuration.local.json:/app/configuration.local.json
-
-  docker-proxy: 
-    image: tecnativa/docker-socket-proxy
-    container_name: docker-proxy 
-    restart: unless-stopped 
-    environment: 
-      - TZ=America/Chicago
-    volumes:
-        - /var/run/docker.sock:/var/run/docker.sock:ro
-```
+*Pre-requisite:* You have either `docker-compose` or `Docker Desktop` installed
+
+1. Create a directory `docgraf`
+    1. Inside this folder create a [docker-compose.yaml](https://github.com/philosowaffle/docgraf/blob/main/docker/docker-compose.yaml) file in the directory
+    1. Also create a [configuration.local.json](https://github.com/philosowaffle/docgraf/blob/main/configuration.example.json) file in the directory.
+1. Edit the config file to set your Grafana host and Service Account token
+1. Open a terminal in this folder
+1. Run: `docker-compose pull && docker-compose up -d`
+
+You can learn more about customizing your configuration over in the [Configuration Section]({{ site.baseurl }}{% link configuration/index.md %}).
 
 ### Docker Daemon
 
-It is recommened to run DocGraf against a docker proxy like `tecnativa/docker-socket-proxy`.
-
-### Prometheus
-
-If you configure DocGraf to serve Prometheus metrics then you will also need to map the corresponding port for your docker container. By default, Prometheus metrics will be served on port `4000`. You can learn more about DocGraf and Prometheus in the [Observability Configuration]({{ site.baseurl }}{% link configuration/index.md %}) section.
-
-```yaml
-version: "3.9"
-services:
-  docgraf:
-    image: philosowaffle/docgraf
-    container_name: docgraf
-    restart: unless-stopped
-    environment:
-      - TZ=America/Chicago
-    ports:
-      - 4000:4000
-    volumes:
-      - ./configuration.local.json:/app/configuration.local.json
+It is recommened to run DocGraf against a docker proxy like the provided `tecnativa/docker-socket-proxy`.
+
+## Repositories
+
+### [DockerHub](https://hub.docker.com/r/philosowaffle/docgraf)
+
+```bash
+docker run -v /full/path/to/configuration.local.json:/app/configuration.local.json -v /full/path/to/output:/app/output philosowaffle/docgraf:stable
 ```
 
-## Docker Tags
+### [GitHub Package](https://github.com/philosowaffle/docgraf/pkgs/container/docgraf)
 
-The DocGraf docker image is available on [DockerHub](https://hub.docker.com/r/philosowaffle/docgraf). The following tags are provided:
+```bash
+docker run -v /full/path/to/configuration.local.json:/app/configuration.local.json -v /full/path/to/output:/app/output ghcr.io/philosowaffle/docgraf:stable
+```
+
+## Tags
 
 1. `stable` - Always points to the latest release
-1. `latest` - The bleeding edge of the master branch
-1. `vX.Y.Z` - For using a specific released version
+1. `latest` - The bleeding edge of the master branch, breaking changes may happen
+1. `X.Y.Z` - For using a specific released version
+
+## Docker User
+
+The images run the process under the user and group `docgraf:docgraf` with uid and gid `1019:1019`.  To access files created by `docgraf`:
+
+1. Create a group on the local machine `docgraf` with group id `1019`
+1. Add your user on the local machine to the `docgraf` group