Merge pull request #23 from backmarket-oss/change-metric-spec

Simplify interpretation of produced metrics

.gitignore

@@ -1,2 +1,2 @@
-
+.venv
 dist/

.jsfh-conf.yaml

@@ -0,0 +1,8 @@
+---
+template_name: md
+template_md_options:
+  properties_table_columns:
+    - Property
+    - Type
+    - Title/Description
+footer_show_time: false

.pre-commit-config.yaml

@@ -1,5 +1,10 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
+default_install_hook_types:
+- pre-commit
+- pre-push
+default_stages:
+- pre-commit
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0
@@ -9,34 +14,38 @@ repos:
   - id: check-yaml
     exclude: ^charts/kube-transition-metrics/templates/
   - id: check-added-large-files
-- repo: https://github.com/golangci/golangci-lint
-  rev: v1.52.2
-  hooks:
-  - id: golangci-lint
-    name: golangci-lint
-    description: Fast linters runner for Go.
-    entry: golangci-lint run --timeout=2m --fix --out-format checkstyle
-    types: [go]
-    language: golang
-    pass_filenames: false
 - repo: https://github.com/dnephin/pre-commit-golang
   rev: v0.5.1
   hooks:
   - id: go-fmt
   - id: golangci-lint
+    args:
+    - --timeout=5m
   - id: go-mod-tidy
+- repo: local
+  hooks:
+    - id: json-schema-for-humans
+      name: json-schema-for-humans
+      description: Generate doc/SCHEMA.md with https://github.com/coveooss/json-schema-for-humans
+      entry: bash -c 'python -m venv .venv && source .venv/bin/activate && pip install --quiet json-schema-for-humans && generate-schema-doc --config-file .jsfh-conf.yaml internal/logging/schemas doc/SCHEMA.md'
+      language: system
+      files: internal/logging/schemas
+      types:
+      - json
 - repo: local
   hooks:
   - id: trufflehog
     name: TruffleHog
     description: Detect secrets in your data.
     entry: bash -c 'docker run --rm -v "$PWD:/src" ghcr.io/trufflesecurity/trufflehog:latest git --branch=HEAD file:///src --fail --only-verified'
     language: system
-    stages: ["commit", "push"]
+    stages:
+    - pre-push
 - repo: local
   hooks:
   - id: semgrep
     name: semgrep
     entry: bash -c 'docker run --rm -v "$PWD:/src" returntocorp/semgrep semgrep --config p/ci --error --skip-unknown-extensions'
     language: system
-    stages: ["commit", "push"]
+    stages:
+    - pre-push

README.md

@@ -68,8 +68,105 @@ podAnnotations:
 
 ## Available metrics
 
-For a detailed overview of available metrics, see
-[internal/statistics/README.md](internal/statistics/README.md).
+This Pod life-cycle statistics are emitted in JSON format to `stdout`.
+These logs can be integrated with log processing pipelines like ELK or DataDog.
+Distinguish metric logs from debug and informative logs by the presence of a
+top-level `kube_transition_metrics` key.
+
+### Log Structure
+
+All non-metric logs include a top-level `level` key, which can be: `debug`,
+`info`, `warn`, `error`, or `panic`.
+Non-metric logs are sent to `stderr`, whereas life-cycle metrics are sent to
+`stdout`.
+
+### Examples:
+
+A complete pod record:
+
+```json
+{
+  "kube_transition_metrics": {
+    "type": "pod",
+    "kube_namespace": "default",
+    "pod_name": "flat-earth",
+    "pod": {
+      "creation_timestamp": "2024-06-08T11:14:00+02:00",
+      "scheduled_timestamp": "2024-06-08T11:14:00+02:00",
+      "creation_to_scheduled_seconds": 0,
+      "initialized_timestamp": "2024-06-08T11:14:01+02:00",
+      "creation_to_initialized_seconds": 1,
+      "scheduled_to_initialized_seconds": 1,
+      "ready_timestamp": "2024-06-08T11:14:02+02:00",
+      "creation_to_ready_seconds": 2,
+      "initialized_to_ready_seconds": 1
+    }
+  },
+  "time": "2024-06-08T11:14:06+02:00"
+}
+```
+
+A complete non-init container record:
+```json
+{
+  "kube_transition_metrics": {
+    "type": "container",
+    "kube_namespace": "default",
+    "pod_name": "flat-earth",
+    "container": {
+      "name": "consipire",
+      "init_container": false,
+      "initialized_to_running_seconds": 2.785652,
+      "running_timestamp": "2024-06-08T11:14:02+02:00",
+      "started_timestamp": "2024-06-08T11:14:02+02:00",
+      "running_to_started_seconds": 0,
+      "ready_timestamp": "2024-06-08T11:14:02+02:00",
+      "running_to_ready_seconds": 0,
+      "started_to_ready_seconds": 0
+    }
+  },
+  "time": "2024-06-08T11:14:06+02:00"
+}
+```
+
+A complete init container record:
+```json
+{
+  "kube_transition_metrics": {
+    "type": "container",
+    "kube_namespace": "default",
+    "pod_name": "flat-earth",
+    "container": {
+      "name": "subliminal-messaging",
+      "init_container": true,
+      "ready_timestamp": "2024-06-08T11:14:01+02:00"
+    }
+  },
+  "time": "2024-06-08T11:14:06+02:00"
+}
+```
+
+An image pull record:
+```json
+{
+  "kube_transition_metrics": {
+    "type": "image_pull",
+    "image_pull": {
+      "container_name": "conspire",
+      "already_present": true,
+      "started_timestamp": "2024-06-08T11:14:01+02:00",
+      "finished_timestamp": "2024-06-08T11:14:01+02:00",
+      "duration_seconds": 0
+    },
+    "kube_namespace": "default",
+    "pod_name": "flat-earth"
+  },
+  "time": "2024-06-08T11:14:01+02:00",
+  "message": "Container image \"docker.io/library/nginx:latest\" already present on machine"
+}
+```
+
+For a detailed overview of available metrics, see [doc/SCHEMA.md](doc/SCHEMA.md).
 
 ## Contributing
 

cmd/kube-transition-metrics/main.go

@@ -6,12 +6,11 @@ import (
 	_ "net/http/pprof"
 	"os"
 
+	"github.com/BackMarket-oss/kube-transition-metrics/internal/logging"
 	"github.com/BackMarket-oss/kube-transition-metrics/internal/options"
 	"github.com/BackMarket-oss/kube-transition-metrics/internal/prommetrics"
 	"github.com/BackMarket-oss/kube-transition-metrics/internal/statistics"
-	"github.com/BackMarket-oss/kube-transition-metrics/internal/zerologhttp"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
-	"github.com/rs/zerolog"
 	"github.com/rs/zerolog/log"
 	"k8s.io/client-go/kubernetes"
 	"k8s.io/client-go/rest"
@@ -61,10 +60,11 @@ func getKubeconfig(options *options.Options) *rest.Config {
 }
 
 func main() {
+	logging.Configure()
 	prommetrics.Register()
 
 	options := options.Parse()
-	zerolog.SetGlobalLevel(options.LogLevel)
+	logging.SetOptions(options)
 
 	config := getKubeconfig(options)
 	clientset, err := kubernetes.NewForConfig(config)
@@ -80,7 +80,7 @@ func main() {
 	go podCollector.Run(clientset)
 
 	http.Handle("/metrics", promhttp.Handler())
-	handler := zerologhttp.NewHandler(http.DefaultServeMux)
+	handler := logging.NewHTTPHandler(http.DefaultServeMux)
 	// No timeouts can be set, but that's OK for us as this HTTP server will not be
 	// exposed publicly.
 	//nolint:gosec